GitLab Container Registry administration

With the GitLab Container Registry, every project can have its own space to store Docker images.

Read more about the Docker Registry in the Docker documentation.

This document is the administrator’s guide. To learn how to use the GitLab Container Registry, see the user documentation.

Enable the Container Registry

Omnibus GitLab installations

If you installed GitLab by using the Omnibus installation package, the Container Registry may or may not be available by default.

The Container Registry is automatically enabled and available on your GitLab domain, port 5050 if:

Otherwise, the Container Registry is not enabled. To enable it:

The Container Registry works under HTTPS by default. You can use HTTP but it’s not recommended and is beyond the scope of this document. Read the insecure Registry documentation if you want to implement this.

Installations from source

If you have installed GitLab from source:

  1. You must install Registry by yourself.
  2. After the installation is complete, to enable it, you must configure the Registry’s settings in gitlab.yml.
  3. Use the sample NGINX configuration file from under lib/support/nginx/registry-ssl and edit it to match the host, port, and TLS certificate paths.

The contents of gitlab.yml are:

registry:
  enabled: true
  host: registry.gitlab.example.com
  port: 5005
  api_url: http://localhost:5000/
  key: config/registry.key
  path: shared/registry
  issuer: gitlab-issuer

Where:

Parameter Description
enabled true or false. Enables the Registry in GitLab. By default this is false.
host The host URL under which the Registry runs and users can use.
port The port the external Registry domain listens on.
api_url The internal API URL under which the Registry is exposed. It defaults to http://localhost:5000. Do not change this unless you are setting up an external Docker registry.
key The private key location that is a pair of Registry’s rootcertbundle. Read the token auth configuration documentation.
path This should be the same directory like specified in Registry’s rootdirectory. Read the storage configuration documentation. This path needs to be readable by the GitLab user, the web-server user and the Registry user. Read more in #configure-storage-for-the-container-registry.
issuer This should be the same value as configured in Registry’s issuer. Read the token auth configuration documentation.

A Registry init file is not shipped with GitLab if you install it from source. Hence, restarting GitLab does not restart the Registry should you modify its settings. Read the upstream documentation on how to achieve that.

At the absolute minimum, make sure your Registry configuration has container_registry as the service and https://gitlab.example.com/jwt/auth as the realm:

auth:
  token:
    realm: https://gitlab.example.com/jwt/auth
    service: container_registry
    issuer: gitlab-issuer
    rootcertbundle: /root/certs/certbundle
caution
If auth is not set up, users can pull Docker images without authentication.

Container Registry domain configuration

There are two ways you can configure the Registry’s external domain. Either:

Because the Container Registry requires a TLS certificate, cost may be a factor.

Take this into consideration before configuring the Container Registry for the first time.

Configure Container Registry under an existing GitLab domain

If the Registry is configured to use the existing GitLab domain, you can expose the Registry on a port. This way you can reuse the existing GitLab TLS certificate.

If the GitLab domain is https://gitlab.example.com and the port to the outside world is 5050, here is what you need to set in gitlab.rb or gitlab.yml if you are using Omnibus GitLab or installed GitLab from source respectively.

Ensure you choose a port different than the one that Registry listens to (5000 by default), otherwise conflicts occur.

note
Host and container firewall rules must be configured to allow traffic in through the port listed under the registry_external_url line, rather than the port listed under gitlab_rails['registry_port'] (default 5000).

Omnibus GitLab installations

  1. Your /etc/gitlab/gitlab.rb should contain the Registry URL as well as the path to the existing TLS certificate and key used by GitLab:

    registry_external_url 'https://gitlab.example.com:5050'

    The registry_external_url is listening on HTTPS under the existing GitLab URL, but on a different port.

    If your TLS certificate is not in /etc/gitlab/ssl/gitlab.example.com.crt and key not in /etc/gitlab/ssl/gitlab.example.com.key uncomment the lines below:

    registry_nginx['ssl_certificate'] = "/path/to/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key"

  2. Save the file and reconfigure GitLab for the changes to take effect.

  3. Validate using:

    openssl s_client -showcerts -servername gitlab.example.com -connect gitlab.example.com:5050 > cacert.pem

If your certificate provider provides the CA Bundle certificates, append them to the TLS certificate file.

An administrator may want the container registry listening on an arbitrary port such as 5678. However, the registry and application server are behind an AWS application load balancer that only listens on ports 80 and 443. The administrator may simply remove the port number for registry_external_url, so HTTP or HTTPS is assumed. Then, the rules apply that map the load balancer to the registry from ports 80 or 443 to the arbitrary port. This is important if users rely on the docker login example in the container registry. Here’s an example:

registry_external_url 'https://registry-gitlab.example.com'
registry_nginx['redirect_http_to_https'] = true
registry_nginx['listen_port'] = 5678

Installations from source

  1. Open /home/git/gitlab/config/gitlab.yml, find the registry entry and configure it with the following settings:

    registry:
  enabled: true
  host: gitlab.example.com
  port: 5050
  2. Save the file and restart GitLab for the changes to take effect.
  3. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).

Users should now be able to sign in to the Container Registry with their GitLab credentials using:

docker login gitlab.example.com:5050

Configure Container Registry under its own domain

When the Registry is configured to use its own domain, you need a TLS certificate for that specific domain (for example, registry.example.com). You might need a wildcard certificate if hosted under a subdomain of your existing GitLab domain, for example, registry.gitlab.example.com.

As well as manually generated SSL certificates (explained here), certificates automatically generated by Let’s Encrypt are also supported in Omnibus installs.

Let’s assume that you want the container Registry to be accessible at https://registry.gitlab.example.com.

Omnibus GitLab installations

  1. Place your TLS certificate and key in /etc/gitlab/ssl/registry.gitlab.example.com.crt and /etc/gitlab/ssl/registry.gitlab.example.com.key and make sure they have correct permissions:

    chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.*

  2. After the TLS certificate is in place, edit /etc/gitlab/gitlab.rb with:

    registry_external_url 'https://registry.gitlab.example.com'

    The registry_external_url is listening on HTTPS.

  3. Save the file and reconfigure GitLab for the changes to take effect.

If you have a wildcard certificate, you must specify the path to the certificate in addition to the URL, in this case /etc/gitlab/gitlab.rb looks like:

registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"

Installations from source

  1. Open /home/git/gitlab/config/gitlab.yml, find the registry entry and configure it with the following settings:

    registry:
  enabled: