In this post I will go over the installation of Docker Registry with Basic Authentication and over SSL/TLS (self-signed cert for demonstration purposes). I will also do this on Docker for Mac, which has some interesting things to note.
Let me start by saying that you can use the Docker Hub which is a freely available Hosted registry, but there may be instances where you want to host your own registry to control where your images are being stored, you can also opt to use the commercial Docker Trusted Registry, but I will go over the free open-source Registry.
Create project structure
Password file to support Basic Auth
Certificates to support TLS
Location to store the images
Create Docker Registry container
Using the Registry
Registry API
Create project structure
|
1 2 3 4 5 6 7 8 9 10 |
mac$ mkdir -p registry/{volumes/{auth,certs,data},docker-registry} mac$ cd registry mac$ tree . └── registry ├── docker-registry // WhereI will store the docker-compose.yml file └── volumes ├── auth // Volume for Basic Auth password file ├── certs // Volume for TLS certs └── data // Volumes for images storage |
Password file to support Basic Auth
Let’s create a username and password
|
1 2 3 4 |
mac$ htpasswd -Bbn <USER> <PASSWORD> > volumes/auth/htpasswd mac$ cat volumes/auth/htpasswd user1:$2y$05$xOuwA8oaflSZ5wpiJto2/OBOIMTSpZrH69wsaQOsnaKt07Vzu1sBW |
Certificates to support TLS
Create a root CA key, which will sign the actual certificates
|
1 |
mac$ openssl genrsa -out volumes/certs/rootCA.key 2048 |
Create root CA certificate which will need to be installed on the systems that will use the Registry
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
mac$ openssl req -x509 -new -nodes -key volumes/certs/rootCA.key -days 365 -out volumes/certs/rootCA.crt You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:NY Locality Name (eg, city) []:NY Organization Name (eg, company) [Internet Widgits Pty Ltd]:Technologist Organizational Unit Name (eg, section) []:Tech Common Name (e.g. server FQDN or YOUR name) []:Technologist CA Email Address []:johnATtechnologist |
Now that you have a CA, you can sign certificates.
Create a key for the Registry system
|
1 |
mac$ openssl genrsa -out volumes/certs/host.key 2048 |
Create a Certificate Signing Request (CSR) for the CA to sign
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
mac$ openssl req -new -key volumes/certs/host.key -out volumes/certs/host.csr You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:NY Locality Name (eg, city) []:NY Organization Name (eg, company) [Internet Widgits Pty Ltd]:Technologist Organizational Unit Name (eg, section) []:Tech Common Name (e.g. server FQDN or YOUR name) []:registry.example.com Email Address []:johnATtechnologist Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: An optional company name []: |
Finally have the root CA sign the CSR
|
1 2 3 4 5 |
mac$ openssl x509 -req -in volumes/certs/host.csr -CA volumes/certs/rootCA.crt -CAkey volumes/certs/rootCA.key -CAcreateserial -out volumes/certs/host.crt -days 365 Signature ok subject=/C=US/ST=NY/L=NY/O=Technologist/OU=Tech/CN=registry.example.com/emailAddress=johnATtechnologist Getting CA Private Key |
Location to store the images
The tree structure should look like below, having the data folder be the image repository
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
mac $ tree . ├── docker-registry │ └── docker-compose.yml └── volumes ├── auth │ └── htpasswd ├── certs │ ├── host.crt │ ├── host.csr │ ├── host.key │ ├── rootCA.crt │ ├── rootCA.key │ └── rootCA.srl └── data |
Create Docker Registry container
Run your container using docker command
|
1 2 3 4 5 6 7 8 9 |
mac$ docker run -d -p 5000:5000 --restart=always --name registry \ -v /Users/john/docker/blog/registry/volumes/auth:/auth \ -e "REGISTRY_AUTH=htpasswd" \ -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \ -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \ -v /Users/john/docker/blog/registry/volumes/certs:/certs \ -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/host.crt \ -e REGISTRY_HTTP_TLS_KEY=/certs/host.key \ registry:2 |
Or even better, use docker-compose:
|
1 2 |
mac$ cd docker-registry mac$ cat docker-compose.yml |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
registry: restart: always image: registry:2 ports: - 5000:5000 environment: REGISTRY_HTTP_TLS_CERTIFICATE: /certs/host.crt REGISTRY_HTTP_TLS_KEY: /certs/host.key REGISTRY_AUTH: htpasswd REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm volumes: - /Users/john/docker/blog/registry/volumes/data:/var/lib/registry - /Users/john/docker/blog/registry/volumes/certs:/certs - /Users/john/docker/blog/registry/volumes/auth:/auth |
Start up container based on docker-compose.yml
|
1 2 |
mac$ docker-compose up -d Creating dockerregistry_registry_1 |
See it running
|
1 2 3 4 |
mac$ docker-compose ps Name Command State Ports ------------------------------------------------------------------------------------------- dockerregistry_registry_1 /entrypoint.sh /etc/docker ... Up 0.0.0.0:5000->5000/tcp |
At this point the Docker Registry is running
Using the Registry
Download an image from Docker Hub (or you can test with your own images built from Dockerfile)
|
1 |
mac$ docker pull ubuntu |
Tag the image to point to your new Registry
|
1 |
mac$ docker tag ubuntu registry.example.com:5000/john/ubuntu |
Push image to your Registry (see failure due to ‘unknow CA authority’)
|
1 2 3 |
mac$ docker push registry.example.com:5000/john/ubuntu The push refers to a repository [registry.example.com:5000/john/ubuntu] Get https://registry.example.com:5000/v1/_ping: x509: certificate signed by unknown authority |
At this point, you need to add the root CA cert to your trusted certificates.
On the machine that will pull or push to the registry, you will need to install the rootCA.crt CA certificate created earlier:
|
1 2 |
docker-engine$ mkdir /etc/docker/certs.d/registry.example.com:5000/ docker-engine$ cp rootCA.crt /etc/docker/certs.d/registry.example.com:5000/rootCA.crt |
On the Mac, you are probably using Docker for Mac, which actually runs a small hypervisor xhyve that virtualizes the docker engine. That means we need to place the rootCA.crt CA certificate inside the xhyve VM running the Docker Engine. There is no simple way of doing it and I am using the following method (which must be done everytime you restart the Docker service).
|
1 |
mac$ docker run -v /Users/john/docker/blog/registry/volumes/certs:/macdata -v /etc/docker:/hostdata ubuntu bash -c "mkdir -p /hostdata/certs.d/registry.example.com:5000/;cat /macdata/rootCA.crt > /hostdata/certs.d/registry.example.com:5000/ca.crt" |
Now let’s try to Push the image to the Registry again
|
1 2 3 4 5 6 7 8 |
linux$ docker push registry.example.com:5000/john/ubuntu The push refers to a repository [registry.example.com:5000/john/ubuntu] 4f9d527ff23f: Preparing cc8df16ebbaf: Preparing c3c1fd75be70: Preparing 5c42a1311e7e: Preparing c8305edc6321: Preparing unauthorized: authentication required |
Good, we are getting somewhere, TLS is working, and it now asks for Authentication
Authenticate to the Docker Registry
|
1 2 3 4 |
linux$ docker login registry.example.com:5000 Username (testuser): user1 Password: Login Succeeded |
Now let’s successfully push our image
|
1 2 3 4 5 6 7 8 |
linux$ docker push registry.example.com:5000/john/ubuntu The push refers to a repository [registry.example.com:5000/john/ubuntu] 4f9d527ff23f: Pushed cc8df16ebbaf: Pushed c3c1fd75be70: Pushed 5c42a1311e7e: Pushed c8305edc6321: Pushed latest: digest: sha256:35dca5fc91c4890f787a266a057ad76b98ff3af43c75aa7e10962d06f06fd6e5 size: 1357 |
At this point you can share your Docker image, or incorporate into a development or integration workflow by pulling the image
From any Docker engine system:
|
1 2 3 4 |
linux$ docker login registry.example.com:5000 Username: user1 Password: Login Succeeded |
|
1 2 3 4 5 |
linux$ docker pull registry.example.com:5000/john/ubuntu Using default tag: latest latest: Pulling from john/ubuntu Digest: sha256:35dca5fc91c4890f787a266a057ad76b98ff3af43c75aa7e10962d06f06fd6e5 Status: Downloaded newer image for registry.example.com:5000/john/ubuntu:latest |
Registry API
You can use the Docker Registry API https://docs.docker.com/registry/spec/api/ to interact with your Registry.
For example to see a catalog of your images:
|
1 2 3 |
$ curl --user user1:password1 --cacert rootCA.crt -X GET https://registry.example.com:5000/v2/_catalog {"repositories":["john/ubuntu"]} |
Comments
Leave a comment Trackback