Deploying a Private Registry with the Official Registry Image
How to run your own local or self-hosted Docker registry using the official registry:2 container image, configure persistent storage, and set up basic htpasswd authentication.
Published on • November 18, 2026
AI Assistant

Running your own self-hosted container registry provides complete data sovereignty, eliminates public cloud registry bandwidth costs, and accelerates image transfers across local networks and CI runners.
The open-source Distribution project provides the official registry:2 Docker image, allowing you to spin up a fully functional, OCI-compliant container registry in seconds.
In this step-by-step tutorial, we will deploy a private container registry using docker run and docker-compose, attach persistent host storage, configure htpasswd authentication, and test image push and pull workflows.
Basic Deployment: Quickstart
To launch a basic local registry listening on port 5000:
docker run -d \
-p 5000:5000 \
--restart=always \
--name local-registry \
registry:2
You can immediately test your new local registry:
# 1. Pull a standard public image
docker pull alpine:latest
# 2. Tag it for your local registry
docker tag alpine:latest localhost:5000/my-alpine:v1
# 3. Push to your local registry
docker push localhost:5000/my-alpine:v1
(Note: Docker automatically allows unencrypted HTTP connections to localhost:5000).
Adding Persistent Storage and Basic Authentication
A default container instance stores uploaded image layers inside its ephemeral container container filesystem (/var/lib/registry). If the container is deleted, all stored images are lost!
To build a production-grade self-hosted registry, attach persistent storage volumes and enforce HTTP Basic Authentication using htpasswd.
Step 1: Create htpasswd Credentials
Use htpasswd (from apache2-utils or via Docker) to generate an encrypted password file:
mkdir -p /opt/registry/auth /opt/registry/data
# Generate htpasswd file containing user 'registryuser' with password 'SuperSecret123!'
docker run --rm \
--entrypoint htpasswd \
httpd:2-alpine \
-Bbn registryuser "SuperSecret123!" > /opt/registry/auth/htpasswd
Step 2: Deploying via Docker Compose
Create a docker-compose.yml file to manage persistent configuration:
version: '3.8'
services:
registry:
image: registry:2
container_name: private-registry
restart: always
ports:
- "5000:5000"
environment:
REGISTRY_AUTH: htpasswd
REGISTRY_AUTH_HTPASSWD_REALM: "Registry Realm"
REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /var/lib/registry
volumes:
- /opt/registry/data:/var/lib/registry
- /opt/registry/auth:/auth:ro
Start the registry service:
docker compose up -d
Testing Authenticated Workflows
Now that authentication is enabled, unauthenticated push or pull attempts will be rejected with HTTP 401:
docker pull localhost:5000/my-alpine:v1
# Output: Error response from daemon: no token passed
1. Authenticate with docker login
docker login localhost:5000 -u registryuser -p SuperSecret123!
# Output: WARNING! Your password will be stored unencrypted in ~/.docker/config.json. Login Succeeded
2. Push & Pull
docker push localhost:5000/my-alpine:v1
# Output: v1: digest: sha256:7f8a... size: 528
Inspecting Stored Registry Catalog via REST API
The official registry exposes standard OCI distribution endpoints:
# List all repositories stored in the registry
curl -u registryuser:SuperSecret123! http://localhost:5000/v2/_catalog
# Output: {"repositories":["my-alpine"]}
# List all tags for a specific repository
curl -u registryuser:SuperSecret123! http://localhost:5000/v2/my-alpine/tags/list
# Output: {"name":"my-alpine","tags":["v1"]}
Important Considerations for Production
- TLS / HTTPS Encryption: Connecting over IP addresses (e.g.,
192.168.1.10:5000) requires setting up TLS certificates (or a reverse proxy like NGINX / Caddy) because Docker CLI rejects HTTP connections to non-localhost addresses by default. - Object Storage Backends: For high availability, configure S3, MinIO, Google Cloud Storage, or Azure Blob Storage as the registry storage backend instead of local host disk directories.
- Garbage Collection: Deleting tags via API only deletes manifest pointers. You must periodically execute
registry garbage-collectto delete unreferenced layer blobs from disk.
Summary
Deploying the official registry:2 container image with persistent host volumes and htpasswd authentication gives you a fast, lightweight, and private container registry environment.