Hosting and deployment¶
Status (2026-10-28): the sanitised public build is live at https://machine-world-kb.pages.dev/ (Cloudflare Pages project machine-world-kb, classic Pages, Direct Upload with Wrangler, approved by the user). The private build is not deployed anywhere. No Git repository was created.
Redeploy the public site after an update:
server\venv\Scripts\python.exe machine-world-knowledge\scripts\build_site.py --mode public
cd machine-world-knowledge
npx wrangler pages deploy _work\site_public --project-name machine-world-kb --branch main --commit-dirty=true
Wrangler 4.x routes pages commands to the newer Workers-based Pages; this project was created once with --force on classic Pages, and later commands need no --force.
What the public build removes or rewrites (build_site.py --mode public, rules in sources/config.json): transcripts and links to them; original-language quotes; "Uncertain passages" and "Dates mentioned in the audio" sections; the source index, CLI investigation, knowledge-core snapshots, local-documents list, README and update log; local paths; names of people from the meetings (public_redact_names → "[name withheld]"); the engine's internal name → "cessation" and doctrine terms → "[doctrine term]" (public_replace_terms, per the owner's public-wording rule); recording file names that reveal places or exact times.
First decision: private or public?¶
This base contains raw transcripts of internal discussions, verbatim quotes, names of participants, recording file names and the owner's source-of-truth file marked "Read-only" for collaborators. Default: private. Two builds exist:
| Build | Command | Contains | Who may see it |
|---|---|---|---|
| Private | build_site.py → _work/site/ |
everything, incl. transcripts | you and people you invite |
| Public preview | build_site.py --mode public → _work/site_public/ |
no transcripts, quotes, owner snapshots, source index or local paths | nobody until reviewed: see _work/public-review.md (restricted terms, names) |
The source of truth also sets public wording rules ("cessation"; no internal engine name or doctrine terms in public copy). The public preview reports these terms; it does not rewrite them. That is the owner's edit.
Hosting options compared (terms checked 2026-10-28)¶
| Host | Free tier (official pages) | Keep the site private for free? | Fit |
|---|---|---|---|
| Cloudflare Pages | 500 builds/month, 1 concurrent build, 20,000 files/site, 25 MiB per file, 100 projects (limits) | Yes, with Cloudflare Access (Zero Trust free plan: up to 50 users, $0, ZTNA included (plans)). Preview deployments: one-click "Enable access policy"; the *.pages.dev production domain needs its own Access application (preview docs) |
Recommended |
| GitHub Pages | 1 GB site, 100 GB/month soft bandwidth, 10 builds/hour soft limit, 10 min deploy timeout (limits) | No: access-controlled Pages need GitHub Enterprise Cloud (visibility) | Good for a reviewed public build only |
| Netlify | Credit-based Free plan, 300 credits (pricing) | No: password protection "isn't available on Credit-based Free and Personal plans"; a private project is visible only to the team owner (docs) | Already hosts the public machineworld-docs site |
| Vercel | Hobby plan | Partly: "Vercel Authentication" can protect all deployments on every plan, but only for Vercel users with access; password protection is "Not available on Hobby" (docs) | Workable for 1–2 readers with Vercel accounts |
Recommendation: Cloudflare Pages + Cloudflare Access. It is the only option that keeps the full private build behind a login (email one-time PIN or Google) for free, for up to 50 readers. It serves plain static files, so MkDocs output needs no adapter. Deploy either with Direct Upload of _work/site/ (no Git host needed, nothing leaves your machine except the built site) or from a private Git repository.
Not needed: backend, database, paid plan, custom domain.
Deploy steps (run only after approval)¶
# 1. Build and check locally
server\venv\Scripts\python.exe machine-world-knowledge\scripts\build_site.py # strict build
server\venv\Scripts\python.exe machine-world-knowledge\scripts\build_site.py --serve # http://127.0.0.1:8000
# 2. One-time: Cloudflare account (yours), then in Zero Trust > Access > Applications:
# add a self-hosted application for <project>.pages.dev and *.<project>.pages.dev,
# policy: Allow, emails = the readers you choose. Do this BEFORE the first upload.
# 3. Upload the built site (Direct Upload with Wrangler; needs Node)
npx wrangler pages project create machine-world-kb --production-branch main
npx wrangler pages deploy machine-world-knowledge\_work\site --project-name machine-world-kb
Then open the pages.dev URL in a private window and confirm the Access login appears before any content.
Git-based alternative: push machine-world-knowledge/ to a private repo and set Cloudflare Pages build command pip install -r site/requirements.txt && python scripts/build_site.py, output _work/site. Note transcripts/ and notes/ are git-ignored, so a Git build cannot include transcripts or regenerate pages. Use Direct Upload for the private build.
Version pins¶
site/requirements.txt pins mkdocs==1.6.1, mkdocs-material==9.7.7, pymdown-extensions==12.1. The Material team warns that MkDocs 2.0 removes the plugin system with no migration path, so do not upgrade MkDocs past 1.x without testing.