Table of Contents

Container Registry: Distribution Registry

The Distribution Registry (formerly Docker Registry 2) is a lightweight, open-source Docker registry. It supports only Docker (OCI) images and is the right choice when you want the simplest possible self-hosted registry.

What this page covers

  • Distribution Registry vs. Nexus: when to choose Distribution Registry
  • Installing with Docker Compose (Docker track)
  • Installing on K3s (K3s track)
  • Basic authentication setup with htpasswd
  • TLS configuration behind Traefik
  • Authenticating from Docker and from CI workflows

When to choose Distribution Registry

Choose Distribution Registry when:

  • You only need to store Docker images (no other artifact formats).
  • You want the smallest possible resource footprint.
  • You want a simple, battle-tested solution with minimal operational overhead.

Docker Compose installation

# docker-compose.yml
services:
  registry:
    image: registry:2
    volumes:
      - registry-data:/var/lib/registry
      - ./auth:/auth
    environment:
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: "Registry"
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
    ports:
      - "5000:5000"

Creating htpasswd credentials

htpasswd -Bbn myuser mypassword > auth/htpasswd