vps/compose/README.md

compose/ — repo-owned Compose declarations

Non-secret Compose sources for the Docker hosts. Secrets are never in these files: every secret is a ${VAR} reference resolved from the server-local .env (docker compose reads .env from the project directory automatically).

Source-of-truth matrix

Project	Host	Compose source	Mechanism
vaultwarden	us2 (/opt/vaultwarden)	compose/vaultwarden/compose.yml	static file + compose-deploy.yml
pdns	hk2 (/opt/pdns)	compose/pdns/compose.yml	static file + compose-deploy.yml
adguardhome	dns.windy.lan (/opt/adguardhome)	— (待从 LAN 提取)	static file (pending)
unifi	ubnt (/home/windy/unifi-9)	— (待从 LAN 提取)	static file (pending)
wireguard	us4 (/opt/wireguard)	ansible/templates/wireguard-compose.yml.j2	role-rendered (inventory vars)
rustdesk	hk2 (/opt/rustdesk)	ansible/roles/rustdesk/templates/compose.yml.j2	role-rendered (inventory vars)
mailcow	mx2 (/opt/mail)	— (mailcow update generator owns it)	excluded by design

Mechanism rule: static compose/<project>/compose.yml for declarations that do not vary per host; role-rendered j2 for declarations driven by inventory vars (image pins, relay host). One mechanism per project; do not duplicate a project in both.

Deploying a static project

cd ansible

# Read-only diff + validation against the server .env (no writes)
ansible-playbook playbooks/compose-deploy.yml --limit vaultwarden --check --diff

# Apply: stage repo file → validate `docker compose config -q` → backup current
# file → promote → `docker compose up -d` (gated)
ansible-playbook playbooks/compose-deploy.yml --limit vaultwarden \
  -e '{"compose_deploy_confirm": true}'

See ../runbooks/ansible-operations.md.

Adding a project

1. Sanitize the live compose so every secret is ${VAR} from .env (prefer ${VAR:?missing VAR} for required keys).
2. Commit compose/<project>/compose.yml + .env.example (key names only).
3. Add compose_repo_project (+ compose_remote_file if not compose.yml) to the host in ansible/inventory/hosts.yml, and allowlist the project in ansible/roles/compose_deploy/defaults/main.yml.
4. Verify with --check --diff (zero diff) then a gated apply.