cdsr: initial import of deployed stack (runtime 4.133.0, pinned extensions, SSOT vault)
This commit is contained in:
Antigravity
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
|
||||
Reference in New Issue
Block a user