From c5b2c1fc482b79f3491187979c6cf6434e391152 Mon Sep 17 00:00:00 2001 From: Julien Gautier Date: Sat, 9 May 2026 21:16:42 +0200 Subject: [PATCH] docs(infra): document Compose profile + down/up symmetry gotcha MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docker compose down -v` left pgweb and jaeger running (under `--profile dbtools` / `--profile observability` respectively), with no obvious diagnostic. Reason: Compose only operates on services whose profile is currently active — if you brought them up with a flag, you must `down` with the same flag, otherwise they are invisible to that command. Document the gotcha in `infra/README.md` "Local-dev stack" → "Operational tips", with the two pragmatic resolutions: pass the same flags on each command, or set `COMPOSE_PROFILES` once and let it propagate. --- infra/README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/infra/README.md b/infra/README.md index 26d4e91..e4d14d1 100644 --- a/infra/README.md +++ b/infra/README.md @@ -172,6 +172,18 @@ All ports are overridable via `.env` if the host machine has conflicts. ### Operational tips - **Persistence** — state lives in named Docker volumes (`apf-portal-postgres-data`, `apf-portal-redis-data`). Survives `docker compose down`. Use `docker compose -f dev.compose.yml down -v` to wipe (also wipes the audit-roles bootstrap, which re-runs on the next fresh boot). +- **Profiles must match on `down` as on `up`** — `docker compose down` only acts on services whose profile is currently active. If you brought the stack up with `--profile dbtools --profile observability`, those same flags are required on `down` to also stop pgweb and Jaeger; otherwise they keep running until the next reboot. Two pragmatic patterns: + + ```bash + # Either pass the same flags on each command: + docker compose -f dev.compose.yml --profile dbtools --profile observability down -v + + # Or set COMPOSE_PROFILES once (e.g. in your shell or in infra/local/.env) + # so every `up` / `down` / `ps` sees the right scope: + export COMPOSE_PROFILES=dbtools,observability + docker compose -f dev.compose.yml down -v + ``` + - **Bootstrap re-run** — the SQL in `local/init/postgres/` only runs on a **fresh** Postgres data volume. To replay after editing the file, `down -v` (loses all dev data) or run the SQL manually with `docker compose exec postgres psql -U portal -d portal_dev -f /docker-entrypoint-initdb.d/01-init.sql`. - **Logs** — `docker compose -f dev.compose.yml logs -f ` to follow a single service. `otel-collector` is the loudest — its `debug` exporter prints every span / metric / log it receives. - **Image upgrades** — same policy as the runner image (deliberate, not via `:latest`). Renovate's docker-compose manager will surface bumps automatically once the dashboard rule allows them.