docs(setup): add Debian 13 dev-VM setup procedure + scripts + devcontainer
CI / commits (pull_request) Successful in 2m52s
CI / check (pull_request) Successful in 3m3s
CI / scan (pull_request) Successful in 3m11s
CI / a11y (pull_request) Successful in 3m5s
Docs site / build (pull_request) Successful in 3m10s
CI / perf (pull_request) Successful in 6m53s

New procedure in docs/setup/01-dev-debian-vm-setup.md targeting the new
dev VM (10.100.201.21, Debian 13) that replaces the WSL workflow. The
existing setup files are renumbered (01->02, 02->03, 03->04) to free
prefix 01 for the default flow.

10 modular idempotent scripts under docs/setup/scripts/ install the
stack: zsh + Oh My Zsh + Powerlevel10k + plugins, modern CLI tooling
(bat, eza, fd-find, ripgrep, fzf, zoxide, ncdu, keychain + dev extras),
nvm + Node from .nvmrc + corepack + pnpm, Docker CE + compose plugin,
inotify watches + swap + hostname tuning, best-effort UFW + sshd
hardening that probes-before-applying, and notes/aliases.zsh +
notes/gitconfig.txt installation.

A systemd template (apf-portal-infra@.service) auto-starts the local
dev infra stack at boot per user.

.devcontainer/ ships a VSCode Dev Container spec pinning Node 24 and
attaching to the host's apf-portal-dev Compose network so postgres /
redis / otel resolve by DNS from inside the container. initializeCommand
fails fast if the infra hasn't been brought up yet.

CLAUDE.md Environment conventions documents the two envs (local +
development) plus the hybrid sub-mode (workstation IDE + VM infra via
SSH LocalForward) and the two IDE flows (Remote-SSH + Devcontainer).

Adjacent follow-ups (not in this PR): preview infra on the GitLab VM
(10.100.201.10), GitLab Runner migration alongside the Gitea -> GitLab
cutover, private dotfiles repo.
This commit is contained in:
Julien Gautier
2026-05-24 18:37:57 +02:00
parent 0d8b3712fb
commit f70b1d3a1b
19 changed files with 1236 additions and 22 deletions
+3 -1
View File
@@ -108,8 +108,10 @@ pnpm nx format:check
## Environment conventions
- **Two development environments.** `local` (Windows-WSL or native macOS / Linux on the workstation) and `development` (Debian 13 VM at `10.100.201.21` — the default for new devs, replaces WSL). A `hybrid` sub-mode runs the IDE + Nx servers on the workstation while reaching the infra services (postgres / redis / otel) on the dev VM through SSH tunnels. Full procedure: [docs/setup/01-dev-debian-vm-setup.md](docs/setup/01-dev-debian-vm-setup.md). The legacy WSL flow remains documented in [docs/setup/02-wsl-terminal-setup.md](docs/setup/02-wsl-terminal-setup.md).
- **Two IDE flows on the dev VM** — VSCode Remote-SSH (default; transparent equivalent of the WSL flow) and Devcontainer (`.devcontainer/devcontainer.json` shipped, Node + pnpm pinned in the image, mounts the docker socket so the host's `apf-portal-dev` Compose network is reachable from inside).
- **Never install Angular globally.** Use `pnpm dlx` for one-off CLI invocations and project-local `pnpm nx ...` for everything else — versions stay pinned per project.
- **Work inside the WSL filesystem** (`~/dev/...`), never under `/mnt/c` — the latter has severe I/O penalties that break Nx caching and dev-server reload times.
- **On WSL: work inside the WSL filesystem** (`~/Works/...`), never under `/mnt/c` — the latter has severe I/O penalties that break Nx caching and dev-server reload times. On the dev VM the analogous rule is "stay on the VM disk, do not work over SSHFS / network mounts".
- **pnpm is mandatory** (activated via `corepack enable`); do not introduce npm or yarn lockfiles.
- Prettier config target: `singleQuote: true`, `semi: true`, `printWidth: 100`.