jamminrebel/cdsr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Antigravity
2026-08-20 10:49:50 +02:00
commit c2d92d7b74
20 changed files with 1440 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
q5vault/operations/auth-tls.md Normal file
View File

@@ -0,0 +1,99 @@
---
title: 🔐 Auth & TLS
description: Authelia access rule, nginx four-block topology, shared certificate lineage, proof commands, and rollback/debug order for the code-server SSO-gated stack.
source: verified deployment on the loca operator host, 2026-08-19
reviewed: 2026-08-19
---
# 🔐 Auth & TLS
## Authelia access rule
File: `/home/loca/dev/services/authelia/config/configuration.yml` (root:root 644)
Edit procedure — stage in `/tmp` then install atomically:
```bash
sudo -n install -m 644 -o root -g root /tmp/configuration.yml /home/loca/dev/services/authelia/config/configuration.yml
```
YAML added inside `access_control.rules`:
```yaml
- domain: "cdsr.loca.zone"
policy: one_factor
```
The rule sits alongside existing rules for `auth.loca.zone`, `admin.loca.zone`, `omp.loca.zone`, `pwiz.loca.zone`, `trlm.loca.zone`.
## Why the wiki has no rule
Authelia runs with `default_policy: bypass`. An explicit rule for `wiki.cdsr.loca.zone` is intentionally omitted — the wiki remains public by omission while the app host becomes protected by explicit allowlisting.
## Apply procedure
```bash
cd /home/loca/dev/services/authelia
sudo -n docker compose config
sudo -n docker compose restart
sudo -n docker compose ps
```
Authelia v4.39.20 restarts clean on loopback `127.0.0.1:51091`. Session cookie domain `loca.zone`, `authelia_url https://auth.loca.zone`, expiration 1h, inactivity 5m.
## Nginx topology
File: `/etc/nginx/sites-available/cdsr.loca.zone` (symlinked into `sites-enabled`), installed from `deploy/cdsr.nginx.conf`.
Four server blocks after Certbot:
- `cdsr.loca.zone:443` — reverse proxy to `http://127.0.0.1:52224`
- includes `snippets/security-headers-app.conf`
- includes `snippets/authelia-location.conf`
- `location /` protected by `snippets/authelia-authrequest.conf`
- `proxy_http_version 1.1`, websocket headers (`Upgrade`, `Connection`), `proxy_read_timeout 86400`
- `wiki.cdsr.loca.zone:443` — static root `/home/loca/dev/wikis/cdsr/current`
- includes `snippets/security-headers.conf`
- 1y immutable cache for `css|js|png|webp|ico|json|woff2?|svg|map`
- `try_files $uri $uri.html $uri/ =404`
- `cdsr.loca.zone:80` — ACME challenge from `/var/www/html` + 301 to HTTPS
- `wiki.cdsr.loca.zone:80` — ACME challenge from `/var/www/html` + 301 to HTTPS
## TLS certificate
Single lineage `cdsr.loca.zone` covering both hosts:
```bash
sudo -n certbot certonly --webroot -w /var/www/html --non-interactive --agree-tos -m admin@loca.zone --cert-name cdsr.loca.zone -d cdsr.loca.zone -d wiki.cdsr.loca.zone
```
Expiry: 2026-11-17, auto-renew scheduled. Certs at `/etc/letsencrypt/live/cdsr.loca.zone/{fullchain,privkey}.pem`.
If a partial lineage already exists, rerun with the same `--cert-name` and `--expand` instead of minting a second lineage.
`sudo -n nginx -t` emits a harmless pre-existing `ssl_stapling` warning about `flxr.loca.zone` — expected and safe to ignore.
## Proof commands
```bash
# app host — unauthenticated redirect into Authelia
curl -sSI https://cdsr.loca.zone/
# -> HTTP/1.1 302
# -> Location: https://auth.loca.zone/?rd=https%3A%2F%2Fcdsr.loca.zone%2F&rm=HEAD
# wiki host — public, no auth redirect
curl -sSI https://wiki.cdsr.loca.zone/
# -> HTTP/1.1 200
# -> serves static content directly
```
## Rollback / debug order if auth breaks
1. `sudo -n nginx -t` — config clean (ignore the pre-existing flxr ssl_stapling warning)
2. Confirm app 443 block includes both snippets:
- `include snippets/authelia-location.conf`
- `location / { include snippets/authelia-authrequest.conf; ... }`
3. Confirm Authelia rule present:
- `grep -A2 'domain: "cdsr.loca.zone"' /home/loca/dev/services/authelia/config/configuration.yml`
4. Check Authelia container:
- `cd /home/loca/dev/services/authelia && sudo -n docker compose ps`
- `cd /home/loca/dev/services/authelia && sudo -n docker compose logs --tail=50 authelia`
5. Prove code-server itself is healthy (bypasses all auth/TLS):
- `curl -sf http://127.0.0.1:52224/healthz`
- should return `{"status":"alive",...}` when an editor session is active

