cdsr: initial import of deployed stack (runtime 4.133.0, pinned extensions, SSOT vault)
This commit is contained in:
Antigravity
69
q5vault/reference/config-paths.md
Normal file
69
q5vault/reference/config-paths.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: 📂 Config & Paths Reference
|
||||
description: Exhaustive table of every config file, state directory, system path, and port used by the code-server deployment, with purpose and owner
|
||||
source: verified deployment on the loca operator host, 2026-08-19
|
||||
reviewed: 2026-08-19
|
||||
---
|
||||
|
||||
# 📂 Config & Paths Reference
|
||||
|
||||
## Path & Port Table
|
||||
|
||||
| Path / Port | Purpose | Owner / Permissions | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `config/config.yaml` | code-server runtime config | `loca:loca` 644 | Effective config shown below |
|
||||
| `config/extensions.lock.json` | pinned extension versions + VSIX metadata | `loca:loca` 644 | Baseline + optional entries |
|
||||
| `config/runtime-version.txt` | upstream code-server version pin | `loca:loca` 644 | Content: `4.133.0` |
|
||||
| `scripts/install-extensions.sh` | installs baseline from lock file | `loca:loca` 755 | Reads `config/extensions.lock.json`, verifies sha256, `--include-optional` for optional entries |
|
||||
| `scripts/list-extension-versions.sh` | audits installed vs lock file | `loca:loca` 755 | Exits non-zero on MISSING/MISMATCH |
|
||||
| `deploy/cdsr.service` | systemd unit source | `loca:loca` 644 | Installed to `/etc/systemd/system/cdsr.service` |
|
||||
| `deploy/cdsr.nginx.conf` | nginx site config source | `loca:loca` 644 | Installed to `/etc/nginx/sites-available/cdsr.loca.zone` |
|
||||
| `data/user/` | code-server user data dir | `loca:loca` 755 | Set via `user-data-dir` |
|
||||
| `data/user/User/settings.json` | VS Code settings (telemetry off, auto-update off) | `loca:loca` 644 | Seeded at deploy |
|
||||
| `data/extensions/` | installed extensions dir | `loca:loca` 755 | Set via `extensions-dir` |
|
||||
| `tmp/extensions/` | VSIX download cache | `loca:loca` 755 | Filenames `<id>-<version>@<platform>.vsix` |
|
||||
| `q5vault/` | Quartz wiki vault (real content) | `loca:loca` 755 | Symlinked as `/home/loca/dev/wikis/cdsr/content` |
|
||||
| `quartz.config.cdsr.yaml` | Quartz config for this wiki | `loca:loca` 644 | Symlinked as `/home/loca/dev/wikis/cdsr/quartz.config.yaml` |
|
||||
| `/etc/systemd/system/cdsr.service` | installed systemd unit | `root:root` 644 | Requires `sudo -n install` for edits; enable/start via `systemctl` |
|
||||
| `/etc/nginx/sites-available/cdsr.loca.zone` | installed nginx site | `root:root` 644 | Requires `sudo -n install` for edits; symlinked into `sites-enabled` |
|
||||
| `/etc/nginx/sites-enabled/cdsr.loca.zone` | symlink to sites-available | `root:root` 755 | Created by `ln -sf` |
|
||||
| `/etc/nginx/snippets/security-headers-app.conf` | security headers for app host | `root:root` 644 | Included in app 443 block |
|
||||
| `/etc/nginx/snippets/security-headers.conf` | security headers for wiki host | `root:root` 644 | Included in wiki 443 block |
|
||||
| `/etc/nginx/snippets/authelia-location.conf` | Authelia location config | `root:root` 644 | Included in app 443 block |
|
||||
| `/etc/nginx/snippets/authelia-authrequest.conf` | auth_request to Authelia | `root:root` 644 | Protects app `location /` |
|
||||
| `/etc/letsencrypt/live/cdsr.loca.zone/` | TLS cert lineage | `root:root` 700 dir, 600 files | `fullchain.pem`, `privkey.pem`; expires 2026-11-17 |
|
||||
| `/home/loca/dev/services/authelia/config/configuration.yml` | Authelia config | `root:root` 644 | Requires `sudo -n install` after staging in `/tmp`; rule `cdsr.loca.zone` = `one_factor` |
|
||||
| `/home/loca/dev/wikis/cdsr/content` | symlink → `q5vault/` | `loca:loca` symlink | Wiki build source |
|
||||
| `/home/loca/dev/wikis/cdsr/quartz.config.yaml` | symlink → `quartz.config.cdsr.yaml` | `loca:loca` symlink | Wiki build config |
|
||||
| `/home/loca/dev/wikis/cdsr/current` | symlink → latest `dist-*` build | `loca:loca` symlink | Nginx `root` points here |
|
||||
| `/usr/bin/code-server` | upstream binary (Debian package) | `root:root` 755 | Installed via `dpkg -i` from GitHub release v4.133.0 |
|
||||
| `/usr/lib/code-server` | upstream libs (Node, extensions host) | `root:root` 755 | Package-managed, do not modify |
|
||||
|
||||
## Loopback Port & Range
|
||||
|
||||
- `127.0.0.1:52224` — code-server bind address (chosen inside mandatory 51000-53000 loopback range for loca.zone app backends)
|
||||
- Health endpoint: `http://127.0.0.1:52224/healthz` — always HTTP 200 while the server is up; body is `{"status":"expired","lastHeartbeat":0}` when no editor session is connected (healthy-idle) and `{"status":"alive",...}` while a browser session is connected. Only a non-200 or no response indicates failure; HTTP 200 from `/` also proves liveness
|
||||
|
||||
## Effective `config/config.yaml`
|
||||
|
||||
```yaml
|
||||
bind-addr: 127.0.0.1:52224
|
||||
auth: none
|
||||
cert: false
|
||||
app-name: Code Server · loca.zone
|
||||
user-data-dir: /home/loca/dev/code-server/data/user
|
||||
extensions-dir: /home/loca/dev/code-server/data/extensions
|
||||
disable-telemetry: true
|
||||
```
|
||||
|
||||
## Root-Owned Files Requiring `sudo -n install`
|
||||
|
||||
- `/etc/systemd/system/cdsr.service`
|
||||
- `/etc/nginx/sites-available/cdsr.loca.zone`
|
||||
- `/etc/nginx/snippets/security-headers-app.conf`
|
||||
- `/etc/nginx/snippets/security-headers.conf`
|
||||
- `/etc/nginx/snippets/authelia-location.conf`
|
||||
- `/etc/nginx/snippets/authelia-authrequest.conf`
|
||||
- `/home/loca/dev/services/authelia/config/configuration.yml`
|
||||
|
||||
Edit workflow: stage in `/tmp`, then `sudo -n install -m 644 -o root -g root /tmp/<file> /target/path`.
|
||||
93
q5vault/reference/dev-routing.md
Normal file
93
q5vault/reference/dev-routing.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: 🔀 Dev Server Routing
|
||||
description: code-server built-in proxy routes, framework caveats, and why pretty per-port subdomains are not configured here
|
||||
source: verified deployment on the loca operator host, 2026-08-19
|
||||
reviewed: 2026-08-19
|
||||
---
|
||||
|
||||
# 🔀 Dev Server Routing
|
||||
|
||||
## Why No Pretty Subdomains
|
||||
|
||||
Pretty per-port subdomain proxying (`proxy-domain`) is intentionally not configured because:
|
||||
|
||||
- DNS is not the blocker — multi-label wildcards do resolve on this host; `3000.cdsr.loca.zone` and deeper names all answer with the host address
|
||||
- TLS certificate issuance is the blocker — the `cdsr.loca.zone` lineage covers exactly two SANs: `cdsr.loca.zone` and `wiki.cdsr.loca.zone`
|
||||
- A `*.cdsr.loca.zone` certificate would require DNS-01 validation with DNS-provider API credentials, which are not configured on this host
|
||||
- HTTP-01 via webroot (the method used for every lineage here) cannot issue wildcard certificates at all
|
||||
- Therefore per-port hostnames would serve a name mismatch to the browser; code-server's built-in `/proxy/<port>/` and `/absproxy/<port>/` routes remain the supported routes and need no new certificate
|
||||
|
||||
See upstream: [Accessing web services — Using a subdomain](https://coder.com/docs/code-server/guide#using-a-subdomain) about requiring a DNS entry per port and wildcard TLS support.
|
||||
|
||||
## Default Route: `/proxy/<port>/`
|
||||
|
||||
The default subpath proxy strips the `/proxy/<port>` prefix before forwarding to the dev server.
|
||||
|
||||
Worked example:
|
||||
|
||||
```bash
|
||||
# In code-server integrated terminal (binds 127.0.0.1 only)
|
||||
python3 -m http.server 52325 --bind 127.0.0.1
|
||||
```
|
||||
|
||||
Then open:
|
||||
|
||||
```
|
||||
https://cdsr.loca.zone/proxy/52325/
|
||||
```
|
||||
|
||||
- Trailing slash matters, always use it
|
||||
- Dev server must bind `127.0.0.1`, not `0.0.0.0`
|
||||
- Port must not collide with code-server loopback port `52224`
|
||||
- Ad-hoc dev-server ports must avoid every port in the AGENTS.md `port_convention` registry (52222 pwiz, 52223 reserved for pwiz, 52224 cdsr, 52226 code) and must be checked with `ss -ltn` before binding — an ad-hoc listener inside 51000-53000 can shadow a registered backend and block that service's restart
|
||||
|
||||
Upstream: [Using a subpath](https://coder.com/docs/code-server/guide#using-a-subpath)
|
||||
|
||||
## Path-Preserving Route: `/absproxy/<port>/`
|
||||
|
||||
Use `/absproxy/<port>/` when the framework needs the request path preserved and not stripped.
|
||||
|
||||
| Route | Path sent to dev server |
|
||||
| --- | --- |
|
||||
| `/proxy/3000/app/path` | `/app/path` |
|
||||
| `/absproxy/3000/app/path` | `/absproxy/3000/app/path` |
|
||||
|
||||
Upstream: [Stripping `/proxy/<port>` from the request path](https://coder.com/docs/code-server/guide#stripping-proxyport-from-the-request-path)
|
||||
|
||||
## Framework Caveat Table
|
||||
|
||||
| Framework | Route | Required config |
|
||||
| --- | --- | --- |
|
||||
| React / create-react-app | `/absproxy/<port>/` | `PUBLIC_URL=/absproxy/<port>` and `WDS_SOCKET_PATH=$PUBLIC_URL/sockjs-node` |
|
||||
| Vue (Vue CLI) | `/absproxy/<port>/` | `publicPath: "/absproxy/<port>"` and `devServer.sockPath: "sockjs-node"` |
|
||||
| Angular | `/absproxy/<port>/` | `<base href="./">` in `src/index.html` and `--serve-path /absproxy/<port>` in `ng serve` |
|
||||
| Svelte (SvelteKit) | `/absproxy/<port>/` | `kit.paths.base: "/absproxy/<port>"` in `svelte.config.js` |
|
||||
|
||||
Notes:
|
||||
|
||||
- React requirement source: [Proxying to create a React app](https://coder.com/docs/code-server/guide#proxying-to-create-a-react-app)
|
||||
- Vue requirement source: [Proxying to a Vue app](https://coder.com/docs/code-server/guide#proxying-to-a-vue-app)
|
||||
- Angular requirement source: [Proxying to an Angular app](https://coder.com/docs/code-server/guide#proxying-to-an-angular-app)
|
||||
- Svelte requirement source: [Proxying to a Svelte app](https://coder.com/docs/code-server/guide#proxying-to-a-svelte-app)
|
||||
- HMR note: websocket-driven HMR needs Nginx headers already configured in the app block (`proxy_read_timeout 86400`, `Upgrade $http_upgrade`, `Connection $connection_upgrade`)
|
||||
|
||||
## Troubleshooting Checklist
|
||||
|
||||
- Dev server binds to `0.0.0.0` only; set `--bind 127.0.0.1` or `--host 127.0.0.1`
|
||||
- Missing trailing slash (`/proxy/52325` versus `/proxy/52325/`)
|
||||
- Proxy port equals `52224`
|
||||
- Assets load from `/` and not the proxied prefix, indicating a base path mismatch
|
||||
- HMR fails to connect, confirm websocket forwarding and timeout headers in Nginx
|
||||
- CORS/preflight issues on custom auth chains, see `--skip-auth-preflight` if auth is enabled
|
||||
|
||||
## Source URLs (read during this task)
|
||||
|
||||
- https://coder.com/docs/code-server/guide
|
||||
- https://coder.com/docs/code-server/guide#using-a-subdomain
|
||||
- https://coder.com/docs/code-server/guide#using-a-subpath
|
||||
- https://coder.com/docs/code-server/guide#stripping-proxyport-from-the-request-path
|
||||
- https://coder.com/docs/code-server/guide#proxying-to-create-a-react-app
|
||||
- https://coder.com/docs/code-server/guide#proxying-to-a-vue-app
|
||||
- https://coder.com/docs/code-server/guide#proxying-to-an-angular-app
|
||||
- https://coder.com/docs/code-server/guide#proxying-to-a-svelte-app
|
||||
- https://coder.com/docs/code-server/guide#preflight-requests
|
||||
18
q5vault/reference/index.md
Normal file
18
q5vault/reference/index.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: 📚 Reference Index
|
||||
description: Landing page for reference documentation linking to config paths and dev routing pages
|
||||
source: verified deployment on the loca operator host, 2026-08-19
|
||||
reviewed: 2026-08-19
|
||||
---
|
||||
|
||||
# 📚 Reference Index
|
||||
|
||||
Quick links to reference pages:
|
||||
|
||||
- [[reference/config-paths]] — exhaustive table of every config file, state directory, system path, and port used by this deployment, with owner and purpose
|
||||
- [[reference/dev-routing]] — code-server built-in proxy routes (`/proxy/<port>/` and `/absproxy/<port>/`), framework caveats, and why pretty subdomains are not used here
|
||||
|
||||
Back links:
|
||||
|
||||
- [[index]] — quick-start cheat sheet
|
||||
- [[operations/index]] — operations landing page
|
||||
Reference in New Issue
Block a user