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!


  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?

  2. Hi Adrian,

    Thank you for the article on this issue. Do you have a link to the tool you created? I couldn’t find one within the article.

  3. Hi Adrian,
    Thank you for your article.
    I’m running docker on mac and having an issue with it.
    I used the security command to add the ca.crt, afterwards I restarted the docker application.
    then, when I’ve tried to docker-compose it fails with the error:
    x509: certificate signed by unknown authority
    any idea?
    Thanks in advanced

    • Hmm, I’m not sure.

      Where is the Docker engine running? If all your using is Docker for Mac, this should work, but it may have changed since the blog post was written.

      If you’re using a VM or something different, you’ll need to make sure the cert is in the VM.

      I don’t have a Mac any more, so it’s difficult for me to debug.

Leave a Reply

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