Note:
The container registry works under HTTPS by default. Using HTTP is possible
but not recommended and out of the scope of this document.
Read the insecure Registry documentation if you want to
implement this.

Note:
A Registry init file is not shipped with GitLab if you install it from source.
Hence, restarting GitLab will 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:

Since the container Registry requires a TLS certificate, in the end it all boils
down to how easy or pricey is to get a new one.

Please 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 so that you can reuse the existing GitLab TLS
certificate.

Assuming that the GitLab domain is https://gitlab.example.com and the port the
Registry is exposed to the outside world is 4567, 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.

Note:
Be careful to choose a port different than the one that Registry listens to (5000 by default),
otherwise you will run into conflicts.

Omnibus GitLab installations

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:4567'

Note how 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:

Make the relevant changes in NGINX as well (domain, port, TLS certificates path).

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

docker login gitlab.example.com:4567

Configure Container Registry under its own domain

If the Registry is configured to use its own domain, you will need a TLS
certificate for that specific domain (e.g., registry.example.com) or maybe
a wildcard certificate if hosted under a subdomain of your existing GitLab
domain (e.g., registry.gitlab.example.com).

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

Omnibus GitLab installations

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.*

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

Disable Container Registry for new projects site-wide

If the Container Registry is enabled, then it will be available on all new
projects. To disable this function and let the owners of a project to enable
the Container Registry by themselves, follow the steps below.

Container Registry storage driver

You can configure the Container Registry to use a different storage backend by
configuring a different storage driver. By default the GitLab Container Registry
is configured to use the filesystem driver, which makes use of storage path
configuration.

Warning GitLab will not backup Docker images that are not stored on the
filesystem. Remember to enable backups with your object storage provider if
desired.

Important Enabling storage driver other than filesystem would mean
that your Docker client needs to be able to access the storage backend directly.
So you must use an address that resolves and is accessible outside GitLab server.

Change the registry's internal port

Note:
This is not to be confused with the port that GitLab itself uses to expose
the Registry to the world.

The Registry server listens on localhost at port 5000 by default,
which is the address for which the Registry server should accept connections.
In the examples below we set the Registry's port to 5001.

A certificate keypair is required for GitLab and the Container Registry to
communicate securely. By default omnibus-gitlab will generate one keypair,
which is saved to /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key.
When using a non-bundled Container Registry, you will need to supply a
custom certificate key. To do that, add the following to
/etc/gitlab/gitlab.rb

gitlab_rails['registry_key_path']="/custom/path/to/registry-key.key"# registry['internal_key'] should contain the contents of the custom key# file. Line breaks in the key file should be marked using `\n` character# Example:registry['internal_key']="---BEGIN RSA PRIVATE KEY---\nMIIEpQIBAA\n"

Note: The file specified at registry_key_path gets populated with the
content specified by internal_key, each time reconfigure is executed. If
no file is specified, omnibus-gitlab will default it to
/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key and will populate
it.

Troubleshooting

Using self-signed certificates with Container Registry

If you're using a self-signed certificate with your Container Registry, you
might encounter issues during the CI jobs like the following:

Error response from daemon: Get registry.example.com/v1/users/: x509: certificate signed by unknown authority

The Docker daemon running the command expects a cert signed by a recognized CA,
thus the error above.

While GitLab doesn't support using self-signed certificates with Container Registry out of the box, it is possible to make it work by instructing the docker-daemon to trust the self-signed certificates, mounting the docker-daemon and setting privileged = false in the runner's config.toml. Setting privileged = true takes precedence over the docker-daemon.