hermes-skills/skills/devops/infrastructure-automation/references/docker-deployment-standard.md

Docker Service Deployment Standard (IT Pro Partner)

This reference documents the standard for deploying Docker services on ITP infrastructure.

Directory Structure

~/docker/<service-name>/
├── docker-compose.yml   ← Pinned image tags (never :latest)
├── .env                 ← Secrets only (never in compose file)
├── data/                ← Persistent volumes on disk (backed up by S3)
├── CHANGELOG.md         ← Every config change documented

Access: Tailscale-Only Standard

1. Deploy compose in ~/docker/<service>/
2. Verify local: curl -s http://localhost:<port>/
3. Open UFW: ufw allow <port>/tcp
4. Enable Tailscale Serve for HTTPS: tailscale serve --bg --https 443 --set-path / http://127.0.0.1:<port>
5. Set the service's base URL to https://<hostname>.tail<random>.ts.net
6. Test from a Tailscale-connected device
7. Close UFW port: ufw delete allow <port>/tcp
8. Log: bash ~/.hermes/scripts/changelog.sh "Networking" "Tailscale Serve for <service> at https://..."

Vaultwarden-Specific Notes

• DOMAIN env var must match the access URL exactly. Wrong protocol (http vs https) causes the web vault to hang on a spinner silently.
• Registration is disabled by default (SIGNUPS_ALLOWED=false). Enable it temporarily for first-user setup, then lock it.
• Admin panel at /admin uses the ADMIN_TOKEN from .env.
• Tailscale hostname with 0 vs O confusables: the Bitwarden mobile app may silently corrupt zero characters in the URL during text input. Fix: rename the Tailscale node before deploying: tailscale set --hostname vaultwarden. Then re-create Tailscale Serve (turn off, re-enable — it picks up the new hostname). No zeros, no letter-O confusion.
• Bitwarden app fails with "not a recognized Bitwarden server": always the DOMAIN/access-URL mismatch. Verify via curl https://<url>/api/config — the identity field must match exactly what the app connects to.

Backup

• Compose files and .env are synced to S3 every 15 min via hermes-live-sync
• For data directories: same sync includes ~/docker/*/data/*
• RPO: < 15 min for both config and data