Running your own Docker Registry

(Last Updated On: July 4, 2018)

Running your own docker registry can be handy and secure if you just need to keep your docker containers somewhere safe and not out for the public to utilize.  In this post, I will walk you through setting up a docker registry on an Ubuntu Server system.


I created a rather small VM for this project which is just a 1×1 VM and 40GB of drive space.  I then installed Ubuntu Server 16.04 (although i am pretty sure it will work with Ubuntu Server 17.10 as well since Docker now supports it).  After installing all the updates you are ready to get started.

Creating a Docker Registry

Install Docker

The first step is to install Docker on your server.  Run the following commands to install Docker:

# curl -fsSL | sudo apt-key add -
# add-apt-repository "deb [arch=amd64] $(lsb_release -cs) stable"
# apt update
# apt install docker-ce

Generate TLS Certificates

We now need to generate some self-signed certificates.  If you have actual CA certs then you should use those.  If you don’t then run these commands to generate some self-signed certificates.  We will have to change the docker configuration a bit on your clients in order to push to this registry if that is the case.

# mkdir -p certs
# cd certs
# openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout registry-selfsigned.key -out registry-selfsigned.crt

Configuring the Docker Registry

Now that we have our certs generated we can start our on-premises docker registry.

# cd ..
# docker run -d --restart=always \
 --name registry -v `pwd`/certs:/certs \
 -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/registry-selfsigned.crt \
 -e REGISTRY_HTTP_TLS_KEY=/certs/registry-selfsigned.key \
 -p 443:443 \

We are not quite done yet though.  We need to configure our docker client to use an insecure registry (which is what we have if you used self-signed certs).

Setup Authentication

Now that we have TLS configured we need to setup authentication.  Create an auth directory.

# mkdir auth

Now we will use the registry container to generate a htpasswd file in the auth directory that will contain our username and password.  Be sure to replace username and password with the actual username and password you would like to use.

# docker run --entrypoint htpasswd registry:2 -Bbn username password > auth/htpasswd

This will save the htpasswd file in our auth directory that we just created.  Stop the registry if you still have it going:

# docker container stop registry

And start it up again but this time with the authentication parameters:

docker run -d --restart=always --name registry -v `pwd`/certs:/certs -v `pwd`/auth:/auth -e "REGISTRY_AUTH=htpasswd" -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd -e REGISTRY_HTTP_ADDR= -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/registry-selfsigned.crt -e REGISTRY_HTTP_TLS_KEY=/certs/registry-selfsigned.key -p 5000:5000 registry:2

Configuring an Insecure Registry

On your client system, edit /etc/docker/daemon.json and add this line:

{ "insecure-registries":["registry.example.lab:5000"] }

Restart the docker service.

# systemctl restart docker

Make sure to edit to use your registry server’s FQDN.

Pushing Images to your Docker Registry

Now we can login and push images to our registry.  First login:

# docker login registry.example.lab:5000

Enter the username and password you configured earlier.  Now pull a basic container down from Docker Hub, tag it with your registry and push the container to your registry with these commands:

#docker pull ubuntu:16.04
# docker tag ubuntu:16.04 registry.example.lab:5000/lab-ubuntu
# docker push registry.example.lab:5000/lab-ubuntu

You now have your local docker registry stood up and secured.


I hope you have enjoyed this article.  Click here for more of my articles on Docker.


I hope you have enjoyed this article, if so please leave a comment below.  For more articles, please signup for the AdminTome Blog below.  Also please feel free to share the article to your friends using the buttons to the left.  Thanks again for reading this post.


Leave a Comment

you're currently offline