feat(infra): add dev.sh wrapper for the local-dev compose stack
CI / commits (pull_request) Successful in 1m19s
CI / check (pull_request) Successful in 1m25s
CI / scan (pull_request) Successful in 1m28s
CI / a11y (pull_request) Successful in 1m37s
CI / perf (pull_request) Successful in 3m37s

Direct `docker compose -f infra/local/dev.compose.yml ...` works
fine, but two things kept biting on this stack:

- Compose-profile asymmetry — `down` only operates on services
  whose profile is currently active, so anything brought up with
  `--profile X` keeps running unless the same flag is on `down`.
  pgweb and Jaeger silently survived several `down -v` invocations
  before we spotted it.
- Verbose invocations — typing the compose-file flag and the
  profile flags on every command for routine ops gets old fast.

Add `infra/local/dev.sh` as a thin wrapper:

  ./infra/local/dev.sh up                 # core only
  ./infra/local/dev.sh up all             # core + every profile
  ./infra/local/dev.sh up dbtools         # core + pgweb
  ./infra/local/dev.sh up observability   # core + Jaeger
  ./infra/local/dev.sh down [-v]          # always with all profiles
  ./infra/local/dev.sh stop <service>     # stop one service
  ./infra/local/dev.sh restart <service>  # restart one service
  ./infra/local/dev.sh status             # ps with all profiles
  ./infra/local/dev.sh logs [service]     # follow logs
  ./infra/local/dev.sh exec <svc> <cmd>   # run inside a container

Anything not matching one of the named verbs is passed through to
`docker compose -f dev.compose.yml ...` (with every profile flagged
in), so the full Compose surface remains available without losing
the profile-symmetry guarantee.

Docs:

- `infra/README.md` "Local-dev stack" — new "Convenience script"
  subsection with the cheat-sheet table; "First-time setup" walk-
  through rewritten to use the script; the previous standalone
  "Profiles must match on `down` as on `up`" tip is collapsed
  into a one-liner since the script handles it.
- `docs/development.md` §3 — point at the script for the typical
  setup flow.

The compose file itself is unchanged.
This commit is contained in:
Julien Gautier
2026-05-09 21:45:54 +02:00
parent 4d2d4d652a
commit 7a475a52fb
3 changed files with 190 additions and 25 deletions
+6 -5
View File
@@ -99,7 +99,7 @@ cd apps/portal-bff && pnpm exec prisma generate && cd ../..
pnpm nx run-many -t lint test build
```
For the BFF to actually run end-to-end, you'll also need the local infrastructure stack — Postgres, Redis, OpenTelemetry Collector — provisioned via Docker Compose:
For the BFF to actually run end-to-end, you'll also need the local infrastructure stack — Postgres, Redis, OpenTelemetry Collector — provisioned via Docker Compose. A thin wrapper script ([`infra/local/dev.sh`](../infra/local/dev.sh)) hides Compose-profile quirks and gives ergonomic verbs:
```bash
# 1. Configure infra secrets (copy template, edit, do not commit).
@@ -108,11 +108,12 @@ $EDITOR infra/local/.env
# Set strong dev values for POSTGRES_PASSWORD and REDIS_PASSWORD.
# 2. Bring up the core stack (postgres + redis + otel-collector).
docker compose -f infra/local/dev.compose.yml up -d
./infra/local/dev.sh up
# 3. (Optional) Activate viewers when debugging:
docker compose -f infra/local/dev.compose.yml --profile dbtools up -d # pgweb
docker compose -f infra/local/dev.compose.yml --profile observability up -d # Jaeger UI
./infra/local/dev.sh up dbtools # adds pgweb (http://localhost:8081)
./infra/local/dev.sh up observability # adds Jaeger UI (http://localhost:16686)
./infra/local/dev.sh up all # core + every profile
# 4. App-side env from .env.example, then fill in DATABASE_URL pointing
# to the compose-managed Postgres (matches the values you set in
@@ -120,7 +121,7 @@ docker compose -f infra/local/dev.compose.yml --profile observability up -d #
cp apps/portal-bff/.env.example apps/portal-bff/.env
```
Full reference for the local stack — service inventory, port table, persistence, bootstrap re-run procedure — lives in [`infra/README.md`](../infra/README.md) → "Local-dev stack".
`./infra/local/dev.sh help` lists the rest of the verbs (`down`, `status`, `logs`, `stop`, `restart`, `exec`). Full reference — service inventory, port table, persistence, bootstrap re-run procedure — lives in [`infra/README.md`](../infra/README.md) → "Local-dev stack".
---