Deploy the Docs to Cloudflare (Dashboard Guide)

Step-by-step to host backend/docs as a website on Cloudflare Pages, gated by Cloudflare Access so only approved people (your team) can read it. Everything here is done from the Cloudflare dashboard — no CLI required.

There are two parts:

1. Cloudflare Pages — builds and hosts the VitePress site from this repo.
2. Cloudflare Access — puts a login gate in front of it (Free up to 50 users).

Why Access instead of GitHub Pages: a GitHub Free org can only publish public Pages, which anyone with the URL could read. Cloudflare Access gives you a private, login-gated site that mirrors "only our people."

---

Part 1 — Create the Pages project (Git-connected)

Step 1: Open Workers & Pages

1. Log in at dash.cloudflare.com.
2. Left sidebar → Workers & Pages.
3. Click Create application → Pages tab → Connect to Git.

Step 2: Connect the repository

1. Authorize Cloudflare for GitHub if prompted (org: OP-Oktivo).
2. Select the repo that holds this code (oktivo_app / oktivo-voice-app).
3. Click Begin setup.

Step 3: Configure build settings (the important part)

This is a monorepo, so the docs live in a subdirectory. Set:

Setting	Value
Project name	oktivo-backend-docs (any unique name; becomes the *.pages.dev subdomain)
Production branch	main (or whichever branch you want live)
Framework preset	VitePress (or None if not listed)
Build command	npm run docs:build
Build output directory	.vitepress/dist
Root directory (Advanced)	backend/docs

Root directory is the key field — it tells Cloudflare to cd backend/docs before installing and building. With it set, the build command and output directory are relative to backend/docs, so use .vitepress/dist (not backend/docs/.vitepress/dist).

Optional environment variable (recommended for a consistent build):

• Variable: NODE_VERSION Value: 20

Step 4: Save and Deploy

1. Click Save and Deploy.
2. Watch the build log. On success you get a URL like https://oktivo-backend-docs.pages.dev.
3. Open it — the docs site should load (it's public for now; Part 2 locks it down).

Step 5 (optional): Only rebuild when docs change

To avoid rebuilding on every unrelated backend/app commit:

1. Project → Settings → Build → Build watch paths.
2. Include paths: backend/docs/*
3. Save. Now pushes that don't touch backend/docs skip the docs build.

Step 6 (optional but recommended): a nicer custom domain

1. Project → Custom domains → Set up a custom domain.
2. Enter e.g. docs.oktivo.<yourdomain> (the zone must be on Cloudflare).
3. Cloudflare adds the DNS record automatically. Use this hostname in Part 2.

If you skip the custom domain, you can still protect the *.pages.dev URL in Part 2.

---

Part 2 — Lock it down with Cloudflare Access

This adds an identity gate. Visitors must sign in (Google / GitHub / email code) and match an Allow policy before they see any page. Access is deny-by-default.

Step 1: Open Zero Trust

1. In the dashboard, go to Zero Trust (sidebar). First time only: pick a team name and the Free plan (supports up to 50 users, no card needed for Free).

Step 2: Add a login method (identity provider)

1. Settings → Authentication → Login methods → Add new.
2. Easiest to start: One-time PIN (emails a code — no IdP setup).
   • Or add Google / GitHub for SSO if your team uses one.

Step 3: Create the Access application

1. Access controls → Applications → Add an application.
2. Choose Self-hosted.
3. Application name: Oktivo Backend Docs.
4. Application domain: enter the hostname from Part 1:
   • the custom domain (docs.oktivo.<yourdomain>), or
   • the Pages domain (oktivo-backend-docs.pages.dev).

     To protect a *.pages.dev domain you may need to add it under Settings → Custom Pages/Domains of Zero Trust; a real custom domain on a Cloudflare zone is the smoother path.

5. Leave session duration at the default (e.g. 24h) or shorten it. Click Next.

Step 4: Create the Allow policy (who gets in)

1. Policy name: Allow Oktivo team.
2. Action: Allow.
3. Add a rule under Include — pick ONE that fits how you want to define access:
   • Emails ending in → @yourcompany.com (everyone on your domain), or
   • Emails → an explicit list of teammate emails, or
   • Login method / Identity provider → GitHub, combined with an email rule.
4. (Optional) Add Require rules to tighten further (e.g. specific country).
5. Save the policy, then Next → Add application.

Access can't read GitHub repo collaborators directly. The practical equivalent of "repo access" is an email-domain rule or an explicit email allow-list that you keep in sync with the team.

Step 5: Test

1. Open the docs URL in a private/incognito window.
2. You should hit a Cloudflare Access login screen.
3. Sign in with an allowed identity → the docs load.
4. Try a non-allowed email → access is denied. Done.

---

How updates work after setup

• Push to the production branch → Cloudflare auto-builds and redeploys the docs.
• The Access gate stays in place across deploys.
• To add/remove people: Zero Trust → Access → Applications → (the app) → Policies.

Troubleshooting

Symptom	Cause	Fix
Build fails: vitepress: not found	Root directory not set	Set Root directory = backend/docs
Build fails: output dir empty	Wrong output path	Build output directory = .vitepress/dist (relative to root dir)
Build fails on Node version	Old Node on builder	Add env var NODE_VERSION=20
Site loads but no login prompt	Access app domain mismatch	Ensure the Access Application domain exactly matches the live hostname
Anyone can view it	No Allow policy / app not covering domain	Confirm the Access application covers the exact hostname and has an Allow policy
Mermaid diagrams blank	Build used stale cache	Retry deployment / clear build cache in project settings

Alternative: deploy without Git (direct upload)

If you prefer not to connect the repo, build locally and upload:

cd backend/docs
npm install
npm run docs:build
npx wrangler pages deploy .vitepress/dist --project-name oktivo-backend-docs

Then apply the same Cloudflare Access steps (Part 2) to the resulting project.