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

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:

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:

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

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:

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!

The following two tabs change content below.

Adrian Mouat

Adrian Mouat is Chief Scientist at Container Solutions and the author of the O'Reilly book "Using Docker". He has been a professional software developer for over 10 years, working on a wide range of projects from small webapps to large data mining platforms.

Latest posts by Adrian Mouat (see all)

4 Comments

  1. Hi Adrian,
    thanks for you in detail article. This has already helped a lot.
    We have one small problem. We use private key client authentication with our enterprise docker registry. Therefor in /etc/docker/certs.d/test-docker-reg\:5000/ is also a .key file. Do you know how to use this auth with mac os?

Leave a Reply

Your email address will not be published. Required fields are marked *