# 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, fail if the live anonymous release-manifest drifted from the
  rendered launch authority, 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
- as of `2026-07-02`, `.woodpecker/hypertwist-bootstrap.yml` includes a
  `website_live_deploy` step for `main` pushes that invokes this same helper
  after website frontend and auth-server validation, using
  `HYPERTWIST_VPS_SSH_KEY_PATH` and `HYPERTWIST_SAME_ORIGIN_MANIFEST` when the
  builder provides them
- a git push only counts as published after that helper-backed CI deploy, or a
  manual invocation of the same helper, has completed and the public origin has
  been revalidated
- 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`