From 479dcb84f480fd5ae48f7312d8e5b7a79412d9ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20H=C3=A4rtl?= Date: Fri, 10 Nov 2017 08:30:35 +0100 Subject: [PATCH] Issue #1118 Update docs for registry container --- docs/container_registry.md | 267 +++++++++++++++++++------------------ 1 file changed, 135 insertions(+), 132 deletions(-) diff --git a/docs/container_registry.md b/docs/container_registry.md index bc899f2a..dfc78f26 100644 --- a/docs/container_registry.md +++ b/docs/container_registry.md @@ -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) @@ -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. @@ -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 @@ -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.