julien/apf_portal
1
0
Fork 0
Code Issues 1 Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(decisions): add ADR-0030 dockerised full-stack dev mode (proposed) #256

Merged
julien merged 1 commits from docs/adr-0030-dockerised-dev-mode into main 2026-05-29 19:06:09 +02:00
Conversation 0 Commits 1 Files Changed 2
+113
julien commented 2026-05-29 18:51:41 +02:00
Owner
Copy Link
Copy Source

Summary

Propose ADR-0030 — Dockerised full-stack dev mode: an apps Compose profile that runs the three Nx apps (portal-bff, portal-shell, portal-admin) from a shared Dockerfile.dev, so a developer can docker compose up the whole stack with no native Node/pnpm on the host.

proposed status — this PR is the decision record only. The Dockerfile.dev + the apps profile + the BFF entrypoint land in a follow-up PR once the ADR is accepted.

Why

Two frictions motivate it:

  1. Infra is already in Docker (infra/local/dev.compose.yml), but the Nx apps run natively — every dev pays the nvm/corepack/pnpm setup cost. The recent fresh-VM .zshrc nvm gap is a concrete example of that path breaking.
  2. A developer asked to run all servers with a single docker compose up, no toolchain, no IDE attach.

Decision (chosen option)

An apps Compose profile backed by one shared Dockerfile.dev (node:24 + pinned pnpm), because it is purely additive:

  • ./infra/local/dev.sh up stays infra-only (native + devcontainer flows unchanged).
  • ./infra/local/dev.sh up apps brings up infra + the three dev servers with hot reload.

Key design points captured in the ADR (built in the follow-up): one image / one install for the monorepo; repo bind-mounted but node_modules + Nx cache in named volumes (native-module arch correctness); depends_on … service_healthy; BFF entrypoint does prisma generate + migrate deploy; services point at the existing apf-portal-dev Compose network.

The ADR documents a "which mode when" table so the three dev modes (native / devcontainer / compose-apps) coexist without confusion.

Scope guardrails

  • Dev-only. No production images here — those are tracked against the ADR-0028 Container Registry follow-up (post-cutover). The ADR is explicit that it produces no deployment artefact.
  • Complements ADR-0020's devcontainer (interactive/IDE) with a non-interactive services sibling; does not replace it.

Numbering

Takes 0030, not 0029. 0029 is reserved for the cascade/Pléiades/Acteurs+ syncs ADR (referenced by ADR-0026/0027/0028); numbers are never reused, so the dev-mode ADR takes the next free slot. The index gap at 0029 is intentional until that ADR is written.

What lands

File Change
docs/decisions/0030-dockerised-dev-mode.md New ADR, proposed.
docs/decisions/README.md Index row for 0030.

