Cloudflare Pages Deployment Setup

This document describes how to deploy the MkDocs documentation site to Cloudflare Pages.

Architecture

The deployment uses GitHub Actions with the cloudflare/wrangler-action to build the MkDocs site and push it to Cloudflare Pages via direct upload. This avoids needing Cloudflare's Git integration and gives full control over the build process.

Workflow file: .github/workflows/deploy-cloudflare.yml

push to master → GitHub Actions → pip install + mkdocs build → wrangler pages deploy → Cloudflare Pages

Prerequisites

1. A Cloudflare account (free tier is sufficient)
2. The GitHub repo marcoteodoro/progress-migration-docs (private, master branch)

Step 1: Create Cloudflare API Token

1. Go to https://dash.cloudflare.com/profile/api-tokens
2. Click Create Token
3. Use the Custom token template
4. Configure permissions:
   • Account > Cloudflare Pages > Edit
5. Account Resources: Include > select your account
6. Click Continue to summary > Create Token
7. Copy the token (you won't see it again)

Step 2: Get Your Cloudflare Account ID

1. Go to https://dash.cloudflare.com
2. Click on any domain (or the account overview)
3. The Account ID is visible in the right sidebar, or in the URL: https://dash.cloudflare.com/<ACCOUNT_ID>/...
4. Copy the Account ID (a 32-character hex string)

Step 3: Add GitHub Secrets

1. Go to https://github.com/marcoteodoro/progress-migration-docs/settings/secrets/actions
2. Click New repository secret and add:
   • Name: CLOUDFLARE_API_TOKEN / Value: the token from Step 1
   • Name: CLOUDFLARE_ACCOUNT_ID / Value: the account ID from Step 2

Step 4: Create the Cloudflare Pages Project

The first deployment will auto-create the project. Alternatively, create it manually:

Option A: Auto-create (recommended)

Just push to master. The GitHub Action will run and create the progress-migration-docs project automatically on first deploy.

Option B: Manual creation via Cloudflare Dashboard

1. Go to https://dash.cloudflare.com > Workers & Pages > Create
2. Select the Pages tab
3. Click Upload assets (NOT "Connect to Git" -- we use GitHub Actions for builds)
4. Project name: progress-migration-docs
5. Upload any placeholder file, then the GitHub Action will overwrite it on next push

Option C: Manual creation via CLI

npx wrangler pages project create progress-migration-docs --production-branch master

Step 5: Verify Deployment

After pushing to master with the secrets configured:

1. Check the GitHub Actions tab: https://github.com/marcoteodoro/progress-migration-docs/actions
2. The "Deploy MkDocs to Cloudflare Pages" workflow should run successfully
3. The site will be available at: https://progress-migration-docs.pages.dev

Custom Domain (Optional)

To use a custom domain like docs.progresscu.ie:

1. Go to Cloudflare Dashboard > Workers & Pages > progress-migration-docs > Custom domains
2. Click Set up a custom domain
3. Enter your domain (e.g., docs.progresscu.ie)
4. Cloudflare will configure the DNS automatically if the domain is on Cloudflare

Access Protection (Optional but Recommended)

Since this is internal documentation for a private project, you should restrict access.

Option A: Cloudflare Access (Zero Trust) -- Recommended

1. Go to https://one.dash.cloudflare.com (Zero Trust dashboard)
2. Navigate to Access > Applications > Add an application
3. Select Self-hosted
4. Configure:
   • Application name: Progress Migration Docs
   • Session duration: 24 hours
   • Application domain: progress-migration-docs.pages.dev (or your custom domain)
5. Add a policy:
   • Policy name: Allowed Users
   • Action: Allow
   • Include rule: Emails -- add authorized email addresses
6. This will show a Cloudflare login page before allowing access to the docs

Option B: Simple Password via _headers File

Create a file at migration-review/_headers (this gets copied to _site/_headers during build):

/*
  X-Robots-Tag: noindex

Note: Cloudflare Pages does not support native basic auth. Use Cloudflare Access (Option A) for real authentication, or add X-Robots-Tag: noindex to at least prevent search engine indexing.

Deployment URL

Environment	URL
Production	https://progress-migration-docs.pages.dev
Preview (non-master branches)	https://<branch>.progress-migration-docs.pages.dev
Custom domain (if configured)	https://docs.progresscu.ie (example)

Troubleshooting

"Authentication error" in GitHub Actions

• Verify CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets are set correctly
• Verify the API token has Cloudflare Pages: Edit permission
• Tokens expire if you set an expiry -- check token validity

"Project not found" error

• The project auto-creates on first deploy. If it fails, create it manually (see Step 4 Option B or C)
• Project name must match exactly: progress-migration-docs

Build fails with MkDocs errors

• Check migration-review/requirements.txt has the right dependencies
• The --strict flag in mkdocs build will fail on broken links or warnings -- remove it temporarily to debug

Workflow Reference

The GitHub Actions workflow (.github/workflows/deploy-cloudflare.yml) does:

1. Checks out the repo
2. Sets up Python 3.12
3. Caches pip dependencies
4. Installs mkdocs-material from migration-review/requirements.txt
5. Runs mkdocs build --strict (output to _site/)
6. Uses cloudflare/wrangler-action to deploy _site/ to Cloudflare Pages