Ops handbook site (ops.lovely-home.co.uk)
Internal VitePress site built from this repository’s docs/ folder. Published to Cloudflare Pages, gated with Cloudflare Access for platform operators (and support emails you add to the Access policy).
Local preview
cd ops-handbook
npm ci
npm run dev # runs predev: stages docs/ and copies public/ logos into staged-docsBrand SVGs live in ops-handbook/public/ (nav lockup + home hero). The tab icon is ops-handbook-icon.svg (navy book), kept distinct from the green-house hub/marketing icon and the Playwright icon on the E2E reports index. If logos 404 locally, restart dev after npm run dev so staging and vite.publicDir pick them up.
Open the URL VitePress prints (default http://localhost:5173). Edits under docs/ hot-reload.
Pages are compiled as Vue templates. {{ … }} in inline code or prose is shown as written (the markdown config adds v-pre, #1318); {name} placeholders are escaped too. Fenced code blocks are always literal.
Production deploy
Automatic: push to main when docs/** or ops-handbook/** changes — workflow Deploy ops handbook runs on GitHub-hosted runners and uploads ops-handbook/dist via Wrangler.
Manual:
bash scripts/deploy-ops-handbook.shRequires Wrangler auth and permission to deploy to Pages project lovely-home-ops. Deploy runs from ops-handbook/ (static only — no repo functions/ middleware).
First-time Cloudflare setup
- Create the Pages project once:
npx wrangler pages project create lovely-home-ops --production-branch main(the deploy script no longer creates it, #1594), then run the deploy. - Pages → lovely-home-ops → Custom domains → add
ops.lovely-home.co.uk(Cloudflare usually creates the DNS record automatically). - Run Platform admin Terraform — it imports an existing DNS record / Access app when present, then manages the Lovely Home — Ops handbook Zero Trust app.
- Optional: disable public
*.pages.devpreviews for this project if you do not want an unbranded URL.
Terraform (Access gate)
Platform admin Terraform (GitHub Actions → Platform admin Terraform, confirm apply-platform-admin) creates the Zero Trust app and DNS. It does not read your local terraform/environments/hub.tfvars — CI runs scripts/generate-hub-tfvars.mjs from repo secrets (OPS_HANDBOOK_ACCESS_ENABLED, optional OPS_HANDBOOK_HOSTNAME).
Defaults in CI: Access on, hostname ops.lovely-home.co.uk, Pages project lovely-home-ops.
Local hub.tfvars is for your reference / manual experiments only; keeping it aligned avoids confusion but CI apply does not use it. Prefer re-running the workflow over terraform apply with a laptop copy of secrets.
If your custom domain differs from the default, set repo variable or workflow env OPS_HANDBOOK_HOSTNAME (and match Pages → Custom domains), then re-run Platform admin Terraform.
That workflow manages the Access application for the ops hostname (operator OTP, same email list as platform admin). It does not replace the GitHub deploy workflow — Pages content still comes from Wrangler upload.
Guest readers (platform dashboard)
Platform settings → Site access → Ops handbook access — same pattern as marketing: add support or contractor emails to the Cloudflare Platform operators policy without editing Terraform. Operators come from Platform operators on the same page (#1214).
Set ops_handbook_access_enabled = false only if you intentionally expose the handbook (not recommended).
Content rules
- Do: workflow names, secret names, architecture, URLs, runbook steps.
- Do not: paste API keys, webhook signing secrets,
HUB_PROXY_SECRETS_JSONvalues, or customer PII.
Customer-facing help stays on lovely-home.co.uk/help.
Build layout
| Path | Purpose |
|---|---|
docs/*.md | Handbook pages (source of truth in git) |
scripts/stage-ops-handbook-docs.mjs | Copies docs/ → ops-handbook/staged-docs (escapes {placeholder} for VitePress) |
ops-handbook/.vitepress/config.mts | Nav, search, theme |
ops-handbook/dist/ | Static output (gitignored) |