Local Docker Registry

16 Nov 2018

In an upcoming article, I will set up a local registry for Docker Swarm so every node on the swarm will be using the same image, even when working offline - or one can have their own secret images in the swarm!

Clothesping by Claes Oldenburg

This article will go over how to work with Docker registry locally.

With the local registry, how to:

run it
check for stored images
tag image for pushing
push image
pull image

I will also go over what happens when the registry is not running.

Requirements

If you would like to follow along, please:

Install Virtualbox
Install vagrant
Download this Vagrantfile to your local folder and modify this line:
Run $ vagrant up manager - which will create a virtualbox with necessary software
login using $ vagrant ssh manager

All the following commands are from within this computing environment.

Run a Local Registry

After logging into the manager node, let’s get the registry

vagrant@manager:/vagrant$ sudo docker pull registry
Using default tag: latest
latest: Pulling from library/registry
d6a5679aa3cf: Already exists
ad0eac849f8f: Already exists
2261ba058a15: Already exists
f296fda86f10: Already exists
bcd4a541795b: Already exists
Digest: sha256:5a156ff125e5a12ac7fdec2b90b7e2ae5120fa249cf62248337b6d04abc574c8
Status: Downloaded newer image for registry:latest

And get the registry running with command:

vagrant@manager:/vagrant$ sudo docker run -d -p 5000:5000 registry
9548b741f8129e36ad6efd1f4e6805ecbe1dcbb786236f4fd7de03b2ad28da44
vagrant@manager:/vagrant$ sudo docker ps
CONTAINER ID        IMAGE                     COMMAND                  CREATED             STATUS              PORTS                    NAMES
9548b741f812        registry                  "/entrypoint.sh /etc…"   9 minutes ago       Up 9 minutes        0.0.0.0:5000->5000/tcp   admiring_turing

Interacting with the Local Registry

Test the local registry using curl commands: curl localhost:5000/v2/_catalog

vagrant@manager:/vagrant$ curl localhost:5000/v2/_catalog
{"repositories":[]}

Awesome, this means the local registry is working and there’s nothing in its repository.

Push image to Local Registry

Let’s take an existing image, the nginx image, retag it for the local registry and push it with the following commands:

docker tag <image name> <host/new image name>
docker push <host/new image name>

vagrant@manager:~$ sudo docker tag nginx localhost:5000/nginx-v1
vagrant@manager:~$ sudo docker images
REPOSITORY                 TAG                 IMAGE ID            CREATED             SIZE
nginx                      latest              be1f31be9a87        6 weeks ago         109MB
localhost:5000/nginx-v1    latest              be1f31be9a87        6 weeks ago         109MB
registry                   <none>              2e2f252f3c88        2 months ago        33.3MB
vagrant@manager:~$ sudo docker push localhost:5000/nginx-v1
The push refers to repository [localhost:5000/nginx-v1]
92b86b4e7957: Pushed
94ad191a291b: Pushed
8b15606a9e3e: Pushed
latest: digest: sha256:204a9a8e65061b10b92ad361dd6f406248404fe60efd5d6a8f2595f18bb37aad size: 948

Let’s check what the local registry says now:

vagrant@manager:/vagrant$ curl localhost:5000/v2/_catalog
{"repositories":["nginx-v1"]}

Great, the new image, nginx-v1 is on the local repository.

Removing Local Docker Image

Now, let’s test out how the Local Registry can work. If you can, disable networking to your computer for the next steps as you follow along. This is what will happen:

remove the local image that’s also on the local repository (in this case, it’s localhost:5000/nginx-v1), using command: docker rmi
start a container that uses the image on the local repository, which will be localhost:5000/nginx-v1, using command: docker run