125
q5vault/operations/extensions.md Normal file
View File

@@ -0,0 +1,125 @@
---
title: 🧩 Extensions
description: Pinned Open VSX extension baseline, lock file semantics, install/audit commands, optional/excluded entries, and the LiteLLM AI provider wiring.
source: verified deployment on the loca operator host, 2026-08-19; AI wiring verified in the running IDE 2026-08-20
reviewed: 2026-08-20
---
# 🧩 Extension baseline
## Pinned baseline (six entries)
| id | version | platform | reason |
|---|---|---|---|
| `Continue.continue` | 2.1.0 | linux-x64 | Primary open-source AI agent/chat/edit/autocomplete extension. |
| `Anthropic.claude-code` | 2.1.235 | linux-x64 | First-party Claude Code IDE integration. |
| `ms-python.python` | 2026.4.0 | universal | Python language support expected in this environment. |
| `ms-python.debugpy` | 2026.6.0 | linux-x64 | Explicit debugger dependency instead of relying on later bootstrap by the Python extension. |
| `ms-toolsai.jupyter` | 2025.9.1 | universal | Notebook workflow support in the browser IDE. |
| `ms-azuretools.vscode-containers` | 2.4.5 | universal | Current Container Tools extension; its README states it replaces the older Docker extension functionality. |
All six come from `config/extensions.lock.json` (registry: `https://open-vsx.org`).
## Lock file mechanics
`config/extensions.lock.json` is the single source of truth. Each entry contains `id`, `version`, `platform`, `vsix_url`, `sha256_url`, `reason`, and `mode` (`baseline` or `optional`).
VSIX cache lives in `tmp/extensions/` with filenames `<id>-<version>@<platform>.vsix`.
Install script (`scripts/install-extensions.sh`):
- requires `python3` (no `jq` on this host)
- downloads VSIX + `.sha256` into cache if not present
- verifies sha256 before install
- installs with `code-server --config config/config.yaml --install-extension <abs .vsix> --force`
Audit script (`scripts/list-extension-versions.sh`):
- runs `code-server --list-extensions --show-versions`
- compares against lock file
- exits non-zero on `MISSING` or `MISMATCH`
- `--include-optional` extends the check to `mode: optional` entries
## Commands
```bash
# install baseline only
cd /home/loca/dev/code-server && ./scripts/install-extensions.sh
# install baseline + optional
./scripts/install-extensions.sh --include-optional
# audit baseline
./scripts/list-extension-versions.sh
# audit baseline + optional
./scripts/list-extension-versions.sh --include-optional
```
## Transitively installed (expected, unpinned)
| id | version | note |
|---|---|---|
| `ms-python.vscode-python-envs` | 1.36.0 | Python extension dependency |
| `ms-toolsai.jupyter-keymap` | 1.1.2 | Jupyter dependency |
| `ms-toolsai.jupyter-renderers` | 1.3.0 | Jupyter dependency |
| `ms-toolsai.vscode-jupyter-cell-tags` | 0.1.9 | Jupyter dependency |
| `ms-toolsai.vscode-jupyter-slideshow` | 0.1.6 | Jupyter dependency |
These are not in the lock file and will vary; they are expected by-products of the baseline install.
## Optional: Cody (enterprise only)
| id | version | platform | reason |
|---|---|---|---|
| `sourcegraph.cody-ai` | 1.155.0 | universal | Useful only with a Cody Enterprise account; the Open VSX README states it is no longer available for non-enterprise users. |
Opt-in:
```bash
./scripts/install-extensions.sh --include-optional
```
## Exclusions (recorded in lock file)
| id | reason |
|---|---|
| `TabNine.tabnine-vscode` | Open VSX listing marks it legacy and states it does not onboard new users. |
| `GitHub.copilot` | Microsoft-marketplace-only AI tooling; code-server cannot rely on Microsoft marketplace terms or access. |
Any Microsoft-marketplace-only AI extensions fall under the same exclusion.
## Where extension configuration actually lives
Extension config is not under `data/user/`. The unit sets `HOME=/home/loca`, so extensions that resolve their own paths from `$HOME` write outside the project — see [[architecture/runtime-topology#state-outside-the-project]].
- Continue writes `/home/loca/.continue/` — its real configuration and history, not `data/user/`
- `config.yaml` — mode 600, holds provider settings; never commit it, never paste its contents into the wiki or project files
- also `config.ts`, `.continuerc.json`, `index/`, `sessions/`, `dev_data/`, `.utils/`
- version nuance for the pinned 2.1.0 build
- it still contributes `continue.remoteConfigServerUrl`, `continue.userToken` and `continue.remoteConfigSyncPeriod` for shared/team config sync, sync period defaulting to 60 minutes
- none of those three carries a deprecation message; the only deprecated setting is `continue.telemetryEnabled`, whose deprecation message points at Telemetry > Allow Anonymous Telemetry on the extension's User Settings page
- so Continue configuration is not local-only in this build; this deployment simply leaves remote sync unconfigured
- Claude Code reuses the operator's pre-existing `/home/loca/.claude/` and `/home/loca/.claude.json`, shared with the host Claude Code CLI — it is not deployment-owned state and is not created by the extension install
- backup targets: `/home/loca/dev/code-server/` plus `/home/loca/.continue/`; the project directory alone misses Continue's config and chat sessions
## AI provider wiring (LiteLLM gateway)
Continue is wired to the host LiteLLM gateway (`lllm`, loopback `127.0.0.1:52001`) — no cloud provider sign-in is used. The gateway is reachable from the IDE because code-server and LiteLLM run on the same host.
- credential: a dedicated LiteLLM virtual key with alias `cdsr-ide`, scoped to the three model groups below. The master key is never placed in a client config.
- key file: `/home/loca/dev/code-server/.ai-credentials` (mode 600, gitignored, single line `litellm_ide_key=`). The value is also present in `/home/loca/.continue/config.yaml` (mode 600). Neither value belongs in this wiki, the repo, or a systemd unit.
- client config: `/home/loca/.continue/config.yaml`, three models, all `provider: openai` against `apiBase: http://127.0.0.1:52001/v1`. Shape validated against the extension's own `config-yaml-schema.json` (`name`, `model`, `provider` required; `roles` enum accepts `chat`, `edit`, `apply`, `autocomplete`).
| model | upstream | roles | live state |
|---|---|---|---|
| `free` | OpenRouter `nvidia/nemotron-3.5-lightning:free` | chat, edit, apply, autocomplete | working — verified chat round-trip in the Continue panel |
| `oss-120b` | Groq `openai/gpt-oss-120b` | chat, edit, apply | reachable, but Groq free-tier caps 8000 tokens/minute and Continue's agent prompt is ~8.6k, so chat returns `RateLimitError` |
| `fast` | Groq `llama-3.1-8b-instant` | chat, edit, apply | broken upstream — Groq decommissioned the model, every call returns `404 model_not_found`. Defect belongs to the `lllm` stack config, not this one |
Practical consequence: select `free` in the model picker. Repairing `oss-120b`/`fast` means editing `dev/lllm/config/config.yaml` (a different stack) — not a cdsr change.
Workspace Trust gate: a fresh browser profile opens `/home/loca` in Restricted Mode, which silently disables every third-party extension — no Continue or Claude Code icon in the activity bar and no `Continue:` commands in the palette. Fix: Command Palette → `Workspaces: Manage Workspace Trust` → Trust. Symptom is indistinguishable from a failed install, so check trust before re-installing anything.
Claude Code is deliberately NOT wired to LiteLLM. The gateway does expose an Anthropic-compatible `/v1/messages` passthrough, but the reference probe model (`fast`) fails for the upstream reason above, so the extension stays on its interactive `/login` (browser OAuth) against an Anthropic account. Session state lives in the operator-wide `/home/loca/.claude/` and `/home/loca/.claude.json`, not in `data/user/`.
Cody (optional, only if enabled): sign in via the Cody panel; requires an Enterprise subscription.
`"extensions.autoUpdate": "off"` and `"update.mode": "manual"` are the deployed values in `data/user/User/settings.json` — code-server normalized the seeded `false` to the string `"off"` at first run, and `"off"` and `false` mean the same thing (auto-update disabled). Version drift only happens by updating `config/extensions.lock.json` and re-running the install script.

27
q5vault/operations/index.md Normal file
View File

@@ -0,0 +1,27 @@
---
title: 🛠️ Operations
description: Operations index for the code-server SSO-gated IDE stack — install/upgrade, auth/TLS, extensions, and verification procedures.
source: verified deployment on the loca operator host, 2026-08-19
reviewed: 2026-08-19
---
# 🛠️ Operations
Operations reference for the single-user code-server deployment at `cdsr.loca.zone`.
## Pages
- [[operations/install-upgrade]] — install or upgrade the upstream Debian package, service lifecycle, extension reinstall after Code version bumps, fallback path
- [[operations/auth-tls]] — Authelia access rule, nginx four-block topology, shared cert lineage, proof commands, rollback/debug order
- [[operations/extensions]] — pinned baseline table, optional Cody, explicit exclusions, first-run sign-in notes, install/audit scripts
- [[operations/verification]] — every smoke check with expected outputs: systemctl, loopback healthz, auth redirect, wiki public, Authelia compose, extension audit, browser flows, dev proxy, wiki build
## 🚨 Triage order when something is broken
1. `systemctl status cdsr --no-pager` — service active and running?
2. `curl -sf http://127.0.0.1:52224/healthz` — always HTTP 200 while the server is up. Body `{"status":"expired","lastHeartbeat":0}` is healthy-idle (no editor session connected); `{"status":"alive",...}` appears only while a browser session is connected. Only a non-200 or no response at all indicates failure
3. `sudo -n nginx -t` — nginx config clean (harmless flxr ssl_stapling warning is expected)?
4. Authelia rule present + container healthy:
- `grep -A2 'domain: "cdsr.loca.zone"' /home/loca/dev/services/authelia/config/configuration.yml`
- `cd /home/loca/dev/services/authelia && sudo -n docker compose ps`
- `cd /home/loca/dev/services/authelia && sudo -n docker compose logs --tail=50 authelia`

59
q5vault/operations/install-upgrade.md Normal file
View File

@@ -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.

127
q5vault/operations/verification.md Normal file
View File

@@ -0,0 +1,127 @@
---
title: ✅ Verification
description: "Numbered proof checklist for the deployed cdsr stack: service health, auth gate, wiki public, extensions audit, browser smoke, dev proxy, and wiki build."
source: verified deployment on the loca operator host, 2026-08-19
reviewed: 2026-08-19
---
# ✅ Verification checklist
Run in order. Each step must produce the expected output before proceeding.
## 1. systemd service
```bash
systemctl status cdsr --no-pager
```
Expected: `Active: active (running)` with `Main PID` present.
## 2. code-server loopback health
```bash
curl -sf http://127.0.0.1:52224/healthz
```
Expected (no editor session): JSON `{"status":"expired","lastHeartbeat":0}`
Expected (with browser session connected): JSON `{"status":"alive",...}`
```bash
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:52224/
```
Expected: `200`
## 3. app host requires Authelia
```bash
curl -sSI https://cdsr.loca.zone/
```
Expected: `HTTP/1.1 302` with `Location: https://auth.loca.zone/?rd=https%3A%2F%2Fcdsr.loca.zone%2F&rm=HEAD` (or equivalent redirect into Authelia).
## 4. wiki host is public
```bash
curl -sSI https://wiki.cdsr.loca.zone/
```
Expected: `HTTP/1.1 200` with `Content-Type: text/html` and no `Location` header pointing to `auth.loca.zone`.
## 5. Authelia config valid and container up
```bash
cd /home/loca/dev/services/authelia && sudo -n docker compose config
```
Expected: clean YAML output, no errors.
```bash
cd /home/loca/dev/services/authelia && sudo -n docker compose ps
```
Expected: `authelia` container `Up` (healthy).
## 6. extension baseline audit
```bash
cd /home/loca/dev/code-server && ./scripts/list-extension-versions.sh
```
Expected:
```
ok Continue.continue@2.1.0
ok Anthropic.claude-code@2.1.235
ok ms-python.python@2026.4.0
ok ms-python.debugpy@2026.6.0
ok ms-toolsai.jupyter@2025.9.1
ok ms-azuretools.vscode-containers@2.4.5
```
Exit code: `0`
## 7. browser smoke (manual)
1. Open `https://cdsr.loca.zone` in a browser.
2. Complete Authelia one-factor login at `auth.loca.zone`.
3. Confirm code-server editor shell loads (activity bar, file explorer, terminals).
4. Open Extensions view (Ctrl+Shift+X): verify `Continue` and `Claude Code` are installed and enabled.
5. Open integrated terminal (Ctrl+`): run `whoami` -> output `loca`.
## 8. dev-routing smoke (manual)
1. In the integrated terminal from step 7, run:
```bash
python3 -m http.server 52325 --bind 127.0.0.1
```
2. In the browser, open `https://cdsr.loca.zone/proxy/52325/`
3. Expected: directory listing or test page renders through code-server's built-in proxy.
## 9. wiki build smoke
```bash
cd /home/loca/dev/wikis && ./build.sh cdsr
```
Expected: build completes, emits `current -> dist-<timestamp>` symlink. A `git` warning about the vault not being a git repository is normal and expected.
Then open `https://wiki.cdsr.loca.zone/`:
- quick-start page renders
- internal wikilinks resolve (e.g. `[[operations/extensions]]`, `[[architecture/runtime-topology]]`)
- footer links point to `https://cdsr.loca.zone` and `https://loca.zone`
## Pre-publish wiki lint gate
Run before every `build.sh` invocation, so ahead of step 9 above. This is a gate, not a smoke test: a non-zero exit means nothing gets published.
```bash
python3 /home/loca/dev/wikis/lint-vault.py /home/loca/dev/code-server/q5vault
```
Expected: `11 pages, 0 findings, all 5 checks clean` and exit code `0`.
- `--quiet` suppresses the clean summary so only failures print, which is the form to use in a wrapper
- the vault may be named instead of pathed: `python3 /home/loca/dev/wikis/lint-vault.py cdsr` resolves `/home/loca/dev/wikis/cdsr/content`, the symlink into this vault
- why it exists: a frontmatter `description:` whose value held an unquoted colon-space made the Quartz note-properties transformer fail its YAML parse, and esbuild then died with a Go `all goroutines are asleep - deadlock!` panic instead of a readable error. One unquoted colon cost a whole build with no usable diagnostic
- it complements `scripts/validate-ssot.py`, which `build.sh` runs itself: that validator only gates wikis shipping a `wiki-ia.json` manifest, and this wiki ships none, so its `SSOT Validation passed` line is a vacuous pass here and this linter is the only real pre-publish gate on the vault
- check 1, frontmatter scalars: unquoted values containing a colon-space, starting with `#`, `@`, `*`, `&`, `!`, `%` or a backtick, ending in a colon, carrying an inline ` #` comment that would silently truncate the value, or holding an unterminated quote. Reported as `file:line` plus the offending key
- check 2, wikilinks in tables: an unescaped `|` inside `[[...]]` on a table row splits the cell, and an alias containing `/` is truncated at the slash when rendered
- check 3, dead wikilinks: every target must resolve to a real `.md` in the vault, tried vault-root-relative first and then relative to the linking page, tolerating a leading `./` and an optional `#anchor`
- check 4, house style: no markdown bold anywhere
- check 5, page shape: no second H1 in one file, and no page without a frontmatter block
- checks 2 to 5 ignore fenced blocks and inline code spans, because nothing in those regions renders as markdown, so the example wikilinks in step 9 above are not treated as links
- standard library only, so it runs on any host with `python3` and needs no pyyaml
---
Note: the git-repository warning from `build.sh` is normal -- the vault is a plain directory, not a git repo.