Private Docker registry with Nginx HTTPS and native authentication

Run on a test client. First use the unauthenticated curl check, then the helper-backed Docker login with a deliberately wrong password typed only at the private prompt. A valid TLS connection must return401 for missing/wrong credentials. Re-enter the correct password after the denial test. Do not record prompt values, Authorization headers or helper output. Native htpasswd is broad access: a successful login is not a repository permission test.

curl --silent --show-error --output /dev/null --write-out '%{http_code}
' 'https://registry.example.net/v2/'
docker --config "$HOME/.config/academy-registry-client" login 'registry.example.net' --username 'academy-publisher'

On the VM, stop new writers and allow in-flight uploads to finish before restarting this one container. Then repeat the independent clean-client pull and compare the recorded manifest digest. The 401 health result alone proves neither storage persistence nor complete image availability. Restart persistence is not a backup restore rehearsal or reboot test.

set -eu
sudo docker restart --time 90 'academy-registry'
curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' 'https://registry.example.net/v2/'

Run on the VM; share only sanitized status, never full config/auth files. A413 points first to 1024 MiB per-request limits; include every upstream load balancer in that check. A stalled streamed push calls for checking HTTP/1.1, request buffering, 900-second idle intervals, disk/inodes and write permissions. A502 calls for listener/container status. A401 with correct credentials calls for bcrypt format, selected username and restart after a controlled rotation.

If an upload Location points to HTTP, an internal hostname or another port, stop: inspect the fixed external host and forwarded scheme, not client insecure-registry settings. TLS errors call for SAN/chain/time/managed CA trust checks. The following panel prints no credentials. Nginx access logging is off; keep error logs protected because request context may still be sensitive.

sudo docker inspect 'academy-registry' --format '{{.State.Status}} {{.State.ExitCode}}'
sudo stat -c '%a %u:%g %n' '/srv/academy-registry/data' '/srv/academy-registry/auth/htpasswd' '/srv/academy-registry/config/config.yml'
sudo df -h '/srv/academy-registry/data'
sudo df -i '/srv/academy-registry/data'
sudo nginx -t
curl --silent --show-error --dump-header - --output /dev/null 'https://registry.example.net/v2/'

Schedule an outage, stop all CI pushes, let uploads finish and stop the registry. With every writer stopped, snapshot data plus config/auth/TLS at one consistency point. The archive below is a root-only local staging artifact containing secrets; encrypt and transfer it off-host using your existing approved backup system. A local copy on the same disk is not disaster recovery. On failure leave writers stopped until the failure is understood; do not blindly resume in a trap.

For a future multi-instance or object-store design, stopping one container is insufficient. Coordinate all writers, storage snapshots, database/token-service dependencies and version compatibility. Rehearse restoration into a separate isolated VM with the same pinned version, protected credentials and independent trust/hostname; validate manifests, every referenced blob and a clean-client pull before admitting writers. That restore is a required operational acceptance exercise, not claimed as executed here.

set -eu
sudo docker stop --time 90 'academy-registry'
sudo test "$(sudo docker inspect --format '{{.State.Running}}' 'academy-registry')" = false
sudo python3 - <<'PY'
import os, subprocess
from pathlib import Path
root=Path('/srv/academy-registry')
dest=root/'recovery'/'consistent-backup.tar'
fd=os.open(dest,os.O_WRONLY|os.O_CREAT|os.O_EXCL|os.O_NOFOLLOW,0o600)
with os.fdopen(fd,'wb') as out:
    subprocess.run(['tar','--numeric-owner','-C',str(root),'-cf','-','data','config','auth','tls'],stdout=out,check=True)
print('Stopped-writer snapshot created; transfer encrypted off-host before resuming')
PY
sudo docker start 'academy-registry'

Deleting a tag or manifest is different from reclaiming blobs. The current service has API deletion disabled. Enabling deletion later requires an authorization/retention decision and version-matched API semantics; it is not needed for push/pull. Never delete storage files manually. Garbage collection marks referenced objects then sweeps unreferenced objects; concurrent uploads can lose layers.

The panel performs only a dry run while the service is fully stopped, with read-only data and the exact pinned image. Even dry-run output can disclose repository names, so keep it private. After a reviewed backup and isolated restore rehearsal, destructive GC needs a separate deliberate maintenance action; omit --delete-untagged unless you explicitly accept its tag/digest and multi-platform consequences. Alternatively readonly maintenance requires restart of every writer into readonly mode and observed write denial before GC; do not merely edit YAML while it is running.

set -eu
sudo docker stop --time 90 'academy-registry'
sudo test "$(sudo docker inspect --format '{{.State.Running}}' 'academy-registry')" = false
sudo docker run --rm --network none --user '23153:23153' \
  --read-only --cap-drop ALL --security-opt no-new-privileges --log-driver none \
  --mount 'type=bind,src=/srv/academy-registry/data,dst=/var/lib/registry,readonly' \
  --mount 'type=bind,src=/srv/academy-registry/auth,dst=/auth,readonly' \
  --mount 'type=bind,src=/srv/academy-registry/config,dst=/etc/distribution,readonly' \
  --entrypoint /bin/registry 'docker.io/library/registry:3.1.2@sha256:ddf754342cfc8acc51a56d5d0ab6af06826461864460636d8bd5c546dab2a7b8' \
  garbage-collect --dry-run /etc/distribution/config.yml
sudo docker start 'academy-registry'