Skip to content
Blog

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

  1. 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.
  2. 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.
  3. Garbage Collection: Deleting tags via API only deletes manifest pointers. You must periodically execute registry garbage-collect to 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.