Docker — DevOps Guide

Architecture

The Docker registry consists of three containers:

1. registry-docker-token-server — Custom Python token server validating against Authelia users
2. registry-docker — Registry v3 API server
3. registry-docker-ui — Joxit web UI (behind Authelia forward-auth)

Management

cd /opt/services/registries

# Start/stop
task up:docker
task down:docker

# Logs
task logs:docker

# List images
task docker:catalog

# Regenerate service token
task docker:token:generate

Token Server

The custom token server authenticates podman login / docker login requests against Authelia's users_database.yml.

• Source: docker/token-server/server.py
• Config: Environment variables in compose file
• Certs: docker/config/token-server-key.pem and token-server-cert.pem

Pydantic Configuration

The token server uses Pydantic models for configuration (docker/token-server/config.py). Config values are loaded in order of precedence:

1. YAML config file — docker/token-server/config.yaml
2. Environment variables — prefixed with TOKEN_SERVER_ (e.g. TOKEN_SERVER_TOKEN__ISSUER)

Nested config sections:

Section	Purpose
certificates	TLS key/cert paths for JWT signing
token	Issuer, expiration, service name
authelia	User database path, session settings
sso_badge	Badge appearance and links
acl	Access control rules
cors	CORS origins and headers
docker_registry	Upstream registry URL

JSON Schema Export

# CLI — print JSON Schema to stdout
python -m token_server --json-schema

# API — fetch schema from running server
curl https://docker.registry.hochguertel.work/auth/config/schema

Regenerate Certificates

openssl req -x509 -newkey rsa:4096 -keyout docker/config/token-server-key.pem \
  -out docker/config/token-server-cert.pem -days 365 -nodes \
  -subj "/CN=registry-token-server"

# Generate JWKS
# ... (automated by token server)

task down:docker && task up:docker

Backup

# Backup registry data
tar -czf docker-backup-$(date +%Y%m%d).tar.gz data/docker/registry/

Garbage Collection

Docker Registry v3 handles garbage collection via maintenance config in docker/config/registry.yml:

storage:
  maintenance:
    uploadpurging:
      enabled: true
      age: 168h
      interval: 24h