Publishing the Docs#

The docs you’re reading are published to Cloudflare Pages and gated by Cloudflare Access so only Manex-domain emails can view them.

The pipeline:

Bitbucket push → bitbucket-pipelines.yml → hugo --minify
              → wrangler pages deploy → https://cube2-backend-docs.pages.dev
              (Access enforces auth before the site loads)

Also usable ad-hoc: ./scripts/deploy-docs.sh from your laptop.

First-time setup#

1. Create the Cloudflare Pages project#

• Cloudflare dash → Workers & Pages → Create application → Pages → Upload assets
• Project name: cube2-backend-docs
• Upload any single .html (or a zip with just an index.html) — this initializes the project. All later deploys go via wrangler and target the same project name.
• After it’s created, note the URL: https://cube2-backend-docs.pages.dev.
• Optional: Custom domains tab → add e.g. docs.cube2.manex.com and follow the DNS instructions.

2. Grab the account ID + API token#

• Account ID: visible in the Cloudflare dashboard sidebar. Copy it.
• API token: My Profile → API Tokens → Create Token → use the “Cloudflare Pages: Edit” template → save the token value (shown once).

3. Add secrets to Bitbucket#

Repository settings → Repository variables:

After this, every push to develop triggers a production deploy; every PR gets a preview URL comment.

4. Enable Cloudflare Access (auth gate)#

• dash.cloudflare.com → Zero Trust → the first time you visit you’ll be asked to pick a team domain (e.g. manex.cloudflareaccess.com). Free tier covers up to 50 users.
• Access → Applications → Add an application → Self-hosted.
  • Application name: Cube 2.0 Docs
  • Session duration: 24 h (or whatever suits your team)
  • Application domain: cube2-backend-docs.pages.dev (or your custom domain).
• Configure policies → Add a policy:
  • Policy name: manex-team
  • Action: Allow
  • Include → Emails ending in → @manex.com
• Identity providers: leave the default One-time PIN enabled — Cloudflare emails a 6-digit code to the address. Or hook up Microsoft 365 / Google Workspace / your SSO for click-through login.
• Save.

Verify#

Open the docs URL in a private / incognito window. You should see:

1. Cloudflare’s login page asking for your email.
2. A 6-digit PIN emailed to you.
3. Paste PIN → docs load.

Non-Manex emails get Access Denied. That’s it — a manager can be given a one-line link they’ll authenticate to seamlessly.

Deploying manually#

Set up wrangler once:

npm i -g wrangler
wrangler login          # or export CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID

Then from the repo root:

./scripts/deploy-docs.sh                        # deploy to production
./scripts/deploy-docs.sh --branch=demo-manager  # named preview URL

Or from docs/:

make deploy

Rolling back#

Cloudflare Pages keeps every deploy indefinitely. If something goes wrong:

• Cloudflare dash → your Pages project → Deployments → find the last known-good one → Rollback.
• One click, propagates in seconds.

Removing a user’s access#

Zero Trust → My Team → Users → find them → Revoke sessions. They’re logged out immediately. To keep them out permanently, edit the Access policy to exclude their email.

Costs#

• Cloudflare Pages: free tier is 500 builds/month + unlimited requests + unlimited bandwidth. We won’t come close.
• Cloudflare Access: free for the first 50 users. Beyond that it’s $3/user/mo.
• Custom domain: DNS is free with Cloudflare; SSL is included.