TL-M0-23 · The docs site on Cloudflare Pages, behind Cloudflare Access

Why: apps/docs holds the decisions, the rules and the runbooks, and the upper-ups review the rules there before they are built. The site is internal: Cloudflare Access sits in front of every address, and a reviewer signs in with a one-time code sent to an email address on the list. It starts on Cloudflare's free pages.dev address. docs.opleet.com comes later, once opleet.com's DNS is on Cloudflare. The first deploy is by hand from this Mac (L0); deploying from CI on every merge comes after clean runs.

ID TL-M0-23 · Level L0 · Run order row 35, run early for the review · Issue #25

Goal

The docs site from main is at a pages.dev address, and every address of the project, production and previews, asks for a Cloudflare Access sign-in that only the emails on the list pass.

Before

• You can sign in at dash.cloudflare.com. If you have no account, create one there; the free plan is enough.
• A payment card at hand: Cloudflare Zero Trust asks for payment details even on its Free plan, and doesn't charge it.
• The email addresses of the reviewers, and your own.
• You are in the repository folder on main with nothing to commit.

Run

1 · Sign this Mac in to Cloudflare; a browser tab asks you to allow wrangler

pnpm dlx wrangler@4.148.0 login
pnpm dlx wrangler@4.148.0 whoami

2 · Create the Pages project, with nothing published yet

pnpm dlx wrangler@4.148.0 pages project create opleet-docs --production-branch main

Below, <DOCS_URL> is the pages.dev address this prints, such as opleet-docs.pages.dev. If the name is taken, Cloudflare adds a few characters to it.

3 · Set up Zero Trust once, then turn on sign-in by email code

In the browser: dash.cloudflare.com › Zero Trust. Choose the team name opleet, choose the Free plan, and enter the payment details. Then go to Zero Trust › Integrations › Identity providers › Add new identity provider › One-time PIN, and save.

4 · Put Access in front of the production address and every preview, before anything is published

In the browser, following Cloudflare's steps for a pages.dev project:

1. Workers & Pages › opleet-docs › Settings › Enable access policy.
2. Select Manage on the Access policy it created for preview deployments.
3. In Access › Applications (called Access controls › Applications in newer dashboards), select opleet-docs, then Configure.
4. Under Public hostname, in the Subdomain field, delete the wildcard (*) and save. If saving fails, change the application name a little, as Cloudflare notes, and save again.
5. Back in Workers & Pages › opleet-docs › Settings › General, select Enable access policy again.
6. Check that Access › Applications now has two applications: one for <DOCS_URL> and one for *.<DOCS_URL>.
7. In each of the two, edit its policy: Action Allow, Include › Emails, and add your email and each reviewer's. Save.

5 · Build main and publish it

git switch main
git pull
pnpm install --frozen-lockfile
pnpm --filter docs build
pnpm dlx wrangler@4.148.0 pages deploy apps/docs/dist --project-name opleet-docs --branch main --commit-hash "$(git rev-parse HEAD)" --commit-message "$(git log -1 --format=%s)"

6 · Open it as a stranger would, then as yourself

In a private browser window, open https://<DOCS_URL>. You should get Cloudflare's sign-in page, not the docs. Enter your email, select Send login code, paste the code from your inbox, and the docs open. Then tell the reviewers the address, and that they sign in with the code sent to their email.

Expect

• Block 1: wrangler says you are logged in, then whoami shows your email and account.
• Block 2: a line saying the opleet-docs project was created, with its pages.dev address.
• Block 3: One-time PIN is listed under Your identity providers.
• Block 4: two Access applications, each with an Allow policy listing the emails.
• Block 5: the build ends with “Complete!”, then wrangler uploads the files and says the deployment is complete, with a deployment address.
• Block 6: the private window shows the sign-in page first; the code arrives within a minute and opens the docs.

Check

curl -sI "https://<DOCS_URL>" | head -n 5

A redirect (302) whose location is your team's cloudflareaccess.com sign-in page, never a 200 with the docs.

pnpm dlx wrangler@4.148.0 pages deployment list --project-name opleet-docs

One production deployment, from branch main.

If it fails

• Block 6 or the check shows the docs without a sign-in: the site is public. Stop, run the Undo commands now, and paste what you saw into a CTO session and into #25.
• Block 4 has no Enable access policy: Zero Trust isn't set up yet. Run block 3 first.
• A reviewer gets no code: their email isn't in both policies, or it went to spam. The code expires after 10 minutes; they can ask for a new one.
• Block 5 says the project doesn't exist: block 2 printed another name. Use it in --project-name.
• Block 5's build fails: paste the end of the build output into a CTO session. main builds in CI, so it is likely the local install; run pnpm install --frozen-lockfile again.

Undo

pnpm dlx wrangler@4.148.0 pages project delete opleet-docs --yes

Then delete the two Access applications in Zero Trust › Access › Applications.

Runs

Log each run as a comment on #25.