vagrant@manager:/vagrant$ sudo docker images
REPOSITORY                 TAG                 IMAGE ID            CREATED             SIZE
localhost:5000/nginx-v1    latest              62f816a209e6        9 days ago          109MB
nginx                      latest              62f816a209e6        9 days ago          109MB
registry                   latest              2e2f252f3c88        2 months ago        33.3MB
vagrant@manager:/vagrant$ sudo docker rmi localhost:5000/nginx-v1
Untagged: localhost:5000/nginx-v1:latest
Untagged: localhost:5000/nginx-v1@sha256:427498d66ad8a3437939bb7ef613fe76458b550f6c43b915d8d4471c7d34a544
vagrant@manager:/vagrant$ sudo docker images
REPOSITORY                 TAG                 IMAGE ID            CREATED             SIZE
nginx                      latest              62f816a209e6        9 days ago          109MB
registry                   latest              2e2f252f3c88        2 months ago        33.3MB

Pulling from Local Registry

With the localhost:5000/nginx-v1 image removed from the manager machine, let’s pull from the local repository:

vagrant@manager:/vagrant$ sudo docker pull localhost:5000/nginx-v1
Using default tag: latest
latest: Pulling from nginx-v1
Digest: sha256:427498d66ad8a3437939bb7ef613fe76458b550f6c43b915d8d4471c7d34a544
Status: Downloaded newer image for localhost:5000/nginx-v1:latest
vagrant@manager:/vagrant$ sudo docker images
REPOSITORY                 TAG                 IMAGE ID            CREATED             SIZE
nginx                      latest              62f816a209e6        9 days ago          109MB
localhost:5000/nginx-v1    latest              62f816a209e6        9 days ago          109MB
registry                   latest              2e2f252f3c88        2 months ago        33.3MB

Now, this doesn’t seem so impressive, but if you were offline for these steps, it should be.

Why?

This means the local registry can serve any image that’s pushed to it, without a network connection.

For a single machine, it’s nothing, but when there’s networked machines that is only connected to a single repository, this can get pretty useful behind firewalls, VPC, etc.

Remove Local Registry

Now, stop the local registry container, using the docker stop command, this is what would happen after removing the local image:

vagrant@manager:/vagrant$ sudo docker images
REPOSITORY                 TAG                 IMAGE ID            CREATED             SIZE
localhost:5000/nginx-v1    latest              62f816a209e6        9 days ago          109MB
nginx                      latest              62f816a209e6        9 days ago          109MB
registry                   latest              2e2f252f3c88        2 months ago        33.3MB
vagrant@manager:/vagrant$ sudo docker rmi localhost:5000/nginx-v1
Untagged: localhost:5000/nginx-v1:latest
Untagged: localhost:5000/nginx-v1@sha256:427498d66ad8a3437939bb7ef613fe76458b550f6c43b915d8d4471c7d34a544
vagrant@manager:/vagrant$ sudo docker images
REPOSITORY                 TAG                 IMAGE ID            CREATED             SIZE
nginx                      latest              62f816a209e6        9 days ago          109MB
registry                   latest              2e2f252f3c88        2 months ago        33.3MB
vagrant@manager:/vagrant$ sudo docker ps
CONTAINER ID        IMAGE                     COMMAND                  CREATED             STATUS              PORTS                    NAMES
9548b741f812        registry                  "/entrypoint.sh /etc…"   9 minutes ago       Up 9 minutes        0.0.0.0:5000->5000/tcp   admiring_turing
vagrant@manager:/vagrant$ sudo docker stop admiring_turing
admiring_turing
vagrant@manager:/vagrant$ sudo docker ps
CONTAINER ID  IMAGE  COMMAND   CREATED   STATUS   PORTS  NAMES

Now without a localhost:5000/nginx-v1 image locally, and stopping the local registry container. Let’s see what happens when trying to run: docker pull localhost:5000/nginx-v1 like before:

vagrant@manager:/vagrant$ sudo docker pull localhost:5000/nginx-v1
Using default tag: latest
Error response from daemon: Get http://localhost:5000/v2/: dial tcp 127.0.0.1:5000: connect: connection refused

Wow, so the command: docker pull localhost:5000/nginx-v1 connects with the local repository.

Deleted Registry, Deleted Images

Beware: when stopping the local registry container, this will delete the images stored on the local registry.

Conclusion

We have gone over how to create a local Docker registry using the Docker registry image, testing it out via curl commands, pushing and pulling images to/from it and what happens when the registry is down.

Look for an upcoming article where I use the Docker Registry to help deploy images to each node on a Docker Swarm.