Adding Self-signed Registry Certs to Docker & Docker for Mac

The Docker registry image has over 10 million pulls on Docker Hub, so it's safe to say that a lot of people out there are making use of it. When running a registry, it's essential to make sure your clients can access it easily and securely. If your registry isn't running on a public domain, you're probably using a self-signed certificate for this purpose. This post will look into some of the issues around accessing registries with self-signed certificates from clients, including Docker for Mac.

Distributing certificates to Linux Docker clients is pretty straightforward, as it just means copying the certificate to the correct directory (for the purposes of this post, I'm assuming you know how to create a self-signed cert for the registry):

sudo mkdir /etc/docker/certs.d/test-docker-reg\:5000
sudo cp ca.crt /etc/docker/certs.d/test-docker-reg\:5000/

With the Mac, however, things are a little different. The above solution doesn't work, as Docker for Mac relies on a internal VM whose filesystem gets wiped on restarts. The correct solution (thanks to Justin Cormack) is to add the certificate to the Mac's keychain, which will be picked up by Docker for Mac e.g:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt

You'll need to restart Docker for Mac for the change to take effect.

After this, on both Linux and Mac, you will probably need to make the registry address resolvable (if you're using a self-signed cert it probably means it's running on an internal network without a public domain name). A simple way to do this is to add an entry to /etc/hosts< e.g:

cat /etc/hosts
(out) test-docker-reg

And now you should be able to push and pull to the registry:

docker tag alpine:latest test-docker-reg:5000/test-image
docker push test-docker-reg:5000/test-image

As there's some non-obvious steps here, and it's a common problem, I've written a tool to do this as a one-liner on Linux or Mac:

sudo ./reg-tool.sh install-cert --cert-file ca.crt --reg-name test-docker-reg:5000 --add-host test-docker-reg
(out)Installing certificate
(out)Adding certificate to local machine...
(out)Exposing registry via /etc/hosts
(out)Successfully configured localhost

The registry tool also has options to retrieve the certificate from a URL or a Kubernetes secret. In addition it can automatically set-up a secure registry on Kubernetes, which will be the topic of a later post.

Please let us know if you find the tool useful!

Leave your Comment