#428

docs/commands.md

@@ -37,3 +37,56 @@ npm run test:run
 cd backend && bundle exec rspec
 cd ../frontend && npm run test:run && npm run build && npm run lint
 ```
+
+### Help SSR in production
+
+Build both `dist/client` and `dist/server` with `npm run build`, deploy them
+together, and restart the Node process. `npm run dev` and `npm run preview`
+remain CSR servers; use `npm start` for SSR. The old sitemap generator is not
+part of this build.
+
+The following environment is a deployment proposal, not an applied VPS change:
+
+```sh
+cd frontend
+export NODE_ENV=production
+export HOST=127.0.0.1
+export PORT=5174
+export PUBLIC_ORIGIN=https://hub.nizika.monster
+export SSR_API_BASE_URL=http://127.0.0.1:3002
+npm start
+```
+
+Run this command through the VPS's process supervisor. Port 5174 avoids the
+Vite development port 5173. Rails remains on 127.0.0.1:3002. `PUBLIC_ORIGIN`
+must match the public HTTPS origin, including any non-default port; redirect
+alternate hostnames to that origin. `SSR_API_BASE_URL` configures server-side
+public API requests only. Keep the browser's existing API configuration pointed
+at the public `/api` endpoint.
+
+Inside the existing Apache HTTPS virtual host, with `proxy`, `proxy_http` and
+`headers` enabled, preserve the API rules before the catch-all frontend rule:
+
+```apache
+ProxyPreserveHost On
+RequestHeader set X-Forwarded-Proto "https"
+
+ProxyPass        "/api/" "http://127.0.0.1:3002/"
+ProxyPassReverse "/api/" "http://127.0.0.1:3002/"
+
+ProxyPass        "/" "http://127.0.0.1:5174/"
+ProxyPassReverse "/" "http://127.0.0.1:5174/"
+```
+
+Retain existing TLS, authentication-header handling and any exact `/api` rule.
+Replace the previous SPA catch-all rewrite instead of rewriting Help or missing
+URLs to `index.html` before they reach Node. Do not override Node's 404/503
+responses with an SPA fallback or cache its HTML. Hashed assets may be cached;
+deployments must keep old hashed files available for already-open clients.
+
+Only Help detail pages are server-rendered. Known CSR routes remain client
+rendered, old known routes redirect to Japanese URLs, and unknown routes/assets
+return 404. A failed Help preload keeps the readable server HTML, retries on
+online/focus/pageshow, and permits one automatic reload per bundle and URL in
+session storage. If storage is unavailable or the failure persists, the HTML
+remains intact; native links and manual reload remain available.