jamminrebel/cdsr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c2d92d7b745721db7f3eb8543072b5f2a53e303d
cdsr/q5vault/reference/dev-routing.md

4.9 KiB
Raw Blame History

title, description, source, reviewed
title description source reviewed
🔀 Dev Server Routing code-server built-in proxy routes, framework caveats, and why pretty per-port subdomains are not configured here verified deployment on the loca operator host, 2026-08-19 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 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:

# 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

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

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:

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)