julien
c77313c693
## Summary Follow-up fix on [#220](#220). The corp infra locks the default shell at user-provisioning time on the dev VM (`10.100.201.21`) — `chsh` is denied at the PAM level, so the `sudo chsh -s` block in [`20-zsh.sh`](docs/setup/scripts/20-zsh.sh) fails on every fresh VM. Switch to the `~/.bashrc` exec-zsh hand-off — the same proven pattern used in the legacy [`02-wsl-terminal-setup.md`](docs/setup/02-wsl-terminal-setup.md). UX-identical for the dev, zero infra escalation required. ## What lands | File | Change | | --- | --- | | `docs/setup/scripts/20-zsh.sh` | Drop the `sudo chsh -s` block. Append a guarded `exec zsh -l` block to `~/.bashrc` instead, marked with a managed-by comment for idempotency on re-runs. | | `docs/setup/01-dev-debian-vm-setup.md` | Table row for `20-zsh.sh` updated — "set as default shell" → "`~/.bashrc` (exec zsh on interactive shells — `chsh` is blocked on the corp VM)". | | `docs/setup/README.md` | Same descriptor adjustment. | ## The hand-off block ```bash # Managed by docs/setup/scripts/20-zsh.sh — apf-portal zsh hand-off. # Hand off to zsh on interactive shells. The `case $-` guard avoids # breaking non-interactive bash (scp, rsync, cron, …), and the # ZSH_VERSION check prevents an infinite re-exec loop. case $- in *i*) if command -v zsh >/dev/null 2>&1 && [ -z "${ZSH_VERSION-}" ]; then exec zsh -l fi ;; esac ``` Two safety nets in the block: - **`case $- in *i*)`** — only runs the hand-off when the shell flag set contains `i` (interactive). `scp` / `rsync` / non-interactive ssh executions go through bash and are not hijacked. - **`[ -z "${ZSH_VERSION-}" ]`** — `ZSH_VERSION` is set by zsh itself; if it's already set we're already in zsh and a re-exec would loop. ## Test plan - [ ] On the dev VM, run `20-zsh.sh` on a fresh state: bash, no existing `~/.bashrc` zsh hand-off → script exits without `chsh` error, `~/.bashrc` gets the block appended, `exit` + reconnect lands in zsh. - [ ] Re-run `20-zsh.sh` → reports `↪ skip zsh hand-off already in ~/.bashrc` (idempotency). - [ ] `scp some-file vm-dev:/tmp/` from the workstation still works (non-interactive bash not hijacked). - [x] `pnpm exec prettier --check` clean on the touched markdown files. - [x] `bash -n docs/setup/scripts/20-zsh.sh` (syntax check) clean. ## Why not amend #220 #220 has already merged. Squash-merge collapsed it to `8a04540` on main; a force-push to amend would rewrite that commit and break anyone who's pulled it. The fix lands as a separate commit on the same setup-doc family. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #221
5.8 KiB
5.8 KiB
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 | 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 | 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 | Notes on the web-side tooling. |
| 04 | Angular + Nx monorepo | 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 |
Run every numbered script in order with a confirmation prompt at each step. |
lib.sh |
Common helpers — colour logging, idempotent apt_install / ensure_line. |
10-base-packages.sh |
apt + base packages every other script assumes (curl wget git build-essential …). |
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 |
bat eza fd-find ripgrep fzf zoxide ncdu keychain + dev extras (jq yq httpie make tree htop tmux direnv). |
40-node.sh |
nvm + Node from the repo's .nvmrc + corepack pinned to package.json#packageManager's pnpm version. |
50-docker.sh |
Docker CE + compose plugin from docker.com apt repo + user added to docker group + service enabled at boot. |
60-tuning.sh |
inotify watches → 524288, optional 4 GB swapfile, optional hostname rename (only prompts if generic). |
70-hardening.sh |
Best-effort UFW + unattended-upgrades + fail2ban + sshd hardening drop-in. Probes before applying — skips done items. |
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 |
Template unit auto-starting ./infra/local/dev.sh up at boot for a given user. |