# 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` (theme / plugins / fzf hook) and `~/.bashrc` (exec zsh — `chsh` blocked on corp VM). |
| [`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 (opt-in) + sshd hardening drop-in. Probes before applying — skips done items, prompts before each install.                      |
| [`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. |