Running Your Own Docker Registry
How I set up a private Docker registry with registry:2 in projects: tagging, pushing and pulling images, then securing it with htpasswd and TLS.
A Docker registry is not a file server where you drop images. It is the namespace through which Docker addresses images in the first place: a fully qualified image name has the form host:port/name:tag, and its host part decides where a push goes and where a pull comes from. If it is missing, Docker Hub is meant – even when the image contains your own application code.
Editorial note (July 2026): This tutorial describes the state of 2018. Docker Content Trust is based on Notary v1 and is being retired by Docker; for new signing and verification workflows, Docker points to Sigstore or Notation. Portus is no longer a current product recommendation either: the project was archived in 2023. Basic registry operation with registry:2, TLS, authentication and immutable digests is not affected by this.
If you set this host part yourself, you also decide where your images live, where they come from and who answers for production running exactly what was built and checked. The way there is short. First we clarify why a private registry makes sense at all. Then we start registry:2 with a single command, tag an image, push it and pull it down again on another host. Because an open registry is a real problem, we secure it with basic auth and TLS. Finally, we go beyond the tool: to the provenance, signing and operational responsibility for your own images. If you already know Docker Compose – for example from my article on Node.js and Redis with Docker Compose – you will find your way around here quickly.
Why your own registry at all?#
Docker Hub is convenient. You push an image, it sits in the cloud, anyone can pull it. But in many company contexts, that is exactly the problem: your own application code is in the image, and it should not be publicly visible. Sure, Docker Hub has private repositories, but then the entire deployment chain depends on an external service and on an internet connection that can be slow or disrupted at times.
A private registry in your own network solves these points in one go. The images stay internal, pulling runs over the local network and is noticeably faster, and you keep full control over where the data lives and how long it is kept. Especially in a CI/CD pipeline that pushes many builds around every day, this shows quickly.
To make the differences tangible, I like to put the two side by side:
- I host the private registry myself, in my own network, with full control over storage location and lifecycle – in return, I also operate and secure it myself.
- Docker Hub is a hosted service with accounts, organizations, a web UI and official images – in return, it depends on the internet and lives outside your own infrastructure.
Both have their place. I still pull official base images such as node, redis or registry itself from Docker Hub. My own application images, on the other hand, go into the private registry. One does not exclude the other.
The registry itself is just a container#
Let’s get to the actual tool. The open source registry that uses the same technology behind Docker Hub is called “Docker Distribution” and is provided as the ready-made image registry:2. No separate server, no elaborate installation – one docker run, and the registry is running. By default it listens on port 5000.
docker run -d \
-p 5000:5000 \
--restart=always \
--name registry \
-v /mnt/registry:/var/lib/registry \
registry:2
A few things here are set deliberately. -d starts the container in the background. --restart=always makes sure the registry comes back up on its own after a restart of the Docker daemon or the host – for a service the whole pipeline depends on, you want that. And most important: the volume with -v. By default, the registry stores its images under /var/lib/registry via the filesystem storage driver. Without a volume, this data lives only in the container. Delete the container, and the images are gone. With the mounted directory /mnt/registry, they persist.
With that, the registry is running. But it does nothing visible yet – it is waiting for its first image.
Tag, push, pull#
The decisive point when working with your own registry is the image name. Docker does not use a separate configuration switch to decide which registry an image goes to; it uses the name itself. A fully qualified image name has the form host:port/name:tag. If the host part is missing, Docker automatically assumes Docker Hub (docker.io). If I put my own registry host in front of the name, Docker knows exactly where to go on push and pull.
Let’s say I have built an image app:1.0 locally. Then I retag it for my registry:
docker tag app:1.0 registry.local:5000/app:1.0
docker tag copies nothing and rebuilds nothing – it just attaches a second name to the same image. Then I push it into the registry:
docker push registry.local:5000/app:1.0
Docker reads the host part registry.local:5000 from the name and uploads the individual layers there. On another machine in the same network – or on the CI runner that later handles the deployment – I pull the image down again the same way:
docker pull registry.local:5000/app:1.0
That is the complete cycle. Build, tag, push, pull somewhere else. I like to capture exactly this arc as a diagram, because it shows how the pieces fit together at a glance:
flowchart LR
A[docker build<br/>app:1.0] --> B[docker tag<br/>registry.local:5000/app:1.0]
B --> C[docker push]
C --> D[(Private Registry<br/>:5000)]
D --> E[docker pull<br/>other host / CI]So the whole mechanism hinges on the registry host. That also explains why retagging before the push is necessary: an image named just app:1.0 would be sent toward Docker Hub.
The weak spot: out of the box, everything is open#
The registry we just started runs without any protection. No password, no encryption. Anyone who can reach registry.local:5000 on the network can push and pull. For a quick local test on your own machine, that is fine. But as soon as the registry is reachable from more than one machine, it must not stay like this.
Securing it consists of two independent building blocks that you should not confuse:
- TLS encrypts the transport so nobody can read what goes over the wire.
- Basic auth via htpasswd protects access so only authorized users can push and pull.
One does not replace the other. TLS without auth encrypts, but lets everyone in. Auth without TLS, in turn, is not accepted by the registry at all – the passwords would go over the network in plain text, and registry:2 deliberately does not allow that. So both belong together.
Let’s look at auth first. For basic auth, the registry needs an htpasswd file, and it must use bcrypt hashes. The easiest way to create it is with the httpd image, which ships the htpasswd tool:
docker run --rm --entrypoint htpasswd httpd:2 \
-Bbn deploy s3cret > auth/htpasswd
The flags are quickly explained: -B forces bcrypt (mandatory for the registry), -b passes the password directly on the command line, and -n prints the result to stdout instead of writing it to a file – which is why I redirect the output to auth/htpasswd myself. The result is a user deploy with the password s3cret.
For TLS, I need a certificate and the matching key. In a real environment they come from an internal CA or from Let's Encrypt; in a test network, a self-signed pair will do. I put the two files as domain.crt and domain.key into a certs directory.
Now I restart the registry – this time with both layers of protection. I pass the configuration through environment variables that the registry reads at startup:
docker run -d \
-p 5000:5000 \
--restart=always \
--name registry \
-v "$(pwd)"/auth:/auth \
-v "$(pwd)"/certs:/certs \
-v /mnt/registry:/var/lib/registry \
-e REGISTRY_AUTH=htpasswd \
-e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
-e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
registry:2
The REGISTRY_AUTH_* variables turn on htpasswd authentication and point to the file we just created in the mounted /auth directory. The two REGISTRY_HTTP_TLS_* variables enable TLS with the certificate and key from /certs. From now on, you have to log in before you can push anything:
docker login registry.local:5000
After logging in with username and password, push and pull work as usual again – just secured. Docker remembers the login locally, so the pipeline runs through after a one-time docker login.
For completeness: instead of setting everything through environment variables, you can also give the registry its own config.yml. It contains the same settings in structured form under auth.htpasswd, http.tls and storage.filesystem. You then build a small image FROM registry:2, copy the configuration into it and start it with the matching entrypoint. Both ways are common; for getting started, I find the environment variable variant clearer, because you see everything in one command.
This picture shows how the two layers of protection work together and where the insecure emergency exit is:
flowchart LR
C[Client] -->|TLS| R[Registry container :5000]
R -->|htpasswd auth| S[(Storage volume<br/>/var/lib/registry)]
C2[Client without TLS] -.HTTP.-> I[insecure-registries<br/>test network only]
I -.-> RWhen no TLS is at hand#
When you are trying things out quickly, it happens that no certificate is at hand, but you still want to test a push. Then you run into a typical error message: http: server gave HTTP response to HTTPS client. By default, the Docker client expects HTTPS and refuses to talk to a plain HTTP registry.
For exactly this case there is an exception – but you should really only use it in an isolated test network. On every client, you add the registry as “insecure” to the file /etc/docker/daemon.json:
{
"insecure-registries": ["registry.local:5000"]
}
Then the Docker daemon has to be restarted for the change to take effect. The important part is “on every client”: the entry applies locally per machine, not centrally in the registry. If you use the registry on five hosts, you maintain the entry five times. For a registry in permanent operation, that is no way to run things – there is no way around TLS. By the way, if you use a self-signed certificate, you have to install it as a CA on the clients, otherwise the Docker client distrusts it just the same.
The registry as a checkpoint in the supply chain#
So far, the registry has mainly been a means of transport: build, tag, push, pull. But the real leverage sits one level higher. As soon as all your own images run through a registry that you control yourself, it becomes the central point where the provenance of what runs in production is decided. In many company contexts, that counts for more than the few seconds a pull saves on the local network.
The first point is provenance. A tag like registry.local:5000/app:1.0 is convenient, but mutable. Nothing stops someone from later overwriting the same tag with different content – the name stays the same, the image behind it is a different one. If you want to know for certain which image is running, you reference it by its digest instead of its tag:
docker pull registry.local:5000/app@sha256:9b2a4c...
The digest is the hash over the image content and therefore immutable. When a CI runner or a production host pulls an image by digest, it is guaranteed to get exactly the bits that were once built and checked – not whatever happens to sit under the tag right now. In the pipeline, this means: the build outputs the digest, the deployment pins exactly this digest, and the tag remains only a readable name for humans, not an anchor of trust.
The second point is signing. Provenance via the digest says “it is the same image,” but not yet “it comes from whoever it is supposed to come from.” That is what Docker Content Trust is for. If I set DOCKER_CONTENT_TRUST=1, Docker signs the images on push and requires a valid signature on pull:
export DOCKER_CONTENT_TRUST=1
docker push registry.local:5000/app:1.0
In the background, a Notary service manages the signatures and the associated keys. The gain is that a client recognizes a planted or tampered image and refuses the pull instead of running it blindly. This takes effort – keys need to be created, stored securely and rotated – and it is overkill for a pure test setup. But as soon as images run all the way into production, the question “did we build this, and has nobody touched it since?” is no longer academic.
The third point is operational responsibility, the flip side of all that control. If you run the registry yourself, you do not just decide who may push and pull. You are also responsible for the service running, being patched, keeping its data and staying recoverable if needed. This responsibility does not disappear; it only changes owners. With Docker Hub, the provider carries it; with your own registry, I carry it.
In 2018, this produced the real decision criterion. registry:2 was enough as long as provenance and access were covered with digests, a handful of htpasswd users and Content Trust. But as soon as many teams, fine-grained permissions, traceable audit logs and a reliable separation between “built” and “approved for production” were required, products such as Portus, Sonatype Nexus or JFrog Artifactory came into play. Portus has since been archived; for a selection today, maintenance and support status has to be checked again.
What to keep an eye on in operation#
Two things tend to get lost in the first wave of enthusiasm. The first is the persistence already mentioned: without a mounted volume, you lose all images on the next container restart. So the volume is not optional but basic equipment.
The second is disk space. The filesystem backend grows with every push, and old layers that have long been unneeded do not disappear on their own. Over time, the disk fills up. The registry ships a garbage collection for this, which you should run regularly to clean up blobs that are no longer referenced. This is easily forgotten in operation and takes its revenge months later with a full disk. A backup of the storage directory belongs here as well – with a self-hosted registry, nobody else takes care of it. These are the concrete chores behind the words operational responsibility. The fact that registry:2 starts with one command does not take them off your hands – from then on, they are mine.
Conclusion#
Your own Docker registry sounds like an infrastructure project, but technically it is a matter of a few minutes – as long as you have internalized the decisive points. The registry itself is just a container, registry:2, and the registry host is addressed through the image name host:port/name:tag. Out of the box everything is open, and securing it always needs both building blocks – TLS for encrypted transport and htpasswd for access control. The insecure-registries entry is a crutch for test networks, not a way to operate.
The real gain only shows in operation. Your own images live in your own network, are available faster and shorten the paths in the pipeline. With digests and the Docker Content Trust common at the time, fast delivery became traceable delivery – you knew what was running and where it came from. The limits are just as clear: where governance across many teams, fine-grained permissions and complete audits are required, registry:2 ends and a specialized product begins. For everything before that, a container, a cleanly set host part in the image name and two layers of protection are enough.
Further reading#
- Slide deck on this topic: https://slides.mikebild.dev/introduction-docker-kubernetes.en.html
- Deploy a registry server – docs.docker.com
- Run an externally-accessible registry (basic auth + TLS)
- Registry configuration reference (config.yml)
- Test an insecure registry (daemon.json)
- docker tag / docker push / docker pull / docker login – CLI reference
- Docker Content Trust and Notary v1
- Docker: retired products and recommended alternatives
- Portus – archived repository
- Node.js and Redis with Docker Compose
Revised and translated from German with the help of AI.