DEV Community

cazgp for Zaptic

Posted on

How To: GitLab and Docker Registry

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
  • 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 \

$ curl -fsSL | sudo apt-key add -

$ sudo apt-key fingerprint 0EBFCD88

$ sudo add-apt-repository \
 "deb [arch=amd64] \
 $(lsb_release -cs) \

$ sudo apt-get update

$ sudo apt-get install docker-ce
Enter fullscreen mode Exit fullscreen mode

Verify that docker installed properly:

$ sudo docker run hello-world
Enter fullscreen mode Exit fullscreen mode

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 ''
Enter fullscreen mode Exit fullscreen mode

Enable the registry in nginx:

registry_nginx['enable'] = true
registry_nginx['listen_port'] = 4567
Enter fullscreen mode Exit fullscreen mode

Also copy in the TLS certificate lines:

registry_nginx['ssl_certificate'] = "/path/to/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key"
Enter fullscreen mode Exit fullscreen mode

Save and reconfigure.

gitlab-ctl reconfigure
Enter fullscreen mode Exit fullscreen mode

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 :)

Top comments (5)

olistik profile image

Just a friendly reminder to check that the firewall on the remote host doesn't block the incoming TCP port 4567, like Digital Ocean do when you spin up a Gitlab droplet with their 1-click installer, otherwise you end up with a network error likenet/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers).
If this is the case, a simple sudo ufw allow 4567 will solve the problem.

madeinoz67 profile image
Stephen Eaton

Thanks for this, I’ve been scratching my head trying to get this working and didn’t realise I need docker installed on my local GitLab server until I came across this article. Thanks again!

eduardort profile image
Eduardo Reyes

Cool! I'm planning on doing this myself in the future, thanks for the guide :)

wonchaitanya profile image

I Appreciated your help which help to narrow down our issue , which struggle from lots of troubleshooting

Some comments may only be visible to logged-in visitors. Sign in to view all comments.