Test plan

  • MADR 4.0.0 frontmatter; tags drawn from the README vocabulary (infrastructure, process).
  • Index updated in the same commit (per the repo's index-maintenance rule).
  • R&D Lead review → accept / revise. On acceptance: update the CLAUDE.md architecture roll-up + add the "which mode when" guidance to docs/setup/, then open the implementation PR.

Related

  • ADR-0020 — VSCode devcontainer (the interactive no-toolchain path this complements).
  • ADR-0028 — Container Registry / production images (the deferred prod-image work).
  • ADR-0006 — Prisma; the entrypoint applies (never authors) migrations.
## Summary Propose **ADR-0030 — Dockerised full-stack dev mode**: an `apps` Compose profile that runs the three Nx apps (`portal-bff`, `portal-shell`, `portal-admin`) from a shared `Dockerfile.dev`, so a developer can `docker compose up` the whole stack with **no native Node/pnpm** on the host. `proposed` status — this PR is the **decision record only**. The `Dockerfile.dev` + the `apps` profile + the BFF entrypoint land in a follow-up PR once the ADR is accepted. ## Why Two frictions motivate it: 1. Infra is already in Docker (`infra/local/dev.compose.yml`), but the Nx apps run natively — every dev pays the nvm/corepack/pnpm setup cost. The recent fresh-VM `.zshrc` nvm gap is a concrete example of that path breaking. 2. A developer asked to run all servers with a single `docker compose up`, no toolchain, no IDE attach. ## Decision (chosen option) An **`apps` Compose profile** backed by **one shared `Dockerfile.dev`** (node:24 + pinned pnpm), because it is purely additive: - `./infra/local/dev.sh up` stays infra-only (native + devcontainer flows unchanged). - `./infra/local/dev.sh up apps` brings up infra + the three dev servers with hot reload. Key design points captured in the ADR (built in the follow-up): one image / one install for the monorepo; repo bind-mounted but `node_modules` + Nx cache in **named volumes** (native-module arch correctness); `depends_on … service_healthy`; BFF entrypoint does `prisma generate` + `migrate deploy`; services point at the existing `apf-portal-dev` Compose network. The ADR documents a "which mode when" table so the **three** dev modes (native / devcontainer / compose-`apps`) coexist without confusion. ## Scope guardrails - **Dev-only.** No production images here — those are tracked against the ADR-0028 Container Registry follow-up (post-cutover). The ADR is explicit that it produces no deployment artefact. - Complements ADR-0020's devcontainer (interactive/IDE) with a non-interactive services sibling; does not replace it. ## Numbering Takes **0030**, not 0029. `0029` is reserved for the cascade/Pléiades/Acteurs+ syncs ADR (referenced by ADR-0026/0027/0028); numbers are never reused, so the dev-mode ADR takes the next free slot. The index gap at 0029 is intentional until that ADR is written. ## What lands | File | Change | | --- | --- | | `docs/decisions/0030-dockerised-dev-mode.md` | New ADR, `proposed`. | | `docs/decisions/README.md` | Index row for 0030. | ## Test plan - [x] MADR 4.0.0 frontmatter; tags drawn from the README vocabulary (`infrastructure`, `process`). - [x] Index updated in the same commit (per the repo's index-maintenance rule). - [ ] R&D Lead review → accept / revise. On acceptance: update the CLAUDE.md architecture roll-up + add the "which mode when" guidance to `docs/setup/`, then open the implementation PR. ## Related - [ADR-0020](docs/decisions/0020-portal-admin-app.md) — VSCode devcontainer (the interactive no-toolchain path this complements). - [ADR-0028](docs/decisions/0028-migrate-cicd-and-git-hosting-to-gitlab.md) — Container Registry / production images (the deferred prod-image work). - [ADR-0006](docs/decisions/0006-persistence-postgresql-prisma.md) — Prisma; the entrypoint applies (never authors) migrations.
julien added 1 commit 2026-05-29 18:51:42 +02:00
docs(decisions): add ADR-0030 dockerised full-stack dev mode (proposed)
CI / scan (pull_request) Successful in 3m24s
Details
CI / commits (pull_request) Successful in 3m44s
Details
CI / check (pull_request) Successful in 3m53s
Details
CI / a11y (pull_request) Successful in 4m7s
Details
Docs site / build (pull_request) Successful in 4m18s
Details
CI / perf (pull_request) Successful in 8m36s
Details
774f279785 
Propose an 'apps' Compose profile backed by a shared Dockerfile.dev so
developers can 'docker compose up' all three Nx apps (portal-bff,
portal-shell, portal-admin) with no native Node/pnpm — addressing
onboarding friction (the nvm/.zshrc class of failure) and a concrete
request to run the whole stack in one command.

Decision-only, proposed status. Profile-gated so the native +
devcontainer flows are unchanged; dev-only (production images stay
with the ADR-0028 Container Registry follow-up). Takes number 0030
(0029 is reserved for the cascade/Pleiades/Acteurs+ syncs ADR).
julien merged commit 8a2a99c351 into main 2026-05-29 19:06:09 +02:00
julien deleted branch docs/adr-0030-dockerised-dev-mode 2026-05-29 19:06:12 +02:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adastra-bot (AdAstra Bot) julien (Julien Gautier)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: julien/apf_portal#256
Delete Branch "docs/adr-0030-dockerised-dev-mode"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?