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
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
@@ -0,0 +1,33 @@
|
||||
# Setup guides
|
||||
|
||||
Step-by-step setup procedures for new contributors. Each file is self-contained and idempotent — they document the state a developer should reach, not the order in which it must be done.
|
||||
|
||||
| # | File | Audience |
|
||||
| --- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 01 | [Debian 13 dev-VM setup](01-dev-debian-vm-setup.md) | **Default** — a dev who has just received a fresh dev VM from the infra team. Covers the full path: zsh + Oh My Zsh + Powerlevel10k, modern CLI tooling, Node via nvm, Docker CE, system tuning, optional VM hardening, project clones, the two IDE flows (VSCode Remote-SSH and Devcontainer), the hybrid (local + VM) mode. |
|
||||
| 02 | [WSL terminal setup](02-wsl-terminal-setup.md) | Legacy — the original Windows-WSL flow. Kept for reference for devs still on that path until the org migrates to the VM-based flow. |
|
||||
| 03 | [Dev web stack](03-dev-web-stack.md) | Notes on the web-side tooling. |
|
||||
| 04 | [Angular + Nx monorepo](04-angular-nx-monorepo.md) | Reference notes on the Angular + Nx workspace layout. |
|
||||
|
||||
## `scripts/`
|
||||
|
||||
Modular setup scripts called from the doc above. Each is idempotent, each can be re-run safely. Run via the orchestrator (`bootstrap.sh`) or individually.
|
||||
|
||||
| Script | Purpose |
|
||||
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [`bootstrap.sh`](scripts/bootstrap.sh) | Run every numbered script in order with a confirmation prompt at each step. |
|
||||
| [`lib.sh`](scripts/lib.sh) | Common helpers — colour logging, idempotent `apt_install` / `ensure_line`. |
|
||||
| [`10-base-packages.sh`](scripts/10-base-packages.sh) | apt + base packages every other script assumes (`curl wget git build-essential …`). |
|
||||
| [`20-zsh.sh`](scripts/20-zsh.sh) | zsh, Oh My Zsh, Powerlevel10k, autosuggestions, syntax-highlighting. Patches `~/.zshrc`. |
|
||||
| [`30-cli-tools.sh`](scripts/30-cli-tools.sh) | `bat eza fd-find ripgrep fzf zoxide ncdu keychain` + dev extras (`jq yq httpie make tree htop tmux direnv`). |
|
||||
| [`40-node.sh`](scripts/40-node.sh) | nvm + Node from the repo's `.nvmrc` + corepack pinned to `package.json#packageManager`'s pnpm version. |
|
||||
| [`50-docker.sh`](scripts/50-docker.sh) | Docker CE + compose plugin from docker.com apt repo + user added to `docker` group + service enabled at boot. |
|
||||
| [`60-tuning.sh`](scripts/60-tuning.sh) | inotify watches → 524288, optional 4 GB swapfile, optional hostname rename (only prompts if generic). |
|
||||
| [`70-hardening.sh`](scripts/70-hardening.sh) | Best-effort UFW + unattended-upgrades + fail2ban + sshd hardening drop-in. Probes before applying — skips done items. |
|
||||
| [`80-dotfiles.sh`](scripts/80-dotfiles.sh) | Symlinks `notes/aliases.zsh` → `~/.oh-my-zsh/custom/aliases.zsh`. Copies `notes/gitconfig.txt` to `~/.gitconfig` with prompted identity. |
|
||||
|
||||
## `systemd/`
|
||||
|
||||
| File | Purpose |
|
||||
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
||||
| [`apf-portal-infra@.service`](systemd/apf-portal-infra@.service) | Template unit auto-starting `./infra/local/dev.sh up` at boot for a given user. |
|
||||
Reference in New Issue
Block a user