Hands-on Lab

How to Run a Private, Self-Hosted Docker Registry

July 17, 2026 3 min

0 / 7

Cheat sheet

Found it useful? Don't miss the next lab

0:00 / 0:00

We pull alpine:3.21 from Docker Hub: a tiny image (under 8 MB) that serves as our test subject for the whole push/pull cycle in this lab. We pin the version instead of using latest so the command stays exactly reproducible.

docker pull alpine:3.21

I did it

We confirm the image landed in Docker's local image store before moving on: it shows up with its ID and its real on-disk size.

docker images alpine:3.21

We bring up the official registry. -d runs it in the background, -p 5000:5000 publishes its HTTP port on the host, --restart=always keeps it alive across a daemon restart, and registry:3 is the current image from the Distribution project (the successor to the older registry:2).

docker run -d -p 5000:5000 --restart=always --name registry registry:3

I did it

We confirm two things at once: that the container is running and publishing port 5000, and that the registry's API answers. GET /v2/ is the minimal check endpoint from the spec: if the registry is healthy and reachable, it returns an empty JSON object ({}).

docker ps --filter name=registry --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'; for i in $(seq 1 30); do curl -fsS http://localhost:5000/v2/ >/dev/null 2>&1 && break; sleep 1; done; curl -s http://localhost:5000/v2/

docker tag creates a new local alias, localhost:5000/alpine:mine, pointing at the same image ID as alpine:3.21: it copies zero bytes. docker push is the one that actually moves data: it uploads the image's layers to our registry on port 5000, using the alias's host:port to know where to send them.

docker tag alpine:3.21 localhost:5000/alpine:mine && docker push localhost:5000/alpine:mine

I did it

We ask the registry itself what it has stored, without going through the Docker client. GET /v2/_catalog lists the repositories (alpine should show up) and GET /v2/alpine/tags/list lists its tags (mine should show up): the definitive proof the push actually landed.

for i in $(seq 1 30); do curl -fsS http://localhost:5000/v2/ >/dev/null 2>&1 && break; sleep 1; done; curl -s http://localhost:5000/v2/_catalog | jq .; curl -s http://localhost:5000/v2/alpine/tags/list | jq .

We delete both local tags pointing at this image. That leaves the registry as the only copy left anywhere in the lab: any later docker pull has to fetch it back from port 5000, not from a local cache.

docker rmi localhost:5000/alpine:mine alpine:3.21

I did it

We confirm neither tag remains in the local store: both commands return just the header row, with nothing under it. The image no longer exists on this machine.

docker images alpine:3.21; docker images localhost:5000/alpine:mine

The moment of truth: we pull the image back, but this time from our own registry instead of Docker Hub. The localhost:5000/ prefix is the only thing that differs from an ordinary docker pull.

docker pull localhost:5000/alpine:mine

I did it

We don't stop at docker pull succeeding: we start a real container from the freshly pulled image and read /etc/os-release inside it. Seeing 'Alpine Linux' in the output proves the image that traveled through our registry is a complete, working image, not just metadata.

docker run --rm localhost:5000/alpine:mine cat /etc/os-release

We generate the credentials file the registry's htpasswd auth mode requires. -B forces the bcrypt hash (the only format registry:3 accepts), -b passes the password on the command line itself, and -n prints the result instead of writing straight to an existing file, so we redirect it ourselves into /auth/htpasswd. changeme is a placeholder: on a real registry it gets replaced with a generated password and wiped from the shell history.

mkdir -p /auth && htpasswd -Bbn registryadmin changeme > /auth/htpasswd

I did it

We confirm the file was generated with the right shape: a single username:hash line where the hash starts with $2y$, bcrypt's marker. This is exactly the file you'd mount with -v into the registry container and point at with REGISTRY_AUTH_HTPASSWD_PATH to turn on real authentication.

cat /auth/htpasswd

Final cleanup: we stop and remove the registry container, remove the image we pulled back earlier, and delete the throwaway credentials file. None of it survives on the machine once the lab is done.

docker rm -f registry && docker rmi -f localhost:5000/alpine:mine && rm -rf /auth

