hypertwist/website/deploy

HyperTwist Website Deployment Templates

This folder contains first-party same-origin deployment templates for the public hypertwist.app website plus auth-server lane.

Files:

• hypertwist.same-origin.bundle.example.json
• nginx/hypertwist.app.conf.example
• systemd/hypertwist-website-auth-server.service.example
• ../scripts/render-same-origin-deployment.mjs
• ../scripts/render-same-origin-bundle.mjs

Expected deployment posture:

• NGINX terminates TLS for hypertwist.app
• NGINX reverse-proxies the full public origin to the local website/server Express process
• the Express process serves both the built website/dist bundle and the /api/* plus /auth* route families on the same origin
• the shared VPS default upstream port for this lane is now 3011, not 3001, because the live host already has FamiliarOS occupying 3001

Before using these templates:

• preferred path: copy hypertwist.same-origin.bundle.example.json, replace the placeholder values, and render a validated deployment bundle with npm run render:same-origin-bundle -- --manifest <file> --out-dir <dir>
• set publicOrigin to the exact live origin that should own both the website and auth cookies; for the canonical production lane that value is https://hypertwist.app
• keep server.port on a free shared-host port; the checked-in example uses 3011 because the current shared VPS already has FamiliarOS on 3001
• either render resolved files with npm run render:same-origin-deployment -- --checkout-root /srv/hypertwist/current --systemd-out ... --nginx-out ... or replace filesystem paths manually inside the example files
• replace service-user/group values if the process does not run as hypertwist
• fill real production values into website/.env and website/server/.env
• build the frontend bundle with npm run build in website/

Canonical operator guide:

• docs/ops/HYPERTWIST_WEBSITE_SAME_ORIGIN_DEPLOYMENT_HANDOFF_2026-06-22.md