Docker Registry

In order to provide continuous integration / continuous delivery (CI/CD) services for Abair we provide a local docker registry. This provides the same functionality as using the likes of DockerHub which is essentially just a Docker Inc-Hosted registry with a fancy front end.

The idea is that you will configure your Github Actions / Gitlab CI to build images and push them to our private registry located at https://registry.abair.ie:5000 and then have a shell script pull the images from the registry on the production server and run them in production.

More instructions as to how to do this will be provided down the line in the recommended CI/CD documentation.

Logging in

In order to login to the registry to use it via the docker CLI you will need to first 'login.'

user@computer ~ $ docker login https://registry.abair.ie:5000/
Username: admin
Password:
Login Succeeded

Account for use in services. Be sure to use these credentials in a secret manager.

Username	Password
admin	KiVGdGsRnMNcrmgt822w

Setup and configuration.

The registry is managed using docker compose. It is running under the services account on services. The container can be found at /home/services/docker-registry.

Authentication (for the credentials provided) is managed via a htpasswd file located in .../docker-registry/auth/htpasswd. Creating additional accounts for each service is recommended although they need to be created using bcrypt. Add additional accounts by adding a new line and using the format of username:bcrypt-pw-hash and restarting the containers.

Unfortunately, due to a number of restrictions on docker:registry It's not possible to put the registry behind Cloudflare, which is why we're using Let's Encrypt for TLS/SSL and have the proxy disabled. This is also why it's running on a non-standard port for SSL (5000.)

It's not possible to use SSL termination or any form of self-signed certificates with docker-registry and still maintain authentication. This is a restriction on docker's end. See here for more details.

docker-compose.yml

services:
  registry:
    restart: always
    image: registry:2
    ports: 
      - 5000:5000
    environment:
      REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
      REGISTRY_HTTP_TLS_KEY: /certs/domain.key
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
      REGISTRY_HTTP_SECRET: V5b3BpME79mV8NqVx2uBb9cLsRHpBdfduyHDg
    volumes:
      - ./data:/var/lib/registry
      - ./certs:/certs
      - ./auth:/auth

In order to use the docker-compose file, simply place it in an empty directory named as docker-compose.yml and start it using docker compose up This will start it with the STDOUT/ERR printed, to start it in daemon mode use docker compose up -d

To stop it you can use docker compose stop, If you wish to start clean, delete volumes and then run docker compose down to delete the containers / networks.

SSL/TLS is provided via LetsEncrypt. Currently a System Administrator will have to copy over the new LE certs once every two months to ensure no service disruption, and eventually this process can be automated by automatically moving the certificates every 60 days, although this is yet to be done.

Certificate Expiry

It is forseeable that the SSL certificate used by the registry expires. SSL Certificates should automatically be provisioned to the services virtual machine on which the registry runs, however restarting the container is required in order for those changes to take effect. This can be automated at some point.

If you need to manually re-provision the SSL certificates this can be done on the webserver vm.

$ ssh webserver
$ sudo su
$ bash /root/cron/update-ssl-certs.sh

Once this has completed you can restart the registry.

$ ssh services
$ sudo su services
$ cd /home/services/docker-registry && docker compose restart

This should fix the registry.