feat(infra): dockerised full-stack dev mode — apps compose profile (ADR-0030) (#258)

## Summary Implements [ADR-0030](../docs/decisions/0030-dockerised-dev-mode.md) (now `accepted`): a Docker Compose `apps` profile that runs the three Nx dev servers (`portal-bff`, `portal-shell`, `portal-admin`) from a shared `Dockerfile.dev`, so a developer can boot the whole stack with **no native Node/pnpm**: ```bash ./infra/local/dev.sh up apps # infra + portal-bff:3000 + portal-shell:4200 + portal-admin:4300 ``` Purely additive and profile-gated — the native `nx serve` flow and the devcontainer are untouched. Dev-only; no production images (those stay with the ADR-0028 Container Registry work). ## What lands | File | Change | | --- | --- | | `docs/decisions/0030-dockerised-dev-mode.md` | Status `proposed` → `accepted`. | | `docs/decisions/README.md` | Index status → `accepted`. | | `infra/local/Dockerfile.dev` | **New.** `node:24-bookworm` + corepack (pnpm resolved from `packageManager` at runtime — no pinned version to drift). No COPY/install at build time. `NX_DAEMON=false`, `NODE_OPTIONS=--max-old-space-size=4096`. | | `infra/local/dev-entrypoint.sh` | **New.** Shared entrypoint: BFF (`APF_ROLE=bff`) runs `prisma generate` + `prisma migrate deploy` then serves; SPA services go straight to `nx serve`. | | `infra/local/dev.compose.yml` | **New `apps` profile.** A one-shot `apps-deps` service installs into a shared `node_modules` volume once (the 3 servers gate on its `service_completed_successfully`, avoiding a 3-way install race); `portal-bff` / `portal-shell` / `portal-admin` services from the shared image via a `x-app-base` anchor. Repo bind-mounted; `node_modules` + `.nx` in named volumes. | | `infra/local/dev.sh` | `apps` added to `ALL_PROFILES` (so teardown / status / logs catch it) + usage / examples. | | `infra/README.md` | New "Dockerised app dev mode" section + cheat-sheet / file-table rows. | | `docs/setup/01-dev-debian-vm-setup.md` | "Three dev modes — which when" table at the top of Step 5. | | `CLAUDE.md` | Architecture roll-up bullet + ADR-count line + environment-conventions note. | ## Key design decisions - **One image, one install.** The monorepo means a single `Dockerfile.dev` + a single `pnpm install` serves all three apps. - **`node_modules` + `.nx` in named volumes, not bind-mounted.** The container's install (native modules — `esbuild`, `@swc/core`, Prisma engines, `lmdb`, `@parcel/watcher` — built for this image) must never be shadowed by the host's `node_modules`. The repo source is bind-mounted for hot reload; these two directories are overlaid with named volumes. - **`apps-deps` one-shot avoids the install race.** Three services sharing one `node_modules` volume can't all run `pnpm install` concurrently. A dedicated install service runs first; the three app services `depends_on` its completion. - **`NX_DAEMON=false`** in the containers — three containers sharing one workspace would otherwise contend on the Nx daemon. - **Env wiring.** The BFF reuses its own `apps/portal-bff/.env` (Entra / session / jwks secrets) via `env_file: { required: false }`; the host-specific URLs (`DATABASE_URL` / `REDIS_URL` / OTel endpoint) are overridden in `environment:` — rebuilt from `infra/local/.env` creds → Compose service names. Compose `environment` wins over `env_file`, so the localhost values in the BFF `.env` don't leak into the container. - **BFF still needs its secrets.** "No native toolchain" ≠ "no config". `apps/portal-bff/.env` must exist (same as native dev); `required: false` lets SPA-only devs `up` without it (the BFF then fails its own boot validators with a clear message). ## Validation on the VM - [x] `docker compose -f dev.compose.yml --profile apps config` validates (YAML, anchors / merge, env interpolation). - [x] `bash -n` clean on `dev-entrypoint.sh` and `dev.sh`. - [x] **Full boot on vm-dev** — `./infra/local/dev.sh up apps` brings up postgres / redis / otel + `apps-deps` (one-shot, exit 0) + portal-bff / portal-shell / portal-admin, all containers report healthy or running. - [x] `apps-deps` populates the shared `node_modules` volume; the three servers reach their `nx serve` step without re-installing. - [x] Ports published as expected: BFF :3000, portal-shell :4200, portal-admin :4300. - [x] `./infra/local/dev.sh up` (no `apps`) unchanged for native devs. ## Follow-ups identified during VM validation - **SPA → BFF reachability from a remote browser.** Opening `http://<vm-ip>:4200/` from the workstation surfaces a "Backend unreachable" message: the SPA's hardcoded `bffApiBaseUrl: 'http://localhost:3000/api'` (ADR-0018 build-time env) plus the BFF's `CORS_ALLOWED_ORIGINS=http://localhost:4200,…` both assume "browser on the same machine as the BFF", which doesn't hold here. Fixed in the **stacked follow-up PR `feat/spa-dev-proxy`** (proxy `/api` in the Angular dev-server + relative `bffApiBaseUrl`), which lands right after this PR. - The OTel HTTP exporter URL (`environment.otlpEndpoint`) and the cross-SPA links (`adminAppUrl`, `shellAppUrl`) remain absolute and hit the same remote-browser limit; not blocking for v1, can be revisited if needed. ## Related - [ADR-0030](docs/decisions/0030-dockerised-dev-mode.md) — the decision (accepted in this PR's chain). - [ADR-0020](docs/decisions/0020-portal-admin-app.md) — the devcontainer this complements. - [ADR-0028](docs/decisions/0028-migrate-cicd-and-git-hosting-to-gitlab.md) — production images / Container Registry (deferred). - Follow-up branch `feat/spa-dev-proxy` — the SPA-side proxy fix that makes the dockerised mode usable from a remote browser. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #258
2026-06-01 11:11:44 +02:00
parent 8a2a99c351
commit c080d1ad89
9 changed files with 216 additions and 14 deletions
@@ -0,0 +1,35 @@
+# Dev-only image for the dockerised full-stack dev mode (ADR-0030).
+#
+# One image serves all three Nx apps (portal-bff / portal-shell /
+# portal-admin) — the monorepo means a single install. The image is
+# intentionally minimal: Node + corepack, nothing copied in. The repo
+# is bind-mounted at runtime and dependencies install into a named
+# volume (see dev.compose.yml `apps` profile), so node_modules — with
+# its native modules built for THIS image — is never shadowed by the
+# host's.
+#
+# NOT a production image. Production artefacts are out of scope per
+# ADR-0030 and tracked against the ADR-0028 Container Registry work.
+FROM node:24-bookworm
+
+# corepack ships with Node 24. Enabling it lets pnpm resolve from the
+# `packageManager` field in package.json at runtime — no version pinned
+# here, so this image never drifts from the repo's pinned pnpm.
+RUN corepack enable
+
+# Nx + Angular CLI memory ceiling — matches the devcontainer (.devcontainer/
+# devcontainer.json). 4 GB avoids OOM on large `nx` graph work.
+ENV NODE_OPTIONS=--max-old-space-size=4096
+# Nx daemon is per-container and would contend across the three app
+# containers sharing one workspace bind-mount — disable it. Slight
+# task-graph cost, robust behaviour.
+ENV NX_DAEMON=false
+
+WORKDIR /workspace
+
+# No COPY / no install at build time: the repo is bind-mounted and the
+# `apps-deps` one-shot service installs into the node_modules volume on
+# first boot. Build context stays tiny (just infra/local/) — nothing is
+# copied. Invoked via `bash` so it does not depend on the bind-mounted
+# script keeping its executable bit.
+ENTRYPOINT ["bash", "/workspace/infra/local/dev-entrypoint.sh"]
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Shared entrypoint for the ADR-0030 `apps` Compose profile services.
+#
+# Behaviour is driven by env + the passed command:
+#   - The `apps-deps` one-shot service runs `pnpm install` as its
+#     command; this entrypoint just execs it (APF_ROLE unset → no
+#     prisma). It populates the shared node_modules volume once, so
+#     the app services don't race three concurrent installs.
+#   - The BFF service sets APF_ROLE=bff → this entrypoint runs
+#     `prisma generate` + `prisma migrate deploy` (client + committed
+#     migrations) before serving. `migrate deploy`, never `migrate
+#     dev` — a container never authors migrations.
+#   - The SPA services (portal-shell / portal-admin) leave APF_ROLE
+#     unset → straight to `exec "$@"` (nx serve).
+set -euo pipefail
+cd /workspace
+
+if [[ "${APF_ROLE:-}" == "bff" ]]; then
+  echo "[dev-entrypoint] BFF: prisma generate"
+  pnpm exec prisma generate
+  echo "[dev-entrypoint] BFF: prisma migrate deploy"
+  pnpm exec prisma migrate deploy
+fi
+
+echo "[dev-entrypoint] exec: $*"
+exec "$@"
@@ -34,6 +34,23 @@

 name: apf-portal-dev

+# Shared base for the ADR-0030 `apps` profile — dev servers for the three
+# Nx apps. The repo is bind-mounted for hot reload; node_modules and the
+# Nx cache live in named volumes so the container's install (native
+# modules built for THIS image) is never shadowed by the host's.
+x-app-base: &app-base
+  build:
+    context: .
+    dockerfile: Dockerfile.dev
+  profiles: [apps]
+  working_dir: /workspace
+  volumes:
+    - ../../:/workspace
+    - app-node-modules:/workspace/node_modules
+    - app-nx-cache:/workspace/.nx
+  networks:
+    - apf-portal-dev
+
 services:
  postgres:
    image: postgres:17.2-alpine
@@ -189,11 +206,87 @@ services:
    networks:
      - apf-portal-dev

+  # ------------------------------------------------------------------
+  # ADR-0030 dockerised full-stack dev mode (`--profile apps`).
+  #
+  #   ./infra/local/dev.sh up apps   → infra + the three dev servers,
+  #                                    no native Node/pnpm on the host.
+  #
+  # Hot reload via the repo bind-mount. See docs/setup/ for the
+  # "which mode when" guidance (native / devcontainer / compose apps).
+  # NOTE: the SPA dev servers default to 4200/4300 — the same 4200 the
+  # `serve-static` profile uses; don't run `apps` and `serve-static`
+  # together, or override SHELL_PORT.
+  # ------------------------------------------------------------------
+
+  # One-shot: populate the shared node_modules volume once so the three
+  # app services don't race three concurrent installs on it. Exits when
+  # done; the apps gate on its successful completion.
+  apps-deps:
+    <<: *app-base
+    container_name: apf-portal-apps-deps
+    command: ['pnpm', 'install', '--frozen-lockfile']
+
+  portal-bff:
+    <<: *app-base
+    container_name: apf-portal-bff-dev
+    environment:
+      APF_ROLE: bff
+      NODE_ENV: development
+      PORT: '3000'
+      # Host-specific URLs rebuilt from infra/local/.env creds → Compose
+      # service names. Compose `environment` wins over `env_file`, so
+      # these override the localhost values in the BFF's own .env.
+      DATABASE_URL: 'postgresql://${POSTGRES_USER:-portal}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-portal_dev}?schema=public'
+      REDIS_URL: 'redis://default:${REDIS_PASSWORD}@redis:6379/0'
+      OTEL_EXPORTER_OTLP_ENDPOINT: 'http://otel-collector:4318/v1/traces'
+    # Secrets (Entra / session / jwks) come from the BFF's own dev env.
+    # `required: false` so SPA-only devs can `up` without it — the BFF
+    # then fails its own boot-time config validators with a clear message
+    # rather than Compose erroring on a missing file.
+    env_file:
+      - path: ../../apps/portal-bff/.env
+        required: false
+    command: ['pnpm', 'exec', 'nx', 'serve', 'portal-bff']
+    ports:
+      - '${BFF_PORT:-3000}:3000'
+    depends_on:
+      apps-deps:
+        condition: service_completed_successfully
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+
+  portal-shell:
+    <<: *app-base
+    container_name: apf-portal-shell-dev
+    command: ['pnpm', 'exec', 'nx', 'serve', 'portal-shell', '--host', '0.0.0.0', '--port', '4200']
+    ports:
+      - '${SHELL_PORT:-4200}:4200'
+    depends_on:
+      apps-deps:
+        condition: service_completed_successfully
+
+  portal-admin:
+    <<: *app-base
+    container_name: apf-portal-admin-dev
+    command: ['pnpm', 'exec', 'nx', 'serve', 'portal-admin', '--host', '0.0.0.0', '--port', '4300']
+    ports:
+      - '${ADMIN_PORT:-4300}:4300'
+    depends_on:
+      apps-deps:
+        condition: service_completed_successfully
+
 volumes:
  postgres-data:
    name: apf-portal-postgres-data
  redis-data:
    name: apf-portal-redis-data
+  app-node-modules:
+    name: apf-portal-app-node-modules
+  app-nx-cache:
+    name: apf-portal-app-nx-cache

 networks:
  apf-portal-dev:
@@ -16,7 +16,7 @@ COMPOSE_FILE="${SCRIPT_DIR}/dev.compose.yml"

 # Profiles defined in dev.compose.yml. Keep in sync if a new profile
 # is added.
-ALL_PROFILES=(dbtools observability serve-static)
+ALL_PROFILES=(dbtools observability serve-static apps)

 # Build "--profile p1 --profile p2 …" as separate arguments.
 build_all_profile_flags() {
@@ -60,6 +60,10 @@ Commands:
                          dbtools        core + pgweb
                          observability  core + jaeger
                          serve-static   core + caddy (production-build reverse proxy)
+                          apps           core + the three Nx dev servers in
+                                         Docker — no native Node/pnpm needed
+                                         (ADR-0030). portal-bff:3000,
+                                         portal-shell:4200, portal-admin:4300.
                          Multiple targets allowed (e.g. `up dbtools observability`).

  down [-v]             Tear the stack down. Always runs with every
@@ -87,6 +91,7 @@ Commands:
 Examples:
  ./infra/local/dev.sh up
  ./infra/local/dev.sh up all
+  ./infra/local/dev.sh up apps
  ./infra/local/dev.sh up observability
  ./infra/local/dev.sh down -v
  ./infra/local/dev.sh stop pgweb