How To: GitLab and Docker Registry

I (and one other engineer) spent rather too much time the other afternoon trying to work out how to set up a self-hosted Docker registry on a self-hosted GitLab site.

What we discovered (that the documentation really doesn't explain very well) is that GitLab becomes responsible for running the Docker registry and ensuring that it's accessible on whichever port you configure. That is, all you really need to do is to install Docker and change a couple of things in the GitLab config and everything happens like magic.

The Set-Up

• We assume that you have a self-hosted GitLab EE site somewhere, accessible by gitlab.example.com.
• We assume that this is on an Ubuntu (16.04) machine.
• We also assume that you want to set up a self-hosted Docker registry and that you know what that means.

The Solution

1. Install Docker on your GitLab server

Follow the instructions here to install Docker.

I'll copy out the commands to run to save you from the pain, but do check that link in case you don't know what any of these commands are doing.

$ sudo apt-get update

$ sudo apt-get install \
  apt-transport-https \
  ca-certificates \
  curl \
  software-properties-common

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

$ sudo apt-key fingerprint 0EBFCD88

$ sudo add-apt-repository \
 "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
 $(lsb_release -cs) \
 stable"

$ sudo apt-get update

$ sudo apt-get install docker-ce

Verify that docker installed properly:

$ sudo docker run hello-world

2. Make changes to GitLab config

The container docs say "All you have to do is configure the domain name under which the Container Registry will listen to. Read #container-registry-domain-configuration and pick one of the two options that fits your case."

Click on the link they provide and you reach here which says "There are two ways you can configure the Registry's external domain. Either use the existing GitLab domain where in that case the Registry will have to listen on a port and reuse GitLab's TLS certificate, or use a completely separate domain with a new TLS certificate for that domain."

What we are trying to do is use the existing GitLab domain name because -- how cool is this? -- Docker registry login with GitLab credentials!

So, click the link that takes us here.

... and it says "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."

So, to summarise. The docs say "configure the domain name [for] the Container Registry ... If the Registry is configured [with] the existing [domain name]". But they completely fail to tell you how to configure the domain name! This is the part that confused us a lot.

The missing link

We assume that you don't care what port you want to run Docker registry on, and so use 4567. If you do care, change that value.

Edit /etc/gitlab/gitlab.rb.

Find the line which contains registry_external_url and change it to:

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

Enable the registry in nginx:

registry_nginx['enable'] = true
registry_nginx['listen_port'] = 4567

Also copy in the TLS certificate lines:

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

Save and reconfigure.

gitlab-ctl reconfigure

GitLab will automatically open the ports up and allow you to login to the registry with docker login and your GitLab credentials / 2fa keys (if you use 2fa).

That should be it! Happy GitLabing :)