Cloudflare Pages Setup for Kemma Docs

This guide details how to deploy the Kemma documentation site to Cloudflare Pages.

Configuration

When setting up a new project in Cloudflare Pages, use the following build settings:

Setting	Value	Description
Framework Preset	None / Custom	We use a custom TurboRepo command.
Build Command	npx turbo build --filter=docs	Builds only the documentation workspace.
Build Output Directory	apps/docs/docs/.vitepress/dist	The default VitePress output location.
Root Directory	/ (Default)	Crucial: Must be the repo root to access package.json and turbo.json.

Environment Variables

Ensure the Node.js version matches the project requirement.

Variable Name	Value	Purpose
NODE_VERSION	20	Sets the build environment to Node.js 20 (or higher).

Why these settings?

• Build Command: We use npx turbo build --filter=docs instead of running vitepress build directly inside the app folder. This allows TurboRepo to handle orchestration and ensures all workspace dependencies are correctly resolved from the root.
• Root Directory: Cloudflare Pages needs access to the root package-lock.json to install dependencies correctly. Setting the root directory to apps/docs would fail because it couldn't find the workspace lockfile.
• Output Directory: VitePress compiles the static site into .vitepress/dist relative to the documentation source root.

Access Control (Private Documentation)

To make these docs private (behind a login screen), use Cloudflare Zero Trust (Access). This does not require any code changes, only configuration in the Cloudflare dashboard.

1. Enable Zero Trust: Go to the Cloudflare Dashboard and select Zero Trust from the sidebar.
2. Add Application:
   • Navigate to Access > Applications.
   • Click Add an application and select Self-hosted.
3. Configure Application:
   • Application Name: e.g., "Kemma Docs".
   • Session Duration: e.g., "24 hours".
   • Application Domain: Enter the specific subdomain where your docs are deployed (e.g., docs.kemma.pages.dev or your custom domain).
4. Add Policy:
   • Policy Name: e.g., "Allow Team".
   • Action: Allow.
   • Configure Rules:
     • Include -> Emails -> Enter authorized email addresses.
     • OR Include -> Emails Ending In -> Enter your organization's domain (e.g., @kemma.app).
5. Save: Click Add Application.

Now, when anyone visits the documentation URL, they will be prompted to sign in using the configured identity provider (e.g., Google, GitHub, or One-Time PIN sent to email).

Alternative: Social Login (GitHub/Google)

If entering an email and waiting for a code is too tedious, the best "easy" alternative is Social Login. This allows you to log in with a single click using your existing GitHub or Google account.

Note: Cloudflare Access does not support a simple "Shared Password" (like password123) because it is an identity-based security tool. It needs to know who accessed the site.

Setup GitHub/Google Login

1. Add Identity Provider:
   • In Cloudflare Zero Trust, go to Settings > Authentication.
   • Under Login methods, click Add new.
   • Select GitHub or Google.
   • Follow the instructions to create an OAuth App in GitHub/Google and paste the Client ID and Client Secret back into Cloudflare.
2. Update Application Policy:
   • Go back to Access > Applications and edit your "Kemma Docs" app.
   • In your Policy, you can now add rules like:
     • Include -> Login Method -> GitHub.
     • AND Include -> GitHub Organization -> YourOrgName.

Deployment Process

Cloudflare Pages works by connecting directly to your GitHub repository.

1. Automatic Builds: Once you connect the repo in the Cloudflare Dashboard, Cloudflare will automatically:
   • Detect every new commit to your main branch.
   • Clone the repo.
   • Run the Build Command you configured (npx turbo build --filter=docs).
   • Deploy the output.

You do not need a separate GitHub Action workflow.

Note: The existing file .github/workflows/deploy-docs.yml is configured for GitHub Pages, not Cloudflare. If you strictly use Cloudflare Pages, you can disable or delete that workflow to save GitHub Actions minutes.