cdsr: initial import of deployed stack (runtime 4.133.0, pinned extensions, SSOT vault)

q5vault/operations/install-upgrade.md

@@ -0,0 +1,59 @@
+---
+title: ⬆️ Install & Upgrade
+description: Install or upgrade the upstream code-server Debian package, service lifecycle commands, extension reinstall after Code version bumps, and fallback path.
+source: verified deployment on the loca operator host, 2026-08-19
+reviewed: 2026-08-19
+---
+
+# ⬆️ Install & Upgrade
+
+Runtime is the upstream Debian package `code-server_4.133.0_amd64.deb` from `coder/code-server` v4.133.0. Binary at `/usr/bin/code-server`, libs at `/usr/lib/code-server`. The exact version is pinned in `config/runtime-version.txt`.
+
+## First install (exact sequence as executed)
+
+```bash
+cd /home/loca/dev/code-server/tmp
+curl -fsSL -O https://github.com/coder/code-server/releases/download/v4.133.0/code-server_4.133.0_amd64.deb
+sudo -n dpkg -i code-server_4.133.0_amd64.deb
+sudo -n install -m 644 -o root -g root /home/loca/dev/code-server/deploy/cdsr.service /etc/systemd/system/cdsr.service
+sudo -n systemctl daemon-reload
+sudo -n systemctl enable --now cdsr
+```
+
+## Upgrade sequence
+
+```bash
+cd /home/loca/dev/code-server/tmp
+curl -fsSL -O https://github.com/coder/code-server/releases/download/v<NEW>/code-server_<NEW>_amd64.deb
+sudo -n dpkg -i code-server_<NEW>_amd64.deb
+echo "<NEW>" > /home/loca/dev/code-server/config/runtime-version.txt
+cd /home/loca/dev/code-server && ./scripts/install-extensions.sh
+cd /home/loca/dev/code-server && ./scripts/list-extension-versions.sh
+sudo -n systemctl restart cdsr
+```
+
+A Code version bump can invalidate extension host compatibility — always re-run the extension install and audit after upgrading the runtime.
+
+Order matters: extensions are installed and audited on disk before the service restart, so the restart is what loads the new extension versions into the extension host. Restarting first would leave any live browser session running the old extension host while the disk-based audit already reports green. If a session was open across the upgrade, reload the browser window (`Developer: Reload Window`) after the restart.
+
+`config/runtime-version.txt` is `loca:loca` 644, so the version pin is written with a plain shell redirect — no `sudo` and no `tee` needed.
+
+## Service lifecycle
+
+- status: `systemctl status cdsr --no-pager`
+- restart: `sudo -n systemctl restart cdsr`
+- logs: `journalctl -u cdsr -n 50 --no-pager`
+
+## Packaged unit stays disabled
+
+`code-server@loca` (the default user-scope unit installed by the Debian package) is deliberately left disabled — verified by `systemctl is-enabled code-server@loca` -> `disabled`. Reason: it does not pass `--config /home/loca/dev/code-server/config/config.yaml`, so the editor's own user-data and extensions would land in the default locations (`~/.config/code-server`, `~/.local/share/code-server`) instead of `data/user` and `data/extensions`. That is still the wrong choice even though it is not an all-or-nothing isolation claim: heartbeat, server logs and extension-owned config already live outside the project regardless of `user-data-dir` — see [[architecture/runtime-topology#state-outside-the-project]].
+
+## Fallback if the .deb ever fails
+
+If a packaging mismatch prevents the Debian package from installing on this host, fall back to the upstream standalone Linux amd64 tarball:
+
+1. Download and extract to `/home/loca/.local/lib/code-server-<version>`
+2. Change only `ExecStart` in `deploy/cdsr.service` to point to the extracted binary: `/home/loca/.local/lib/code-server-<version>/bin/code-server`
+3. Keep everything else identical: config, nginx, Authelia, wiki layout, service user, working directory, environment
+
+This fallback preserves the same operational surface while bypassing the Debian package manager.