Alternative Docker Registry Solutions: Self-Hosting and Beyond

Self-hosted Applications
,
1

Introduction

Docker Hub’s rate limits (100 pulls/6 hours for anonymous users, 200 pulls/6 hours for free authenticated users) can significantly impact development workflows, especially when working behind a shared IP address where multiple users’ pulls count against the same limit. This guide explores alternative solutions that can help you avoid these limitations.

1. Self-Hosted Docker Registry

A self-hosted registry gives you complete control over your Docker images without external rate limits.

Basic Setup

The simplest way to set up a Docker registry is to run it as a Docker container:

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

This command:

  • Runs the registry in detached mode (-d)
  • Maps port 5000 on your host to port 5000 in the container
  • Names the container “registry”
  • Uses the official registry:2 image

Production Setup

For a production environment, you’ll want a more robust configuration:

docker run -d \
  -p 5000:5000 \
  --restart=always \
  --name registry \
  -v /path/to/registry-data:/var/lib/registry \
  -v /path/to/certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  registry:2

This configuration includes:

  • Persistent storage for images (-v /path/to/registry-data:/var/lib/registry)
  • TLS certificates for secure connections
  • Automatic restart on failure or system reboot

Adding Authentication

To prevent unauthorized access, add basic authentication:

  1. Create a password file:

    mkdir auth
docker run --entrypoint htpasswd httpd:2 -Bbn username password > auth/htpasswd

  2. Run the registry with authentication:

    docker run -d \
  -p 5000:5000 \
  --restart=always \
  --name registry \
  -v /path/to/registry-data:/var/lib/registry \
  -v /path/to/certs:/certs \
  -v $(pwd)/auth:/auth \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  -e REGISTRY_AUTH=htpasswd \
  -e REGISTRY_AUTH_HTPASSWD_REALM="Registry Realm" \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  registry:2

Using Your Self-Hosted Registry

Tag and push an image:

docker tag ubuntu:latest localhost:5000/my-ubuntu:latest
docker push localhost:5000/my-ubuntu:latest

Pull an image:

docker pull localhost:5000/my-ubuntu:latest

For remote access, replace localhost with your server’s IP address or domain name.

Benefits of Self-Hosted Registry

  1. No rate limits: Pull as many images as often as you need
  2. Improved speed: Local network transfers are faster than internet downloads
  3. Control and privacy: Keep sensitive images within your infrastructure
  4. Customization: Configure storage, authentication, and other options to suit your needs

Limitations

  1. Maintenance overhead: You’re responsible for updates, backups, and security
  2. Resource requirements: Requires a server with sufficient storage and memory
  3. Single point of failure: Without proper redundancy, downtime affects all users

2. Pull-Through Cache

A pull-through cache is a special type of registry that acts as a proxy, caching Docker Hub images locally after the first pull.

Setup

docker run -d \
  -p 5000:5000 \
  --restart=always \
  --name registry \
  -v $(pwd)/registry-data:/var/lib/registry \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  registry:2

This configuration:

  • Creates a registry on port 5000
  • Stores cached images in ./registry-data
  • Sets up proxying to Docker Hub via the REGISTRY_PROXY_REMOTEURL environment variable

Advanced Configuration

For a production pull-through cache, consider these additional configurations:

docker run -d \
  -p 5000:5000 \
  --restart=always \
  --name registry \
  -v $(pwd)/registry-data:/var/lib/registry \
  -v $(pwd)/certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  -e REGISTRY_PROXY_USERNAME=your-dockerhub-username \
  -e REGISTRY_PROXY_PASSWORD=your-dockerhub-password \
  -e REGISTRY_STORAGE_CACHE_BLOBDESCRIPTOR=redis \
  -e REGISTRY_REDIS_ADDR=redis:6379 \
  --link redis:redis \
  registry:2

This adds:

  • TLS security
  • Docker Hub authentication (for access to private images)
  • Redis for cache metadata (improves performance)

Docker Daemon Configuration

Configure Docker clients to use your cache by editing /etc/docker/daemon.json:

{
  "registry-mirrors": ["https://your-registry-server:5000"]
}

Then restart the Docker daemon:

sudo systemctl restart docker

How Pull-Through Cache Works

  1. When a client requests an image (e.g., nginx:latest), Docker checks the cache first
  2. If the image exists in the cache, it’s served directly (no Docker Hub rate limit used)
  3. If the image isn’t cached, the registry pulls it from Docker Hub (counting as just one pull against rate limits), stores it locally, and serves it to the client
  4. Future pulls for the same image tag are served from the cache

Benefits of Pull-Through Cache

  1. Reduces Docker Hub pulls: Only the first pull of an image counts against rate limits
  2. Transparent to users: Clients use images as normal with no workflow changes
  3. Network efficiency: Reduces internet bandwidth usage
  4. Lower maintenance: No need to manually mirror and update images

Cache Management

Monitor disk usage:

du -sh registry-data/

To garbage collect unused layers:

docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml

3. Alternative Public Registries

Several public registries offer Docker-compatible image hosting with different rate limit policies.

Google Container Registry (GCR)

Google Cloud Platform’s container registry service:

  1. Setup:

    • Create a Google Cloud account
    • Install Google Cloud SDK
    • Authenticate: gcloud auth configure-docker

  2. Usage:

    docker tag nginx:latest gcr.io/your-project-id/nginx:latest
docker push gcr.io/your-project-id/nginx:latest

  3. Benefits:

    • Generous free tier (first 0.5 GB storage per month is free)
    • Integrated with Google Cloud services
    • Vulnerability scanning
    • No strict pull rate limits

