setting up private docker registry: docker registry v2 and image upoad to docker registry v2

As title of this post states in text below we are going to describe process how to set up private docker registry and how to create custom docker image and then upload it to our newly created docker registry. We are going to use v2 Registry server for Docker.

You know what is docker… don’t you? If not then take some days of and start reading docker documentation you can find at docker web docker documentation

When it comes to docker registry, one can use docker hub registry, or some other provided by Linux vendor … If you do not want to use docker hub, and you use Linux version which is not officially vendor supported ( for example Fedora ), then you can create your own docker registry and push images there and thus have more control over it. Other reason for own/private docker registry can be that you have private / classified docker images ( eg, bank application running in container and processing client information ) which you want to keep “in house” without exposing them to third party locations.

v2 Docker registry main advantage over docker registry v1 is better API feature set and it is worth to invest time to learn how to deploy it. This post is short to write now about all docker registry v2 APIs and I recommend to read about API features Docker Registry HTTP API V2

In order use local docker registry, we have to install and configure it and afterwards be able to push images to it.
In process below we will describe docker registry process setup, and I am going to use Fedora rawhide as operating system,in your tests, you can use other Linux distribution than Fedora, but ensure it has docker-distribution package, or some name variation of it.
dnf info docker-distribution gives below info

# rpm -qi docker-distribution 
Name        : docker-distribution
Version     : 2.1.1
Release     : 4.fc24
Architecture: x86_64
Install Date: Fri 27 Nov 2015 11:20:18 AM CET
Group       : Unspecified
Size        : 11721281
License     : ASL 2.0
Signature   : RSA/SHA256, Wed 28 Oct 2015 03:18:18 PM CET, Key ID 73bde98381b46521
Source RPM  : docker-distribution-2.1.1-4.fc24.src.rpm
Build Date  : Wed 28 Oct 2015 03:01:16 PM CET
Build Host  :
Relocations : (not relocatable)
Packager    : Fedora Project
Vendor      : Fedora Project
URL         :
Summary     : Docker toolset to pack, ship, store, and deliver content
Description :
Docker toolset to pack, ship, store, and deliver content

Ok, let’s proceed and install docker-distribution package
dnf instal docker-distribution
After installation of some packages, I almost always run rpm -ql which will list me files delivered by particular package, and then I filter only /etc/ and systemd related files, in this case

 # rpm -ql docker-distribution | egrep 'etc|systemd'

At this stage, of main interest is /usr/lib/systemd/system/docker-distribution.service from where we see it will use

ExecStart=/usr/bin/registry /etc/docker-distribution/registry/config.yml

to start service

Docker has comprehensive documentation regarding parameters supported in config.yml, you can find it at Registry Configuration Reference and I recommend to check it in order to better understand what all is possible to configure.

In my /etc/docker-distribution/registry/config.yml I have below

version: 0.1
    service: registry
        layerinfo: inmemory
        rootdirectory: /var/lib/registry
    net: tcp 
    host: https://e-makina.elvirhome.local:5000
    secret: elkosecret
            certificate: /etc/certs/elvirhome.local.crt
            key: /etc/certs/elvirhome.local.key
                realm: elvirhome.local
                path: /etc/certs/dockerpasswd

I decided to to use htpasswd authentication – good enough for my test case, for all other supported authentication methods check docker documentation docker distribution auth options
I also generated self signed TLS certificate. Note that config.yml must be valid yml file and follow yml file formatting,so pay attention on it

# mkdir -p /etc/certs; cd /etc/certs; openssl req -newkey rsa:4096 -nodes -sha256 -keyout elvirhome.local.key -x509 -days 365 -out elvirhome.local.crt

and created hpasswd file

 cd /etc/certs; htpasswd  -c -B dockerpasswd elvir

Now, we are ready to start docker-distribution service

# systemctl restart docker.service 
# systemctl start docker-distribution.service

and check does it run as expected

# systemctl status docker-distribution.service 
● docker-distribution.service - v2 Registry server for Docker
   Loaded: loaded (/usr/lib/systemd/system/docker-distributio
   Active: active (running) since Thu 2015-12-24 17:12:47 CET
 Main PID: 26760 (registry)
    Tasks: 9 (limit: 512)
   CGroup: /system.slice/docker-distribution.service
           └─26760 /usr/bin/registry /etc/docker-distribution

If docker-registry, try to login to docker registry

 $ docker login e-makina.elvirhome.local:5000
Username: elvir
WARNING: login credentials saved in /home/elvir/.docker/config.json
Login Succeeded

It works, we can authenticate against local/private docker registry. In /home/$user/.docker/config.json you can find authentication parameters saved – they will be used next time, so and no need to enter password again. Above is more / less all what is necessary in order to push docker image to your own private docker registry.

However, I would like to draw attention to storage options. Docker registry v2 supports azure,gcs,s3,swift, rados and local storage which I use above – due to its cost and accessibility – free on my machine. Check full list of supported storage options and their configuration parameters docker distribution storage options
If instead local file system some other storage backend is planned to use, then above configuration will slightly differ. I still cannot say how docker operations as push/pull will perform depending if images are pushed/pulled from cloud ( non local ) storage. In this case when docker registry uses cloud based storage, new player comes in game – network latency / performance. If you consider this option, then do some tests in advance.

Now, let’s build our own image and push it to repository. Below will build image based on Fedora rawhide, with name mynewimage, later it will be tagged and pushed to local registry

$ git clone
$ cd docker/contrib
$ sh mynewimage 
$ $ docker images | grep mynewimage 
REPOSITORY                                 TAG                 IMAGE ID            CREATED             SIZE
mynewimage                                 mynewimage          68dbdc9770ec        7 seconds ago       180.1 kB
$ docker tag 68dbdc9770ec e-makina.elvirhome.local:5000/mynewimage 
$ docker push e-makina.elvirhome.local:5000/mynewimage

If you access registry via web pointing it to location you specified for host: in config.yml ( you have to use username / password specified in htpasswd step ) there will be list of images which are already pushed in repository, and here starts API heaven. Happy docker registry and docker API hacking!


#docker, #docker-registry, #docker-registry-v2-api, #docker-distribution, #linux