quant-os/ops/README.md

Quant OS public status operations

The repository is the source of truth for the public status page. A deployment contains exactly:

/srv/www/quant-os/
  releases/<git-sha>/
    index.html
    status-data.js
  status -> releases/<git-sha>

Deployment invariants:

1. run python3 tools/build_public_status.py --check and the full local suite;
2. deploy from a clean, pushed commit and name the release with that full SHA;
3. acquire the web-root deployment lock and copy into a same-filesystem .incoming-<sha> directory;
4. require exactly two regular, non-symlink payload files and compare local and staged SHA-256 for both;
5. atomically rename the verified incoming directory to the immutable release;
6. create a temporary relative symlink and activate it with one atomic rename;
7. install nginx/quant-os-static.conf, run nginx -t, then reload;
8. verify the canonical page, generated JavaScript, cache header and all legacy redirects from a public client;
9. keep the previous release for rollback.

The server-side deploy and activation are executable and fail closed:

ops/deploy_static_status.sh <full-git-sha> <staged-status-dir>
ops/activate_static_status.sh <previous-full-git-sha>

The first command rejects a symlinked source root, symlink payloads, directories and any third source entry, holds .status-deploy.lock across staging and activation, verifies both SHA-256 values, atomically promotes .incoming-<sha>, and refuses to overwrite an existing release. Promoted payload files and their release directory are owner read-only. The second command is the rollback/activation primitive; when called directly it takes the same lock and switches only a relative symlink. A stale lock or incoming directory means a prior process may have crashed: inspect it and confirm no deploy is running before removing it.

Nginx is deliberately two-stage:

1. include nginx/quant-os-static.conf in the existing HTTPS server block, run nginx -t, reload, and verify /quant-os/status/;
2. only then include nginx/quant-os-legacy-redirects-302.conf, preserving the existing broad /quants-strategies/ route for other projects;
3. after an observation period and a separate production change, replace the 302 include with quant-os-legacy-redirects-308.conf.

Rollback only changes the status symlink to the previously verified release and reloads no application state. The page is a static, redacted build-time snapshot; it must never contain credentials, local paths, market data, account identifiers, positions or fills.