Skip to main content

Engineering docs — runbook

Prerequisites (operator machine)​

  • Node.js + npm, Wrangler 4.x (npm i -g wrangler)
  • Wrangler logged in to the TTG Cloudflare account (wrangler login --use-keyring, check with wrangler whoami)
  • Write access to thetaxgraph-ai/engineering-docs

Write and preview​

git clone git@github.com:thetaxgraph-ai/engineering-docs.git
cd engineering-docs
npm ci
npm start                 # live preview at http://localhost:3000
  • Add pages under docs/<area>/ and register them in sidebars.ts.
  • Broken links fail the build (onBrokenLinks: 'throw').
  • Diagrams: edit the .drawio source in its product repo, export PNG to static/img/<area>/ (drawio -x -f png -s 2 -b 20 -p <page> -o static/img/<area>/<name>.png <file>.drawio).

Publish​

npm run build             # static output in ./build (needs a git checkout: pages show "last updated")
wrangler deploy           # uploads ./build to the Worker; custom domain from wrangler.toml

Wrangler prints docs.thetaxgraph.com (custom domain) and a version id on success.

:::caution wrangler.toml ordering routes = [...] must come before the [assets] table. Placed after it, TOML reads it as assets.routes, Wrangler only warns, and the deploy ends with "No targets deployed". :::

Verify after every publish​

B=https://docs.thetaxgraph.com
curl -sL -o /dev/null -w '%{http_code}\n' $B/                      # 200 (or Access login once enabled)
curl -s  -o /dev/null -w '%{http_code}\n' $B/does-not-exist         # 404 page
curl -s $B/ | grep -o 'noindex, nofollow'                            # search engines blocked

Roll back​

wrangler deployments list          # find the previous version
wrangler rollback <version-id>

Enable Cloudflare Access (one-time, account owner)​

  1. Cloudflare dashboard → Zero Trust → choose team name → Free plan.
  2. Workers & Pages → engineering-docs → Access → Protect this Worker behind Access → All traffic.
  3. Policy: Allow → emails ending in the TTG domain (+ named individuals). Login: One-time PIN.
  4. Verify logged out: curl -sI https://docs.thetaxgraph.com/ must redirect to the Access login, with no docs content.
Last updated on