Registry Stack Guide

RETIRED (2026-07-01). This stack (docker-registry + registry-admin) has been decommissioned and replaced by the Gitea package registry. See docs/runtime/stacks/gitea.mdx. The content below is retained for historical reference only.

The registry stack provides the private Docker registry and Registry Admin UI.

Source Of TruthCopy Anchor Link

• Compose: runtime/stacks/infrastructure/registry/docker-compose.registry.yml
• VPS env: runtime/environments/vps/infrastructure/registry/.env
• VPS placeholder: runtime/environments/vps/infrastructure/registry/registry.env
• Dev template: runtime/environments/dev/infrastructure/registry/registry.dev.env
• Launcher: runtime/scripts/infrastructure/registry.{sh,bat}
• Shared auth file: /var/lib/traefik/registry-auth/registry.htpasswd

Security ModelCopy Anchor Link

• registry.perspective-v.com is public and protected by Traefik basic auth.
• registry-admin.perspective-v.com is NetBird-only.
• Both use the shared htpasswd file.

Required VariablesCopy Anchor Link

• REGISTRY_HOST
• REGISTRY_ADMIN_HOST
• REGISTRY_TITLE
• REGISTRY_ADMIN_BOOTSTRAP_USER
• REGISTRY_ADMIN_BOOTSTRAP_PASSWORD
• REGISTRY_ADMIN_TOKEN_SECRET
• REGISTRY_RATE_LIMIT_AVERAGE
• REGISTRY_RATE_LIMIT_BURST

DeployCopy Anchor Link

Create the shared auth file once:

sudo mkdir -p /var/lib/traefik/registry-auth
sudo touch /var/lib/traefik/registry-auth/registry.htpasswd
sudo chmod 600 /var/lib/traefik/registry-auth/registry.htpasswd

Bring up Registry Admin first, then the registry service:

./runtime/scripts/infrastructure/registry.sh up registry-admin
./runtime/scripts/infrastructure/registry.sh up registry

Raw compose equivalents:

docker compose --env-file runtime/environments/vps/infrastructure/registry/.env -f runtime/stacks/infrastructure/registry/docker-compose.registry.yml up -d registry-admin
docker compose --env-file runtime/environments/vps/infrastructure/registry/.env -f runtime/stacks/infrastructure/registry/docker-compose.registry.yml up -d registry

ValidateCopy Anchor Link

./runtime/scripts/infrastructure/registry.sh ps
curl -Ik https://registry.perspective-v.com/v2/
curl -Ik https://registry-admin.perspective-v.com
docker login registry.perspective-v.com

Cleanup And Rehearsal HelpersCopy Anchor Link

• runtime/stacks/infrastructure/registry/scripts/registry-cleanup.sh
• runtime/stacks/infrastructure/registry/scripts/staging-rehearsal.sh

Examples:

cd runtime/stacks/infrastructure/registry
./scripts/registry-cleanup.sh run-monthly --policy-file ./cleanup-policy.json
./scripts/staging-rehearsal.sh --registry-url https://registry.perspective-v.com --registry-admin-url https://registry-admin.perspective-v.com --cleanup-policy ./cleanup-policy.json