Skip to content

Commit

Permalink
Issue sameersbn#1118 Update docs for registry container
Browse files Browse the repository at this point in the history
  • Loading branch information
@mikehaertl
mikehaertl committed Nov 10, 2017
1 parent 37d0e1d commit 479dcb8
Showing 1 changed file with 135 additions and 132 deletions.
267 changes: 135 additions & 132 deletions docs/container_registry.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
GitLab Container Registry
=========================
Since `8.8.0` GitLab introduces container registry. GitLab is helping to authenticate the user against the registry and proxy it via NGINX. If we are talking about [Registry](https://docs.docker.com/registry) we are meaning the registry from docker and Container Registry is the feature of GitLab.
Since `8.8.0` GitLab introduces a container registry. GitLab is helping to authenticate the user against the registry and proxy it via Nginx. By [Registry](https://docs.docker.com/registry) we mean the registry from docker whereas *Container Registry* is the feature in GitLab.

- [Prerequisites](#prerequisites)
- [Available Parameters](#available-parameters)
- [Installation](#installation)
- [Configuration](#configuration)
- [Maintenance](#maintenance)
- [Creating Backups](#creating-backups)
- [Restoring Backups](#restoring-backups)
Expand All @@ -16,7 +16,138 @@ Since `8.8.0` GitLab introduces container registry. GitLab is helping to authent
- [Docker GitLab](https://github.com/sameersbn/docker-gitlab) >= 8.8.5-1


# Available Parameters
# Installation

## Setup with Nginx as Reverse Proxy

We assume that you already have Nginx installed on your host system and that
you use a reverse proxy configuration to connect to your GitLab container.

In this example we use a dedicated domain for the registry. The URLs for
the GitLab installation and the registry are:

* git.example.com
* registry.example.com

> Note: You could also run everything on the same domain and use different ports
> instead. The required configuration changes below should be straightforward.
### Create auth tokens

GitLab needs a certificate ("auth token") to talk to the registry API. The
tokens must be provided in the `/certs` directory of your container. You could
use an existing domain ceritificate or create your own with a very long
lifetime like this:

```bash
mkdir certs
cd certs
openssl req -new -newkey rsa:4096 > registry.csr
openssl rsa -in privkey.pem -out registry.key
openssl x509 -in registry.csr -out registry.crt -req -signkey registry.key -days 10000
```

It doesn't matter which details (domain name, etc.) you enter during key
creation. This information is not used at all.


### Update docker-compose.yml

First add the configuration for the registry container to your `docker-compose.yml`.

```yaml
registry:
image: registry
restart: always
expose:
- "5000"
ports:
- "5000:5000"
volumes:
- ./gitlab/shared/registry:/registry
- ./certs:/certs
environment:
- REGISTRY_LOG_LEVEL=info
- REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/registry
- REGISTRY_AUTH_TOKEN_REALM=https://git.example.de/jwt/auth
- REGISTRY_AUTH_TOKEN_SERVICE=container_registry
- REGISTRY_AUTH_TOKEN_ISSUER=gitlab-issuer
- REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE=/certs/registry.crt
- REGISTRY_STORAGE_DELETE_ENABLED=true
```
> **Important:**
>
> 1. Don't change `REGISTRY_AUTH_TOKEN_SERVICE`. It must have
> `container_registry` as value.
> 2. `REGISTRY_AUTH_TOKEN_REALM` must look like
> `https://git.example.com/jwt/auth`. So the endpoint must be `/jwt/auth`.
>
> These configuration options are required by the GitLab Container Registry.

Then update the `volumes` and `environment` sections of your `gitlab` container:

```yaml
gitlab:
environment:
# ...
# Registry
- GITLAB_REGISTRY_ENABLED=true
- GITLAB_REGISTRY_HOST=registry.example.de
- GITLAB_REGISTRY_PORT=443
- GITLAB_REGISTRY_API_URL=http://registry:5000
- GITLAB_REGISTRY_KEY_PATH=/certs/registry.key
volumes:
- ./gitlab:/home/git/data
- ./certs:/certs
```

### Nginx Site Configuration

```nginx
server {
root /dev/null;
server_name registry.example.de;
charset UTF-8;
access_log /var/log/nginx/registry.example.de.access.log;
error_log /var/log/nginx/registry.example.de.error.log;
# Set up SSL only connections:
listen *:443 ssl http2;
ssl_certificate /etc/letsencrypt/live/registry.example.de/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/registry.example.de/privkey.pem;
ssl_ciphers 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:ECDHE-RSA-DES-CBC3-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4';
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_session_cache builtin:1000 shared:SSL:10m;
ssl_session_timeout 5m;
client_max_body_size 0;
chunked_transfer_encoding on;
location / {
proxy_set_header Host $http_host; # required for docker client's sake
proxy_set_header X-Real-IP $remote_addr; # pass on real client's IP
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 900;
proxy_pass http://localhost:5000;
}
}
server {
listen *:80;
server_name registry.example.com;
server_tokens off; ## Don't show the nginx version number, a security best practice
return 301 https://$http_host:$request_uri;
}
```

# Configuration

## Available Parameters

Here is an example of all configuration parameters that can be used in the GitLab container.

Expand Down Expand Up @@ -63,134 +194,6 @@ gitlab:
- GITLAB_REGISTRY_ISSUER=gitlab-issuer
...
```
# Installation

Starting a fresh installation with GitLab Container registry would be like the `docker-compose` file.

## Docker Compose

This is an example with a registry and filesystem as storage driver.

```yml
version: '2'
services:
redis:
restart: always
image: sameersbn/redis:latest
command:
- --loglevel warning
volumes:
- ./redis:/var/lib/redis:Z
postgresql:
restart: always
image: sameersbn/postgresql:9.6-2
volumes:
- ./postgresql:/var/lib/postgresql:Z
environment:
- DB_USER=gitlab
- DB_PASS=password
- DB_NAME=gitlabhq_production
- DB_EXTENSION=pg_trgm
gitlab:
restart: always
image: sameersbn/gitlab:10.1.2
depends_on:
- redis
- postgresql
ports:
- "10080:80"
- "10022:22"
volumes:
- ./gitlab:/home/git/data:Z
- ./logs:/var/log/gitlab
- ./certs:/certs
environment:
- DEBUG=false
- DB_ADAPTER=postgresql
- DB_HOST=postgresql
- DB_PORT=5432
- DB_USER=gitlab
- DB_PASS=password
- DB_NAME=gitlabhq_production
- REDIS_HOST=redis
- REDIS_PORT=6379
- GITLAB_SSH_PORT=10022
- GITLAB_PORT=10080
- GITLAB_HOST=gitlab.example.com
- GITLAB_SECRETS_DB_KEY_BASE=superrandomsecret
- GITLAB_REGISTRY_ENABLED=true
- GITLAB_REGISTRY_HOST=registry.gitlab.example.com
- GITLAB_REGISTRY_PORT=5000
- GITLAB_REGISTRY_API_URL=http://registry:5000
- GITLAB_REGISTRY_CERT_PATH=/certs/registry-auth.crt
- GITLAB_REGISTRY_KEY_PATH=/certs/registry-auth.key
- SSL_REGISTRY_KEY_PATH=/certs/registry.key
- SSL_REGISTRY_CERT_PATH=/certs/registry.crt
registry:
restart: always
image: registry:2.4.1
volumes:
- ./gitlab/shared/registry:/registry
- ./certs:/certs
environment:
- REGISTRY_LOG_LEVEL=info
- REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/registry
- REGISTRY_AUTH_TOKEN_REALM=http://gitlab.example.com:10080/jwt/auth
- REGISTRY_AUTH_TOKEN_SERVICE=container_registry
- REGISTRY_AUTH_TOKEN_ISSUER=gitlab-issuer
- REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE=/certs/registry-auth.crt
- REGISTRY_STORAGE_DELETE_ENABLED=true
```
> **Important Notice**
>
> 1. Don't change `REGISTRY_AUTH_TOKEN_SERVICE`. It must have `container_registry` as value.
> 2. `REGISTRY_AUTH_TOKEN_REALM` need to be look like `http/s://gitlab.example.com/jwt/auth`. Endpoint must be `/jwt/auth`
> These configuration options are required by the GitLab Container Registry.


## Generating certificate for authentication with the registry

So GitLab handles for us the authentication with Registry we need an certificate to do that secure.
With have here two options:

1. Use a signed certificate from an Trusted Certificate Authority.
2. Self-Signed Certificate for the authentication process.

### Signed Certificate
If you have a signed certificate from a Trusted Certificate Authority you need only to copy the files in then `certs` folder and mount the folder in both containers (gitlab,registry) like in the docker-compose example.
After that you need to set an environment variable in each container.
In the **GitLab Container** you need to set `GITLAB_REGISTRY_KEY_PATH` this is the private key of the signed certificate.
In the **Registry Container** you need to set `REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE` to the certificate file of the signed certificate.
For more info read [token auth configuration documentation][token-config].

### Self Signed Certificate

Generate a self signed certificate with openssl.

- **Step 1**: Create a certs dir
```bash
mkdir certs && cd certs
```

- **Step 2**: Generate a private key and sign request for the private key
```bash
openssl req -nodes -newkey rsa:4096 -keyout registry-auth.key -out registry-auth.csr -subj "/CN=registry.example.com"
```

- **Step 3**: Sign your created privated key
```bash
openssl x509 -in registry-auth.csr -out registry-auth.crt -req -signkey registry-auth.key -days 3650
```

After this mount the `certs` dir in both containers and set the same environment variables like way of the signed certificate.

A complete docker-compose file is found here: [docker-compose-registry.yml](docker-compose-registry.yml)

## Container Registry storage driver

Expand Down Expand Up @@ -285,7 +288,7 @@ docker run --name gitlab -it --rm [OPTIONS] \
```
## Restoring Backups

Gitlab also defines a rake task to restore a backup.
GitLab also defines a rake task to restore a backup.

Before performing a restore make sure the container is stopped and removed to avoid container name conflicts.

Expand Down

0 comments on commit 479dcb8

Please sign in to comment.