I did it

Final check: neither the registry container, nor the pulled-back image, nor the /auth directory are still around. All three commands come back empty or confirm the directory is gone, leaving the machine clean.

docker ps -a --filter name=registry; docker images localhost:5000/alpine:mine; ls /auth 2>&1 || echo 'auth dir removed'

Was this lab useful? Rate it:

Click to rate this post!

[Total: 0 Average: 0]

What a private Docker registry is

A registry is the server that stores container images and serves them when someone runs docker pull. Docker Hub is the default public registry, but as soon as you need to control where your images live (for compliance, for bandwidth, or simply to stop depending on a third party) you run your own with the reference implementation from the Distribution project, packaged as the registry:3 image.

How tagging and pushing an image works

An image name carries the registry encoded up front: host:port/repository:tag. docker tag alpine:3.21 localhost:5000/alpine:mine copies nothing; it just creates a local alias pointing at the same image ID, and it is docker push that actually ships the layers to the registry. The source behind that push endpoint lives in the distribution/distribution repository.

Securing the registry with htpasswd and TLS

An unauthenticated registry is an open bin: anyone with network access to port 5000 can push or pull images. The registry:3 image supports basic auth (a bcrypt-hashed username and password via htpasswd) and TLS in front of port 5000; in production the two always ship together, because Docker only sends credentials in the clear to hosts it treats as “insecure”, which by default means only localhost. In this lab we generate an htpasswd file with a throwaway user and password (changeme) to see the bcrypt format the registry requires; wiring it up for real only takes REGISTRY_AUTH=htpasswd, REGISTRY_AUTH_HTPASSWD_PATH and a certificate under REGISTRY_HTTP_TLS_CERTIFICATE at container start.

If you’re exposing the registry under your own domain, our Nginx Proxy Manager on Docker guide covers the TLS certificate side for any container. To understand the rest of the networking this lab touches, we have dedicated guides on Docker networking and volumes and bind mounts; if you’d rather read a written walkthrough without the video, the long-form version is how to run a private Docker image registry. This and the rest of our hands-on labs follow the same rule: everything you see actually ran.

FAQ

What is the official image used to run a private Docker registry?

The registry:3 image, maintained by the Distribution project (the reference implementation of the container registry). It replaces the older registry:2, which still works but no longer gets the latest fixes.

How do I tell Docker to use my registry instead of Docker Hub?

By prefixing the image name with the registry's host and port: localhost:5000/alpine:mine instead of alpine:mine. That prefix is the only thing that tells Docker Hub images apart from images in your own registry.

Is it safe to leave a Docker registry with no authentication or TLS?

Not for production. Without authentication, anyone with network access to port 5000 can push or pull images; without TLS, Docker only sends credentials in the clear to hosts it treats as insecure (by default, only localhost). The registry supports both together: htpasswd for authentication and a certificate to encrypt the traffic.

What is the difference between docker tag and docker push?

docker tag doesn't move a single byte: it creates a new local alias pointing at the same image ID. docker push is the command that actually ships the image's layers to the registry encoded in that alias.

Cheat sheet

```
docker pull alpine:3.21
```

docker run -d -p 5000:5000 --restart=always --name registry registry:3

docker tag alpine:3.21 localhost:5000/alpine:mine && docker push localhost:5000/alpine:mine

docker rmi localhost:5000/alpine:mine alpine:3.21

```
docker pull localhost:5000/alpine:mine
```

mkdir -p /auth && htpasswd -Bbn registryadmin changeme > /auth/htpasswd

docker rm -f registry && docker rmi -f localhost:5000/alpine:mine && rm -rf /auth

Found it useful? Don't miss the next lab

Subscribe to the newsletter

What a private Docker registry is

How tagging and pushing an image works

Securing the registry with htpasswd and TLS

FAQ

What is the official image used to run a private Docker registry?

How do I tell Docker to use my registry instead of Docker Hub?

Is it safe to leave a Docker registry with no authentication or TLS?

What is the difference between docker tag and docker push?

Cheat sheet