... it's better to have good questions

Running a private container registry for testing

When I signed up for my DockerHub account in 2013, I never thought sooner than later everything ends up in a container image as it is today. DockerHub was the first public free as in free beer registry to distribute your container images. Containers are now everywhere, and DockerHub, a corporate entity running and funding DockerHub, introduced usage limits for the free tier and started commercializing its registry service. I need to play with software in a micro-service architecture on a platform like Kubernetes, and these limits can be daunting.

In this guide, I want to remind myself how to run a local private registry in a home lab with a valid TLS certificate using Let’s Encrypt. The registry is on a private network, and I use the Let’s Encrypt DNS challenge mechanism to get a valid certificate. As an example, I control DNS for the domain, and I want to use as my internal home lab registry. To keep it simple, I describe it with docker-compose.

I’ve created a local project directory registry which contains all the files I need to run it. The directory structure is like the following:

❯ tree -L 3
├── certs
│   └──
│       ├── cert1.pem
│       ├── chain1.pem
│       ├── fullchain1.pem
│       └── privkey1.pem
├── docker-compose.yml
└── registry
    └── docker
        └── registry

The certs directory contains the certificates and the key from Let’s Encrypt. The registry folder persists the data for the registry and the metadata. I run the registry on 443, allowing me to use it with docker pull | push natively.

version: '3'
    image: registry:2
    container_name: registry
      - REGISTRY_HTTP_TLS_KEY=/certs/
      - ./registry:/var/lib/registry
      - ./certs:/certs
      - '443:443/tcp'

Before running the registry I need certificates.

cd certs
docker run -it -v $(pwd):/etc/letsencrypt/archive certbot/certbot certonly --preferred-challenges dns --manual

Following the interactive dialog and entered the domain I wanted to use. I get prompted to create a DNS TXT record to verify ownership with something like this:

with the following value:


I would recommend using a short TTL like 300s when you create the TXT record. It will make it easier if you make a mistake and you have to redo it again. They provide a handy link which allows verifying if the text record is populated accordingly. Another method is using your local DNS resolver using a command like this:

nslookup -type=TXT

When I receive the certificate and keys on my disk, I need to verify the file names and directory paths match with the environment variables in the docker-compose.yml file:


Make sure the name resolution for the internal registry host is working. In my case resolves to an internal address. When the registry is running you can verify the certificate with your browser connecting to It is an empty page but you should connect to it with HTTPS without any complains.

I can now use the registry with tagging the images accordingly, like here in this quick example:

docker pull busybox
docker tag busybox
docker push

If you need it a bit more automated, I can recommend to look at lego which adds automations on the things described above.

gl & hf

Image by Ro Ma from Pixabay