cdsr/q5vault/architecture/runtime-topology.md

title, description, source, reviewed

title	description	source	reviewed
🧭 Runtime Topology	Request flow, local directory map, auth/cert rationale, process state, and websocket requirements for the cdsr.loca.zone code-server deployment.	verified deployment on the loca operator host, 2026-08-19	2026-08-19

🧭 Runtime Topology

Request path

flowchart LR
    Browser[Browser] --> Nginx443[Nginx 443\nTLS + security headers]
    Nginx443 --> Authelia[Authelia auth_request\nauth.loca.zone one_factor]
    Authelia --> CodeServer[code-server on 127.0.0.1:52224]

• Browser → Nginx cdsr.loca.zone:443
  • TLS terminates at Nginx
  • security headers included for app traffic
  • forwards requests to code-server only after auth_request
• Nginx → Authelia
  • authelia_location and authelia_authrequest snippets included
  • auth_request policy for cdsr.loca.zone is one_factor
  • request allowed only after successful Authelia authentication
• Authelia → code-server
  • reverse proxy to 127.0.0.1:52224
  • loopback target: bind-addr is not public
  • headers forwarded: Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto
  • websocket headers: proxy_http_version 1.1, Upgrade $http_upgrade, Connection $connection_upgrade
  • proxy_read_timeout 86400

Local directory map

• /home/loca/dev/code-server
  • config/
  • scripts/
  • deploy/
  • data/user/
  • data/extensions/
  • tmp/extensions/
  • q5vault/
• /etc/systemd/system/cdsr.service
• /etc/nginx/sites-available/cdsr.loca.zone
• /etc/letsencrypt/live/cdsr.loca.zone/
• /home/loca/dev/wikis/cdsr/{content,quartz.config.yaml,current}

Why auth: none and cert: false

• bind-addr is 127.0.0.1:52224, so code-server never binds a public interface
• auth: none is correct because Authelia performs edge auth; enabling code-server auth would add a second credential store, break websocket UX, and duplicate login logic
• cert: false is correct because TLS is terminated at Nginx with a Let's Encrypt lineage certificate
• certs are in /etc/letsencrypt/live/cdsr.loca.zone/ for Nginx TLS termination
• Authelia handles identity at the edge with auth_request before requests enter code-server
• this is only safe because code-server is loopback-only

Process / state facts

• system scope unit: cdsr.service
  • User=loca
  • Group=loca
  • Restart=always
  • WorkingDirectory=/home/loca/dev/code-server
• editor state is project-isolated by explicit config, not by default: config/config.yaml sets user-data-dir: /home/loca/dev/code-server/data/user and extensions-dir: /home/loca/dev/code-server/data/extensions, and the unit passes --config /home/loca/dev/code-server/config/config.yaml
  • data/user and data/extensions are therefore inside the project
  • user-data-dir does not capture everything — see the next section for what lands outside it anyway
• packaged unit code-server@loca is deliberately disabled

State outside the project

The unit sets Environment=HOME=/home/loca, so anything that resolves its own path from $HOME ignores user-data-dir entirely.

Path	Written by / why	Deployment-owned
data/user/	code-server, from user-data-dir in config/config.yaml	yes, in-project
data/extensions/	code-server, from extensions-dir in config/config.yaml	yes, in-project
/home/loca/.local/share/code-server/heartbeat	the running server, regardless of user-data-dir	yes, but outside the project
/home/loca/.local/share/code-server/coder-logs/	same server process, default log location	yes, but outside the project
/home/loca/.continue/	the Continue extension on first activation, resolved from $HOME	no — extension-owned, holds its real config and chat history
/home/loca/.claude/, /home/loca/.claude.json	pre-existing operator state shared with the host Claude Code CLI	no — operator-wide, not created by the extension install, never delete as part of cdsr maintenance

• practical consequence: the deployment is reproducible from the project directory for the editor, extension binaries and editor settings, but extension-owned configuration and chat history are not, so a backup of /home/loca/dev/code-server alone is incomplete — ~/.continue has to be archived alongside it

Websocket + long-poll requirement

• Nginx must proxy websocket upgrades for terminal, shell, and extension transport:
  • proxy_http_version 1.1
  • proxy_set_header Upgrade $http_upgrade
  • proxy_set_header Connection $connection_upgrade
• keep long sessions with proxy_read_timeout 86400