Apr 14

Good Practices for Configuring Docker Private Registries

Private registries can be very helpful when using Docker — particularly if you’re wanting to be able to share code locally without either making it public or incurring the cost of a round trip. This post presents some practices which I think make life easier when using a Private Registry.

Where to look

Docker recognizes that an image is on a private registry when any of the following conditions occur:

  • An explicit port is specified in the image name, such as registry:5000/foobar.
  • An IP address is used, such as or
  • A fully qualified domain name (FQDN), such as registry.nimblestrat.us or registry.local

By default, the registry port is 5000. By adhering to convention, it’s easy to look at an image and tell that it is coming from a private location. However, it’s extra typing and more to remember. I prefer using a FQDN and having the registry bind to port 80 — the name, assuming that the host has a good name (or CNAME record) such as registry.foo.bar.

How to use a private registry

In order to place an image into a private registry, you must first tag it with a name in which you have specified the location of the registry.

Each of these examples would work (assuming that a registry is bound to the IP/Port):

  • docker tag a1b2c3d4e5f6
  • docker tag a1b2c3d4e5f6 registry.foo.bar/gnomovision

However, the following wouldn’t work for pushing an image to a private registry:

  • docker tag a1b2c3d4e5f6 gnomovision — mere mortals cannot “bless” an image and make it part of the “Official Repositories”
  • docker tag a1b2c3d4e5f6 registry/gnomovision — in this case, it considers registry to be a userid for the Docker Hub. There is not enough information to tell it that you’re trying to send it to a host named registry.

Recommended Practices

  1. Either name a host registry or, better yet, use a CNAME record to alias a host as registry. That way you don’t have to remember that xyz.pdq.io is the registry.
  2. Bind to the HTTP port.
  3. Where possible, use authentication. Since my major use case is with Swarm and it does not as yet support authentication, I am investigating other means, such as only allowing connections from a local network. Socketplane is an option, too — have the registry listening on a private network address. Neither is perfect, but for the moment….

I’d love to hear what other folk think — are there practices which you use?

Leave a Reply

%d bloggers like this: