How to use your own Registry

Jul 19 2013

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:

# Pull the ubuntu base image:
docker pull ubuntu

# Push the Hipache image (if you're samalba!)
docker push samalba/hipache

Implicitly that push and pull each access the Central Registry at, 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:

# First, make sure you have the "ubuntu" repository:
docker pull ubuntu

# Then, find the image id that corresponds to the ubuntu repository
docker images | grep ubuntu | grep latest
ubuntu  latest  8dbd9e392a96  12 weeks ago  263 MB (virtual 263 MB)

# Almost there!
# Tag to create a repository with the full registry location.
# The location becomes a permanent part of the repository name.
docker tag 8dbd9e392a96 localhost.localdomain:5000/ubuntu

# Finally, push the new repository to its home location.
docker push localhost.localdomain:5000/ubuntu

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:

git clone
cd docker-registry
cp config_sample.yml config.yml
pip install -r requirements.txt
gunicorn --access-logfile - --log-level debug --debug 
    -b -w 1 wsgi:application

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


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


14 thoughts on “How to use your own Registry

  1. 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
    Email ():
    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.

  2. I encountered problem installing docker-retistry when I issue the command (at Mac Yosemite)
    pip install -r requirements/main.txt (couldn’t find the file requirements.txt)
    swig -python -I/System/Library/Frameworks/Python.framework/Versions/2.7/include/python2.7 -I/usr/include -I/usr/include/openssl -includeall -modern -o SWIG/_m2crypto_wrap.c SWIG/_m2crypto.i

    :3: Error: Unable to find ‘python.swg’

    error: command ‘swig’ failed with exit status 1

  3. Currently trying to set up my own docker registry on Ubuntu 14.04 LTS. After sorting out the errors in the snippet above, I find myself in a dead end. Even if it’s not mentioned I assume I must use python3 (using python2 thows a “pyconfig.h” compilation error when pip-installing the required modules). However, module M2Crypto, required from requirements/main.txt has not been ported to Python3.

    What can I do? Anyone else has met problems when pip-installing the requirements?

  4. I’ve got the registry installed (docker-registry 1.1.0 from GitHub), but when I start it I get an error related to missing docker_registry.core package:

    Traceback (most recent call last):
    File “/usr/local/lib/python2.7/dist-packages/gunicorn/”, line 507, in spawn_worker
    File “/usr/local/lib/python2.7/dist-packages/gunicorn/workers/”, line 114, in init_process
    self.wsgi =
    File “/usr/local/lib/python2.7/dist-packages/gunicorn/app/”, line 66, in wsgi
    self.callable = self.load()
    File “/usr/local/lib/python2.7/dist-packages/gunicorn/app/”, line 65, in load
    return self.load_wsgiapp()
    File “/usr/local/lib/python2.7/dist-packages/gunicorn/app/”, line 52, in load_wsgiapp
    return util.import_app(self.app_uri)
    File “/usr/local/lib/python2.7/dist-packages/gunicorn/”, line 356, in import_app
    File “/home/ecejjar/git/docker-registry/docker_registry/”, line 19, in
    from .app import app # noqa
    File “/home/ecejjar/git/docker-registry/docker_registry/”, line 8, in
    from . import toolkit
    File “/home/ecejjar/git/docker-registry/docker_registry/”, line 18, in
    from docker_registry.core import compat
    ImportError: No module named core

    I’ve checked the docker_registry folder and there’s no core package or module in it. Has anybody else met this problem?

  5. Avatar for Sam Alba

    Daniel @ Status Page

    Hi Sam,

    Thank you for sharing this detailed information it helped me a lot.

  6. raise HaltServer(reason, self.WORKER_BOOT_ERROR)

    How can I fix this issue?

  7. There's Registry 2.0 which is apparently required in case you are using Docker 1.6.0 or above.

    More info:

  8. Hi buddy,

    Great post!

    Do you know how to make my own registry implicit in my setup?
    I don't want to be typing it before the images names all the time.

    Reason: migration from to local private repo.

    Thanks a lot!

  9. Great article. "You’ll also need the Docker registry code." is pointing to deprecated code

Leave a Reply