Skip to content

Deploy docs.apexstem.org — Cloudflare Pages

Output: MkDocs → site/apexstem-docs
Domain: docs.apexstem.org
Protect with: Cloudflare Access (rbac-groups.md)

  1. Cloudflare dashboard → Workers & Pages → Create → Pages → Connect to Git.
  2. Authorize GitHub → select repo rexnfx79/STEMRacing.
  3. Project name: apexstem-docs
  4. Production branch: main (or master)

Build settings

Setting Value
Framework preset None
Build command pip install -r docs-requirements.txt && mkdocs build -f apexstem/mkdocs.yml
Build output directory site/apexstem-docs
Root directory / (repo root)

Environment variable (optional):

Variable Value
PYTHON_VERSION 3.12
  1. Save and Deploy — wait for first build green.
  2. Custom domains → Set up a custom domain → docs.apexstem.org.
  3. DNS record for docs should appear automatically (proxied CNAME).

After deploy

  • Open https://docs.apexstem.org — should show Material theme home.
  • If SSL pending, wait up to 15 minutes.

Path B — GitHub Actions + Wrangler (CI deploy)

Use when you prefer deploy from Actions or Git connect is unavailable.

1. Create API token

Cloudflare → My Profile → API Tokens → Create Token → template Edit Cloudflare Workers (includes Pages) or custom with:

  • Account → Cloudflare Pages → Edit
  • Account → Account Settings → Read

2. GitHub secrets

Repo STEMRacing → Settings → Secrets and variables → Actions:

Secret Value
CLOUDFLARE_API_TOKEN Token from step 1
CLOUDFLARE_ACCOUNT_ID Dashboard → right sidebar on any zone

3. Workflow

Push to main runs .github/workflows/deploy-apexstem-docs.yml.

Or: Actions → Deploy apexstem docs → Run workflow.

Cloudflare Access (required before sharing widely)

  1. Zero Trust → Access → Applications → Add application.
  2. Type: Self-hosted.
  3. Application domain: docs.apexstem.org (or docs.apexstem.org/*).
  4. Identity providers: Google (match trustee Google accounts).
  5. Policies:
  6. Policy 1: Allow — Emails in — you@gmail.com, spouse, mentor, etc.
  7. Or use Google Group emails for trustees.
  8. Save — test in incognito: should redirect to login.

Optional: separate policies per path later (/internal/...) when you split content.

Site README already states Access is path-based. Add to Zero Trust Custom page or MkDocs extra if desired.

Force latest commit (if log shows HEAD is now at 2012cdb)

Retry deployment rebuilds the same old commit. GitHub main must include docs-requirements.txt (commit 112c016 or later).

  1. Workers & Pages → apexstem-docs → Settings → Builds → Production branch = main
  2. Deployments → Create deployment (or View build on latest) — pick main / latest commit — not “Retry” on the failed row
  3. Or: Settings → Builds → Configure → Save to re-link; or push any commit to main to trigger webhook

Confirm log shows: HEAD is now at 112c016 (or newer), not 2012cdb.

Troubleshooting

Issue Fix
No such file or directory: docs-requirements.txt Old commit on build — see § Force latest commit below (do not use Retry on a failed deploy)
Build fails site_dir Ensure output is site/apexstem-docs not apexstem/site
npx wrangler deploy in log Wrong project type — use Pages with output directory, not Worker deploy
404 on custom domain Confirm docs CNAME in DNS; Pages domain “Active”
Repo not listed Install Cloudflare Pages GitHub app on rexnfx79/STEMRacing
Actions deploy 403 Token needs Pages Edit on correct account ID
Site public without login Access app not attached to hostname — add application

Local preview

pip install -r docs-requirements.txt
mkdocs serve -f apexstem/mkdocs.yml

Open http://127.0.0.1:8000

Checklist

  • [ ] Pages project apexstem-docs build succeeded
  • [ ] docs.apexstem.org loads HTTPS
  • [ ] Cloudflare Access enabled
  • [ ] Trustees can log in (incognito test)
  • [ ] Update portal/STATUS.md