Self-Hosted Docker Registry Hardening: Authentication, Network Segmentation, and Image Signing

Nginx Alternative with Buffer Tuning

If using nginx as the internal proxy layer (for example, between an outer reverse proxy and the registry), buffer sizing and tmpfs configuration are critical for reliability under load:

upstream docker-registry {
    server 127.0.0.1:5000;
}

server {
    listen 80;
    server_name registry.internal;

    # This is the single most important setting for registry reliability.
    # Without sufficient buffer space, concurrent pushes of large images
    # will fail with 502 errors.
    client_max_body_size 0;

    proxy_buffering on;
    proxy_buffer_size 32k;
    proxy_buffers 16 64k;
    proxy_busy_buffers_size 128k;

    # Temp file storage for large layer uploads
    proxy_temp_path /var/cache/nginx/proxy_temp;
    proxy_max_temp_file_size 4096m;

    # Timeouts for large pushes
    proxy_read_timeout 900s;
    proxy_send_timeout 900s;
    proxy_connect_timeout 60s;

    location /v2/ {
        proxy_pass http://docker-registry;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

tmpfs Cache Tuning

A subtle but devastating issue: if nginx’s temp file storage runs on a small filesystem, concurrent large pushes will fill it and return 502 errors with no useful log message. Mount tmpfs with adequate space:

# /etc/fstab entry
tmpfs /var/cache/nginx tmpfs defaults,size=2G,noexec,nosuid 0 0

# Apply without reboot
mount -o remount /var/cache/nginx

# Verify
df -h /var/cache/nginx

Size this at 2x your largest expected image layer. Multi-gigabyte ML model images can have individual layers exceeding 1GB. If you are regularly pushing images over 500MB, allocate at least 2GB for the tmpfs cache.

Registry Configuration

The registry itself needs hardening beyond defaults:

# /etc/docker-registry/config.yml
version: 0.1
log:
  level: info
  formatter: json

storage:
  filesystem:
    rootdirectory: /var/lib/registry
  delete:
    enabled: true  # Required for garbage collection
  maintenance:
    uploadpurging:
      enabled: true
      age: 168h      # Purge incomplete uploads after 7 days
      interval: 24h
      dryrun: false

http:
  addr: 127.0.0.1:5000   # Bind to loopback only
  host: https://registry.example.com
  headers:
    X-Content-Type-Options: [nosniff]
  http2:
    disabled: false

health:
  storagedriver:
    enabled: true
    interval: 10s
    threshold: 3

Network Segmentation

The registry should live on an isolated network segment accessible only to:

1. The reverse proxy (for client access)
2. CI/CD runners (for image pushes)
3. Container runtime hosts (for image pulls)

Using firewall rules:

# Allow reverse proxy to reach registry
iptables -A INPUT -s 10.0.1.10/32 -p tcp --dport 5000 -j ACCEPT

# Allow CI/CD runner subnet
iptables -A INPUT -s 10.0.5.0/24 -p tcp --dport 5000 -j ACCEPT

# Allow container host subnet
iptables -A INPUT -s 10.0.10.0/24 -p tcp --dport 5000 -j ACCEPT

# Drop everything else to registry port
iptables -A INPUT -p tcp --dport 5000 -j DROP

For environments using VLANs or software-defined networking, place the registry on a dedicated VLAN with ACLs enforcing the same restrictions at the network layer.

Token-Based Authentication

For environments with more than a handful of users, move beyond htpasswd to token-based authentication. The Docker registry supports a token authentication protocol where a separate auth service issues JWT tokens:

# Registry config addition
auth:
  token:
    realm: https://auth.example.com/token
    service: registry.example.com
    issuer: "Registry Auth Service"
    rootcertbundle: /etc/registry/auth-cert.pem
    autoredirect: false

The auth service validates credentials against your identity provider (LDAP, OIDC, etc.) and issues scoped tokens:

{
  "access": [
    {
      "type": "repository",
      "name": "myapp/backend",
      "actions": ["pull"]
    }
  ]
}

This enables fine-grained access control — developers can push to their project repositories but only pull from shared base images.

Image Signing with Cosign

Unsigned images are unverified images. Use Cosign to sign images at build time and verify signatures at pull time:

# Generate a signing keypair (store the private key securely)
cosign generate-key-pair

# Sign an image after pushing
cosign sign --key cosign.key registry.example.com/myapp/backend:v1.2.0

# Verify before deploying
cosign verify --key cosign.pub registry.example.com/myapp/backend:v1.2.0

Integrate signing into your CI/CD pipeline:

# .gitlab-ci.yml example
sign-image:
  stage: sign
  script:
    - docker push ${REGISTRY}/${IMAGE}:${TAG}
    - cosign sign --key ${COSIGN_PRIVATE_KEY} ${REGISTRY}/${IMAGE}:${TAG}
  only:
    - main

For keyless signing in CI/CD environments, use Cosign’s OIDC-based signing with Fulcio and Rekor:

# Keyless signing (uses OIDC identity from CI/CD environment)
COSIGN_EXPERIMENTAL=1 cosign sign ${REGISTRY}/${IMAGE}:${TAG}

Enforcing Signature Verification

Signing images is pointless if nothing enforces verification. Use a Kubernetes admission controller to reject unsigned images: