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 : buildvm-17.phx2.fedoraproject.org Relocations : (not relocatable) Packager : Fedora Project Vendor : Fedora Project URL : https://github.com/docker/distribution 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' /etc/docker-distribution/registry/config.yml /usr/lib/systemd/system/docker-distribution.service
At this stage, of main interest is /usr/lib/systemd/system/docker-distribution.service from where we see it will use
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 log: fields: service: registry storage: cache: layerinfo: inmemory filesystem: rootdirectory: /var/lib/registry http: addr: 192.168.11.122:5000 net: tcp host: https://e-makina.elvirhome.local:5000 secret: elkosecret tls: certificate: /etc/certs/elvirhome.local.crt key: /etc/certs/elvirhome.local.key auth: htpasswd: 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 Password: Email: ekuric@at_secret_domain.net 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 https://github.com/docker/docker $ cd docker/contrib $ sh mkimage-yum.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!