How to use your own Registry

One of the things that makes Docker so useful is how easy it is to pull ready-to-use images from a central location, Docker’s Central Registry. It is just as easy to push your own image (or collection of tagged images as a repository) to the same public registry so that everyone can benefit from your newly Dockerized service.

But sometimes you can’t share your repository with the world because it contains proprietary code or confidential information. Today we are introducing an easy way to share repositories on your own registry so that you can control access to them and still share them among multiple Docker daemons. You can decide if your registry is public or private.

You’ll need the latest version of Docker (>=0.5.0) to use this new feature, and you must run this version as both the daemon and the client. You’ll also need the Docker registry code.

Using Push and Pull

The default way of pushing and pulling repositories from the Central Registry has not changed:

Implicitly that push and pull each access the Central Registry at index.docker.io, so nothing has changed with the default behavior and all the examples still work.

Now the new feature! To push to or pull from your own registry, you just need to add the registry’s location to the repository name. It will look like my.registry.address:port/repositoryname.

Let’s say I want to push the repository “ubuntu” to my local registry, which runs on my local machine, on the port 5000:

Obviously, the push will fail if no registry server answer locally on the port 5000. We’ll briefly show how to start your own registry server at the end of this blog post.

It’s important to note that we’re using a domain containing a “.” here, i.e. localhost.domain. Docker looks for either a “.” (domain separator) or “:” (port separator) to learn that the first part of the repository name is a location and not a user name. If you just had localhost without either .localdomain or :5000 (either one would do) then Docker would believe that localhost is a username, as in localhost/ubuntu or samalba/hipache. It would then try to push to the default Central Registry. Having a dot or colon in the first part tells Docker that this name contains a hostname and that it should push to your specified location instead.

Install your Registry (on your server or locally)

Docker-Registry is a simple Python app, installing it is straight-forward:

Your Registry is now running on localhost (port 5000) in a development flavor and using local storage. Obviously, in a production environment, you might want to run the Registry on port 443 (or 80 on a local network) and make it accessible on a hostname like “registry.domain.tld”, and point it to use S3 or other storage.

About Sam Alba

sam

As dotCloud’s first engineering hire, Sam was part of the tiny team that shipped our first private beta in 2010. Since then, he has been instrumental in scaling the platform to tens of millions of unique visitors for tens of thousands of developers across the world, leaving his mark on every major feature and component along the way. Today, as dotCloud’s first director of engineering, he manages our fast-growing engineering team, which is another way to say he sits in meetings so that other engineers don’t have to. When not sitting in a meeting, he maintains several popular open-source projects, including Hipache and Cirruxcache and other projects also ending in “-ache”. In a previous life, Sam supported Fortune 500s at Akamai, built the web infrastructure at several startups, and wrote software for self-driving cars in a research lab at INRIA.

Connect with Sam on Twitter! @sam_alba

EmailFacebookTwitter

2 Responses to “How to use your own Registry”

  1. chris-rock

    Dear Sam, great article. I am a little bit confused with registry and index. On a fresh build it looks as follows

    docker push localhost.localdomain:5000/ubuntu
    Username (): user
    Password:
    Email (): user@pass.com
    2013/07/29 22:20:28 Error: Registration: "Password is too short (4), needs to be at least 5 characters"

    Do I need to set a registry? Where do I need to register?

    • Thatcher Peskens

      Hi Chris,
      You would do better off asking this type of question on IRC or StackOverflow. That being said. here it looks like you are prompted to create a user and password, but your input is too short.

Comments are closed.