Gitlab Docker Container Registry Configuration

For more information on Gitlab, visit


Gitlab is one of the leading GIT SCM solutions for code management with a varity of useability options such as using in the cloud, or by installing either their community or enterprise editions locally on your own network. In addition to the SCM itself, Gitlab bundles in a great CI product, and is starting to extend the platform even further with the new contianer registry that was bundled into Gitlab as of version 8.8. This article will go over setting up the container registry on a Gitlab CE instance.


1.    Gitlab:
Gitlab is already installed via the omnibus package on either a debian/ubuntu/rhel or centos machine (bare or virtual):

2.    Registry resolution:
Set a DNS entry resolving to the gitlab server, or set a host file entry on any docker hosts that will utilize the container registry, allowing the docker server to talk to the registry instance.

Set the host file in /etc/hosts registry

3.    Obtain or create a registry certificate:
For this walk through we are going to generate a self signed certificate on the gitlab server for the container registry service to use. As a substition to this step, a certificate can be issued from a local CA, or purchased through an SSL certificate vendor.

If Gitlab is installed on RHEL/CentOS, then the certificate directories are /etc/pki/tls/private and /etc/pki/tls/certs, If installed on Debian or Ubuntu, then the certificate directories are /etc/ssl/private and /etc/ssl/certs

Generate the Key:

RHEL   RHEL   &   CentOS   CentOS:

openssl genrsa -out "/etc/pki/tls/private/gitlab-registry.key" 4096

Debian   Debian   &   Ubuntu   Ubuntu:

openssl genrsa -out "/etc/ssl/private/gitlab-registry.key" 4096

Generate the Certificate:

RHEL   RHEL   &   CentOS   CentOS:

openssl req -x509 -sha512 -nodes -newkey rsa:4096 -days 730 -keyout /etc/pki/tls/private/gitlab-registry.key -out /etc/pki/tls/certs/gitlab-registry.crt

Debian   Debian   &   Ubuntu   Ubuntu:

openssl req -x509 -sha512 -nodes -newkey rsa:4096 -days 730 -keyout /etc/ssl/private/gitlab-registry.key -out /etc/ssl/certs/gitlab-registry.crt


This walk through assumes that Gitlab was installed using the Omnibus package. If gitlab was instead installed from source, then please visit for alternate instructions.

Edit /etc/gitlab/gitlab.rb

To configure the registry, a few options need to be set in the /etc/gitlab/gitlab.rb file. The options are as follows

registry_external_url ''

# Registry     #
gitlab_rails['registry_enabled'] = true
gitlab_rails['gitlab_default_projects_features_container_registry'] = false
gitlab_rails['registry_path'] = "/mnt/docker_registry"
gitlab_rails['registry_api_url'] = "https://localhost:5000"

# GitLab Nginx #
## see:

nginx['enable'] = true
# nginx['client_max_body_size'] = '250m'
nginx['ssl_client_certificate'] = "/etc/gitlab/ssl/ca.crt"
registry_nginx['ssl_certificate'] = "/etc/pki/tls/certs/gitlab-registry.crt"
registry_nginx['ssl_certificate_key'] = "/etc/pki/tls/private/gitlab-registry.key"
registry_nginx['proxy_set_headers'] = { "Host" => "" }

A brief description of the option settings above are as follows:

Option Description
registry_external_url The URL that the registry will listen on
gitlab_rails['registry_enabled'] Enable the contianer registry service
gitlab_rails['gitlab_default_projects_features_container_registry'] T/F setting for registry enabled on every project
gitlab_rails['registry_path'] Optional registry storage location
gitlab_rails['registry_api_url'] URL Gitlab will use to talk to the registry API
nginx['ssl_client_certificate'] = "/etc/gitlab/ssl/ca.crt" Tell Nginx to load the default CA root certificates
registry_nginx['ssl_certificate'] Path to the certificate that the registry is going to use
registry_nginx['ssl_certificate_key'] Path to the key for the certificate that the registry will use
registry_nginx['proxy_set_headers'] Workaround for an issue that should have been resolved in 8.10.2, but left in just to be safe

Reconfigure Gitlab

gitlab-ctl reconfigure

Restart Gitlab

gitlab-ctl restart

Post Requisites:

This step is only required if using a self signed certificate

In the event that you are using a self signed certificate, then the docker host has to either have the certificate imported so that its trusted, or docker will need to be made aware that the registry is insecure, or it will not be able to log into the new registry.

These steps should be performed on the Docker host that will use the Gitlab Container Registry

1.    SCP the certs:
The first step is from the gitlab server, scp the certificate only.. NOT THE KEY to the docker host

RHEL   RHEL   &   CentOS   CentOS:

scp /etc/pki/tls/certs/gitlab-registry.crt root@dockerhost:/tmp

Debian   Debian   &   Ubuntu   Ubuntu:

scp /etc/ssl/certs/gitlab-registry.crt root@dockerhost:/tmp

2.    Import the certs:

RHEL   RHEL   &   CentOS   CentOS:

mv /tmp/gitlab-registry.crt /etc/pki/ca-trust/source/anchors/

Debian   Debian   &   Ubuntu   Ubuntu:

mv /tmp/gitlab-registry.crt /usr/local/share/ca-certificates/

3.    Restart Docker:

systemctl restart docker.service

If for some reason it is undesirable to import the certificate, the docker flag DOCKER_OPTS="" can be added to the /etc/default/docker file, or directly to the docker daemon start script / unit file

4.    Docker Login:

docker login


Gitlab Documentation