Docker images are stored in a docker registry (by default “Docker Hub registry”). This allows you to use or build from existing images. Images published to Docker Hub registry are public. In some cases you want your images to be private. To do this, you will need to setup a private docker registry. For my use case I will be discussing setting up a remote private registry backed by S3


1. Launch a host to serve the docker registry

We chose a public CoreOS AMI for our base image on a t2.micro instance. After the host boots, we connect to it through SSH and start the remote registry using:

$ docker run -d -t --name docker-registry -p 5000:5000 \
  -e AWS_BUCKET=docker-registry \
  -e STORAGE_PATH=/registry \
  -e SEARCH_BACKEND=sqlalchemy registry

This launches a “docker-registry” image and names it “registry”. The AWS_KEY and AWS_SECRET variables are used to authenticate against S3. The bucket “docker-registry” was pre-created. The service is accessible on port 5000 on the host, so we will need to punch a hole in our firewall (security group) to allow traffic coming from my host. We will also assume that this host has the DNS name


2. Automatically start when server boots

Add a file called registry.service to the /etc/systemd/system directory:

Description=Docker Registry

ExecStartPre=-/usr/bin/docker kill registry
ExecStartPre=-/usr/bin/docker rm registry
ExecStartPre=/usr/bin/docker pull registry:0.9.1
ExecStart=/usr/bin/docker run --name registry -p 5000:5000 -e SETTINGS_FLAVOR=s3 -e AWS_BUCKET=upnxt-docker-registry -e STORAGE_PATH=/registry -e AWS_KEY=$AWS_ACCESS_KEY_ID -e AWS_SECRET=$AWS_SECRET_ACCESS_KEY -e AWS_REGION=eu-west-1 -e SEARCH_BACKEND=sqlalchemy registry:0.9.1


Then enable the service to start at reboot

# systemctl daemon-reload
# systemctl enable registry
# systemctl start registry
# systemctl status registry.service


3. Install docker

Installing docker is just downloading the binary image to /usr/local/bin and making it executable

$ curl -o /usr/local/bin/docker
$ chmod +x /usr/local/bin/docker

Note: make sure you use the correct binary (here: mac osx)


4. Launch docker-machine

On Mac and Windows you need to run a VM to run the docker agent since it can’t run natively. I kindof like the setup so would probably use it too on a Linux host, just to keep it separated from the rest of the system. To create/launch such a VM, you will need to download and install a tool called docker-machine

$ curl -L -o /usr/local/bin/docker-machine
$ chmod +x /usr/local/bin/docker-machine

To launch the actual VM:

$ docker-machine create -d virtualbox dev
$ eval “$(docker-machine env dev)"

At this point the docker agent is running and waiting for client requests

Since the default docker agent tries to connect to the docker registry over TLS and we have not set it up, we will tell it to allow insecure connections to our docker registry by adding the “–insecure-registry” flag to the EXTRA_ARGS in the /var/lib/boot2docker/profile file:

$ docker-machine ssh dev
$ sudo vi /var/lib/boot2docker/profile
EXTRA_ARGS="... --insecure-registry"
$ sudo /etc/init.d/docker restart


5. Test the registry

To test whether your registry is setup correctly, you should now be able to

$ docker search