Code Server SSOT

3 min read

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

RoutePath 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

FrameworkRouteRequired 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)