Distribution — The OCI Container Registry Toolkit

Introduction

Distribution (formerly Docker Registry v2) is the open-source reference implementation for storing and distributing OCI container images and artifacts. It is the engine behind Docker Hub, GitHub Container Registry, GitLab Container Registry, and most enterprise registries. If you need a private, self-hosted registry, Distribution is the battle-tested standard.

What Distribution Does

• Stores and serves OCI and Docker container images via the standard Registry HTTP API
• Supports multiple storage backends including local filesystem, S3, GCS, Azure Blob, and Swift
• Handles content-addressable storage with deduplication of shared image layers
• Provides webhook notifications for image push, pull, and delete events
• Supports image signing and content trust through Notary integration

Architecture Overview

Distribution implements the OCI Distribution Specification as a Go HTTP server. Images are stored as manifests (JSON metadata) and blobs (layer tarbytes), both content-addressed by SHA256 digest. A storage driver abstraction supports local disk, S3, GCS, Azure, and more. The registry validates uploads, deduplicates blobs, and serves layers via standard HTTP range requests. A garbage collector reclaims unreferenced blobs.

Self-Hosting & Configuration

• Run with Docker: docker run -d -p 5000:5000 registry:2 for instant local registry
• Configure via /etc/docker/registry/config.yml for storage backend, auth, and TLS
• Set up token-based authentication or integrate with htpasswd for access control
• Enable TLS with your own certificates for secure image push and pull
• Deploy on Kubernetes with Helm chart for high-availability production setups

Key Features

• OCI-compliant: works with Docker, Podman, containerd, and any OCI-compatible client
• Pluggable storage drivers for S3, GCS, Azure Blob, filesystem, and in-memory
• Content-addressable deduplication saves storage when images share base layers
• Webhook notifications for integration with CI/CD pipelines and security scanners
• Garbage collection to reclaim disk space from deleted or untagged images

Comparison with Similar Tools

• Harbor — Adds vulnerability scanning, RBAC, and replication on top of Distribution
• Zot — OCI-native registry with built-in search; lighter but less battle-tested
• Amazon ECR — Managed registry; Distribution gives full self-hosted control
• Quay — Red Hat's registry with security scanning; more features but heavier
• Artifactory — Universal artifact manager; Distribution is focused on OCI images

FAQ

Q: Is Distribution the same as Docker Hub? A: Docker Hub uses Distribution as its core storage engine, but adds a web UI, automated builds, and rate limiting on top.

Q: Can I use it for non-Docker artifacts like Helm charts or WASM modules? A: Yes. Distribution supports OCI artifacts, so you can store Helm charts, Singularity images, WASM modules, and other OCI-compliant content.

Q: How do I set up authentication? A: Configure htpasswd for basic auth, or use token-based authentication with an external authorization server for production environments.

Q: Does it support image replication across regions? A: Distribution itself does not include replication. For cross-region mirroring, use Harbor or a custom sync solution with registry mirroring.

Sources

• https://github.com/distribution/distribution
• https://distribution.github.io/distribution/