windyboyandCursor
343c5db415
Keep sanitized Compose sources in-repo with a confirmation-gated Ansible playbook, add repo-wide validation, tighten runbook ownership/STOP/review metadata, and archive stale research docs. Co-authored-by: Cursor <cursoragent@cursor.com>
49 lines
2.4 KiB
Markdown
49 lines
2.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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`](../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.
|