Distribution — The OCI Container Registry Toolkit

What it is

Distribution is the reference implementation of the OCI Distribution Specification. It provides a container image registry that stores and serves Docker and OCI container images. This is the same codebase that powers Docker Hub, GitHub Container Registry (GHCR), and most private registries. You deploy it as a single binary or Docker container to host your own image registry.

Distribution targets platform engineers, DevOps teams, and organizations that need a private container registry for security, compliance, or performance reasons.

How it saves time or tokens

Pulling images from public registries like Docker Hub introduces rate limits, latency, and dependency on external infrastructure. Running your own registry with Distribution eliminates rate limits, keeps images on your network, and gives you full control over access. For CI/CD pipelines that build and deploy frequently, a local registry cuts image pull times from seconds to milliseconds.

How to use

1. Run a local registry:

docker run -d -p 5000:5000 --name registry registry:2

1. Tag and push an image:

docker tag my-image localhost:5000/my-image
docker push localhost:5000/my-image

1. Pull from your registry:

docker pull localhost:5000/my-image

Example

# docker-compose.yml - Production registry with persistent storage
version: '3'
services:
  registry:
    image: registry:2
    ports:
      - '5000:5000'
    volumes:
      - registry-data:/var/lib/registry
    environment:
      REGISTRY_STORAGE_DELETE_ENABLED: 'true'
      REGISTRY_HTTP_HEADERS_Access-Control-Allow-Origin: '["*"]'

volumes:
  registry-data:

This sets up a persistent registry with image deletion enabled.

Related on TokRepo

• DevOps Tools -- Container and infrastructure automation tools
• Self-Hosted Solutions -- Self-hosted infrastructure platforms

Common pitfalls

• The default registry has no authentication. Add TLS and basic auth or token auth before exposing it outside localhost.
• Storage grows indefinitely without garbage collection. Run registry garbage-collect periodically to reclaim space from deleted images.
• Docker requires HTTPS for non-localhost registries by default. Either add TLS certificates or configure Docker to allow insecure registries (not recommended for production).