docs(dev): explain the combined Vite and FastAPI launcher

2026-10-06 16:53:40 -03:00
parent c8f8aff8c7
commit 99413fc06d
6 changed files with 170 additions and 78 deletions
@@ -22,6 +22,24 @@ In browser DevTools, inspect the WebSocket handshake and `session.created`,
 inside `session`. A cached browser module can disagree with current server
 code; inspect served asset versions and reload with cache disabled when needed.

+## Launcher and hot reload
+
+`start_ui.sh` serves Vite on `8420` and FastAPI on loopback port `8421` by
+default. Check both processes in the launcher/PM2 logs. If either exits, the
+launcher stops the other and returns a failure. Port conflicts are errors;
+use distinct `UI_PORT` and `S2S_BACKEND_PORT` values for additional worktrees.
+
+A Vite "Blocked request" response means the public hostname is missing from
+`S2S_DEV_ALLOWED_HOSTS`. Configure it without a scheme or port and restart the
+launcher. If the page loads but edits do not appear, check the browser's
+`/__vite_hmr` WebSocket and the reverse proxy's upgrade handling. Speech uses
+the separate `/v1/realtime` WebSocket on the same public origin.
+
+For a startup dependency error, check Node/npm on the process manager's PATH,
+Python venv support, and `setsid`/`curl`. The first start installs dependencies;
+later starts reuse them until frontend manifests change. Changes to root
+`.env` or launcher settings require a restart.
+
 ## The assistant promises a tool but nothing happens

 Follow the actual execution mechanism: