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
• ../scripts/run-vps-same-origin-staging-proof.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>
• keep deploymentTier on launch for public cutover; use preview only for non-public rehearsal, where operator checkout, Windows download, release-manifest version/build/checksum/published-at values, and server.paddleWebhookSecret may be honestly blank and warn instead of fail while placeholder strings still remain invalid
• before any root-owned cutover, you can now also run npm run run:vps-same-origin-staging-proof -- --manifest <file> --identity-file <key> from the local repo to stage the current committed website/ tree into a VPS temp checkout, boot it on the host-safe staging port, verify the real /health, /api/auth/health, /api/releases/manifest, and root shell surfaces, and clean the temp lane back up on success; add --archive-source worktree when the proof should use the in-progress local worktree rather than committed HEAD
• after staging proof or for direct root-owned rollout, you can now also run npm run run:vps-same-origin-live-deploy -- --manifest <file> --identity-file <key> to stage the committed checkout, upload the rendered bundle, install env, build the site, replace the live systemd plus nginx files, and validate the public origin through the same readiness lane
• 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