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 mkdocs.apexstem.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)

Cloudflare renamed Zero Trust to Cloudflare One. Same product; navigation changed.

Detailed steps: cloudflare_one_access_setup.md

Short path:

  1. Open one.dash.cloudflare.com (or dash.cloudflare.com → sidebar Zero Trust / Cloudflare One).
  2. First visit: complete team name + choose Zero Trust Free (payment step may appear but Free is $0).
  3. Left nav: Access controls → Applications → Create new application.
  4. Self-hosted and private → Add public hostname → domain docs.apexstem.org.
  5. Access policies → create Allow policy (trustee email addresses).
  6. Identity providers → enable the provider your org uses (for example One-time PIN, Auth0, or Google).
  7. Create — no Tunnel required (Pages already serves the hostname).

Test in incognito at https://docs.apexstem.org.

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 mkdocs.apexstem.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