Cloudflare Pages + Access Deployment

This runbook publishes the Lurnet docs as a Cloudflare Pages static site and restricts access to allowed users with Cloudflare Zero Trust Access.

Local Commands

npm ci
npm run verify
npm run docs:dev

The docs build output is docs/.vitepress/dist.

Cloudflare Pages Setup

1. In Cloudflare, open Workers & Pages.
2. Create a Pages application from the Git repository.
3. Use these build settings:

Setting	Value
Framework preset	VitePress
Production branch	main
Root directory	/
Build command	npm run docs:build
Build output directory	docs/.vitepress/dist
Node.js version	22.16.0 from .node-version

Cloudflare Pages installs dependencies before running the build command. The build must pass npm run verify locally before pushing changes.

Custom Domain

Attach the docs hostname you want to protect, for example docs.example.com, to the Pages project.

Use the custom domain as the canonical docs URL. Do not share the generated *.pages.dev production URL with users unless you have also protected or redirected it.

Zero Trust Access Setup

1. In Cloudflare Zero Trust, open Access controls > Applications.
2. Add an application and choose Self-hosted.
3. Name it Lurnet Docs.
4. Add the public hostname that points to the Pages custom domain, for example docs.example.com.
5. Add an Allow policy for the allowed users. Start with explicit email addresses or your identity provider group.
6. Keep the application deny by default. Users who do not match an Allow policy should be blocked.
7. Choose the identity provider users should authenticate with. For a single provider, enable Instant Auth.
8. Save the application and test in a private browser session with one allowed account and one blocked account.

Preview Deployment Access

Cloudflare Pages preview deployment URLs on <hash>.<project>.pages.dev are public unless protected separately.

Enable preview protection in the Pages project:

1. Open the Pages project.
2. Go to Settings > General.
3. Enable Access policy for preview deployments.

This protects preview deployment URLs, but it does not protect the production <project>.pages.dev URL or the custom domain. The custom domain is protected by the self-hosted Access application above.

Production pages.dev URL

The production <project>.pages.dev URL can bypass the custom-domain Access application if it remains reachable. Use one of these controls before treating the docs as private:

1. Configure the Pages project to redirect *.pages.dev traffic to the protected custom domain, or
2. Create an additional Access application for the production <project>.pages.dev hostname, or
3. Avoid distributing the pages.dev URL and validate that it is not discoverable enough for your risk profile.

Prefer option 1 or 2 for private planning docs.

Deployment Checklist

• npm run verify passes locally.
• Pages build command is npm run docs:build.
• Pages output directory is docs/.vitepress/dist.
• Custom domain is attached to the Pages project.
• Zero Trust Access self-hosted application protects the custom domain.
• Access policy allows only approved users or groups.
• Preview deployment Access policy is enabled.
• Production pages.dev bypass risk is handled.