docs(infra): document Compose profile + down/up symmetry gotcha (#67)
## Summary `docker compose -f infra/local/dev.compose.yml down -v` left pgweb and Jaeger running, with no error and no obvious diagnostic — they kept eating memory until the next reboot. Reason: Compose only operates on services whose profile is currently active. Bringing them up with `--profile dbtools` / `--profile observability` requires the same flag(s) on `down`, otherwise they're invisible to that command. Document the gotcha in `infra/README.md` "Local-dev stack" → "Operational tips", with the two pragmatic resolutions: 1. Pass the same flags on each command (most explicit). 2. Set `COMPOSE_PROFILES=dbtools,observability` once in the shell or `infra/local/.env`, and let it propagate to every `up` / `down` / `ps` invocation. ## Test plan - [ ] Bring up the full stack: `docker compose -f infra/local/dev.compose.yml --profile dbtools --profile observability up -d`. - [ ] `docker compose -f infra/local/dev.compose.yml down -v` (no flags) — confirms pgweb + jaeger keep running. - [ ] Run the documented "complete" command — confirms everything is gone. - [ ] Repeat with `COMPOSE_PROFILES` set; same outcome. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #67
This commit was merged in pull request #67.
This commit is contained in:
@@ -172,6 +172,18 @@ All ports are overridable via `.env` if the host machine has conflicts.
|
|||||||
### Operational tips
|
### 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).
|
- **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`.
|
- **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 <service>` to follow a single service. `otel-collector` is the loudest — its `debug` exporter prints every span / metric / log it receives.
|
- **Logs** — `docker compose -f dev.compose.yml logs -f <service>` 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.
|
- **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.
|
||||||
|
|||||||
Reference in New Issue
Block a user