Amazon Elastic Container Registry (ECR) Public Gallery

Amazon’s public container registry:

  1. Setup:

    • Create an AWS account
    • Install AWS CLI
    • Authenticate: aws ecr-public get-login-password | docker login --username AWS --password-stdin public.ecr.aws

  2. Usage:

    docker tag nginx:latest public.ecr.aws/your-namespace/nginx:latest
docker push public.ecr.aws/your-namespace/nginx:latest

  3. Benefits:

    • 50 GB free storage per month
    • 500 GB free data transfer per month
    • Global content delivery network
    • No documented pull rate limits

Red Hat Quay.io

Red Hat’s container registry:

  1. Setup:

    • Create a Quay.io account
    • Authenticate: docker login quay.io

  2. Usage:

    docker tag nginx:latest quay.io/your-username/nginx:latest
docker push quay.io/your-username/nginx:latest

  3. Benefits:

    • Free public repositories
    • Container security scanning
    • Image build triggers
    • No strict pull rate limits

GitHub Container Registry (GHCR)

GitHub’s container registry service:

  1. Setup:

    • Create a GitHub account
    • Create a personal access token with packages permissions
    • Authenticate: echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin

  2. Usage:

    docker tag nginx:latest ghcr.io/your-username/nginx:latest
docker push ghcr.io/your-username/nginx:latest

  3. Benefits:

    • Free for public packages
    • Integrated with GitHub Actions
    • Supports OCI artifacts
    • No strict pull rate limits for authenticated users

4. Docker Hub Paid Subscriptions

If you prefer to stay with Docker Hub, paid subscriptions offer higher rate limits:

Docker Pro ($5/month)

  • Pull limits: 5,000 pulls per day
  • Benefits:
    • Unlimited private repositories
    • 500 scoped tokens for secure access control
    • 5,000 vulnerability scans per month
    • Parallel builds

Docker Team ($9/user/month)

  • Pull limits: 5,000 pulls per day
  • Benefits:
    • Team management features
    • Audit logs
    • Activity insights
    • Role-based access control

Docker Business ($24/user/month)

  • Pull limits: Unlimited pulls
  • Benefits:
    • Single sign-on
    • VPN tunnels
    • Image access management
    • Registry access controls

Enterprise (Custom pricing)

  • Pull limits: Unlimited pulls
    • Enhanced security features
    • Air-gapped registry options
    • 24/7 support

When to Consider a Paid Subscription

A paid Docker Hub subscription might be worth it if:

  1. You frequently need access to many different images
  2. You need features like vulnerability scanning
  3. You prefer the simplicity of using Docker Hub directly
  4. The cost of maintaining your own registry solution exceeds the subscription cost

5. Troubleshooting Authentication Issues

Authentication problems are common when working with Docker registries. Here’s how to diagnose and resolve them:

Common Authentication Error Messages

  1. “unauthorized: authentication required”:

    • You’re trying to pull from or push to a private repository without authentication
    • Solution: docker login with correct credentials

  2. “denied: requested access to the resource is denied”:

    • You’re authenticated but don’t have permission for the operation
    • Solution: Check permissions on the repository

  3. “error storing credentials - err: exit status 1”:

    • Issues with the Docker credential helper
    • Solution: rm -rf ~/.docker/config.json and login again

Self-Hosted Registry Authentication Issues

  1. Certificate problems:

    • Error: “x509: certificate signed by unknown authority”
    • Solution: Add your certificate to the trusted store or use --insecure-registry (not recommended for production)

  2. Expired credentials:

    • Docker login sessions eventually expire
    • Solution: Re-run docker login with fresh credentials

  3. Missing or incorrect .htpasswd file:

    • Solution: Verify the htpasswd file exists and contains correct entries

Docker Hub Authentication Issues

  1. Token expiration:

    • Personal access tokens have expiration dates
    • Solution: Generate a new token and update login credentials

  2. Two-factor authentication:

    • If 2FA is enabled, you must use a personal access token instead of password
    • Solution: Generate a token in Docker Hub settings

  3. Rate limit errors despite authentication:

    • Verify you’re actually authenticated: docker info | grep Username
    • Solution: Re-authenticate with docker login

Alternative Registry Authentication Issues

  1. GCR authentication errors:

    • Run gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin gcr.io

  2. ECR authentication errors:

    • AWS credentials might have expired
    • Solution: Refresh credentials and re-authenticate

  3. GHCR authentication errors:

    • Ensure your token has the correct permissions
    • Token must have read:packages and write:packages scopes

Debugging Authentication

Check your current authentication status:

cat ~/.docker/config.json

Test connectivity to the registry:

curl -v https://your-registry:5000/v2/

For registry logs:

docker logs registry

Conclusion

Each solution has its own advantages and considerations:

  1. Self-hosted registry: Best for complete control but requires maintenance
  2. Pull-through cache: Excellent middle ground with minimal configuration
  3. Alternative public registries: Good for avoiding Docker Hub limits with minimal changes
  4. Docker Hub paid subscriptions: Simplest solution if the cost is acceptable

For most development teams dealing with Docker Hub rate limits, a pull-through cache offers the best balance of simplicity, effectiveness, and cost. It requires minimal changes to existing workflows while effectively eliminating rate limit issues.

For larger pulls, a combination approach might work best: a self-hosted registry for your own images, a pull-through cache for third-party images, and perhaps a paid Docker Hub account for critical production environments.

Remember that whatever solution you choose, proper authentication management and regular maintenance will ensure your Docker registry experience remains smooth and reliable.

1 Like