Cloudflare Pages Deployment - Quick Reference¶

For: Developers & DevOps Updated: 2025-10-17

TL;DR¶

Deploy MkDocs documentation to Cloudflare Pages on every push to main.

URL: https://audiolab.pages.dev Workflow: .github/workflows/docs-cloudflare.yml Trigger: Push to main (*.md files), manual, weekly schedule

Quick Checks¶

Is the deployment working?¶

# Check latest workflow run
gh run list --workflow=docs-cloudflare.yml --limit 1

# View live site
curl -I https://audiolab.pages.dev | grep "HTTP"

Trigger manual deployment¶

# Via GitHub CLI
gh workflow run docs-cloudflare.yml

# Via GitHub UI
Actions → Deploy Documentation to Cloudflare Pages → Run workflow

Check build locally¶

cd 03_INFRA/03_11_documentation_platform/03_11_01_user_documentation
mkdocs build --site-dir ../../../../var/docs/user
python -m http.server 8000 --directory ../../../../var/docs/user
# Open http://localhost:8000

Common Issues & Fixes¶

❌ "Artifact not found for name: documentation"¶

Cause: Build job didn't create output files Fix: Check "Build Documentation" job logs for errors

# Look for this step failing:
- name: Verify build output exists
  run: |
    if [ ! -d "var/docs/user" ]; then
      echo "❌ ERROR: Build directory NOT found"
      exit 1
    fi

Solution: Build verification now catches this early

❌ Build succeeds but no HTML files¶

Cause: MkDocs strict: false allows silent failures Fix: Workflow now explicitly checks for HTML files

# This step will fail if no HTML generated:
HTML_COUNT=$(find var/docs/user -name "*.html" | wc -l)
if [ "$HTML_COUNT" -eq 0 ]; then
  exit 1
fi

Solution: Already implemented in workflow

❌ "ERROR: No module named 'mkdocs'"¶

Cause: Python dependencies not installed Fix: Update requirements.txt and clear cache

cd 03_INFRA/03_11_documentation_platform/03_11_01_user_documentation
pip install -r requirements.txt
pip freeze > requirements.txt
git add requirements.txt
git commit -m "chore(docs): update dependencies"

❌ Cloudflare deployment fails with 401¶

Cause: Invalid API token Fix: Regenerate and update secret

# 1. Generate new token in Cloudflare dashboard
# 2. Update GitHub secret
gh secret set CLOUDFLARE_API_TOKEN

# 3. Re-run workflow
gh run rerun <run-id>

⚠️ Many warnings in build log¶

Status: Expected behavior Reason: Repository has missing links (in progress docs) Action: None required (unless blocking deployment)

WARNING - Doc file contains a link 'foo.md', but target not found

Why safe: strict: false allows warnings for work-in-progress docs

Key Commands¶

Local Development¶

# Serve docs locally with auto-reload
cd 03_INFRA/03_11_documentation_platform/03_11_01_user_documentation
mkdocs serve

# Build to exact CI location
mkdocs build --site-dir "$PWD/../../../../var/docs/user"

CI/CD Operations¶

# View recent runs
gh run list --workflow=docs-cloudflare.yml --limit 5

# View specific run
gh run view <run-id>

# Download artifact from run
gh run download <run-id> --name documentation

# Cancel running workflow
gh run cancel <run-id>

Deployment Status¶

# Check if site is live
curl -f https://audiolab.pages.dev >/dev/null && echo "✅ Live" || echo "❌ Down"

# Check last modified
curl -I https://audiolab.pages.dev | grep -i "last-modified"

# Test specific page
curl -f https://audiolab.pages.dev/03_INFRA/index.html

Critical File Locations¶

audio-lab/
├── .github/workflows/
│   └── docs-cloudflare.yml              # ★ Workflow definition
├── 03_INFRA/03_11_documentation_platform/03_11_01_user_documentation/
│   ├── mkdocs.yml                        # ★ MkDocs config
│   ├── requirements.txt                  # ★ Python dependencies
│   ├── docs/                             # Generated during build
│   │   └── index.md                      # Entry point
│   └── scripts/
│       └── gen_nav.py                    # ★ Navigation generator
└── var/docs/user/                        # ★ Build output (gitignored)
    ├── index.html                        # Entry point
    ├── assets/                           # Static files
    └── search/                           # Search index

★ = Critical files (don't modify without understanding impact)

Environment Variables¶

In GitHub Actions¶

Variable	Value	Purpose
`${{ github.workspace }}`	`/home/runner/work/AudioLab/AudioLab`	Root directory
`${{ github.sha }}`	`96038819...`	Commit SHA
`${{ secrets.CLOUDFLARE_API_TOKEN }}`	`***`	Cloudflare auth
`${{ secrets.CLOUDFLARE_ACCOUNT_ID }}`	`***`	Cloudflare account

For Local Testing¶

export SITE_DIR="$PWD/../../../../var/docs/user"
mkdocs build --site-dir "$SITE_DIR"

Workflow Anatomy¶

Push to main (*.md)
    ↓
┌───────────────────────┐
│ Job: Build (67s)      │
├───────────────────────┤
│ • Checkout repo       │
│ • Setup Python        │
│ • Install deps        │
│ • Build docs ★        │  mkdocs build --site-dir /workspace/var/docs/user
│ • Verify output ★     │  Check HTML files exist, exit 1 if not
│ • Upload artifact     │  "documentation" → var/docs/user
└───────────────────────┘
    ↓
┌───────────────────────┐
│ Job: Deploy (90s)     │
├───────────────────────┤
│ • Download artifact   │  "documentation" → dist/
│ • Deploy Cloudflare   │  dist/ → audiolab.pages.dev
│ • Summary            │  Link to deployment
└───────────────────────┘
    ↓
https://audiolab.pages.dev ✅

★ = Critical steps (where problems usually occur)

Debugging Checklist¶

When deployment fails:

□ Check which job failed (Build or Deploy)
□ If Build failed:
  □ Look for "Verify build output exists" step
  □ Check MkDocs build logs for errors
  □ Verify requirements.txt is up-to-date
  □ Test build locally with same command
□ If Deploy failed:
  □ Check artifact was uploaded in Build job
  □ Verify Cloudflare secrets are valid
  □ Check Cloudflare dashboard for issues
□ Check workflow file hasn't been modified
□ Try re-running the workflow

Metrics to Monitor¶

Build Health¶

Build time: Should be ~67s ± 10s
HTML file count: Should be > 100
Total file count: Should be > 400
Warnings: < 50 is good, > 200 investigate

Deployment Health¶

Deploy time: Should be ~90s ± 20s
Artifact size: Should be ~5-10 MB
Success rate: Should be > 95%

Site Health¶

Response time: Should be < 500ms
Availability: Should be > 99.9%
HTTPS: Must be enabled

Emergency Contacts¶

Issue	Contact	Action
Workflow broken	DevOps team	Check workflow file
Cloudflare down	CloudFlare support	Check status.cloudflare.com
Site unreachable	Infrastructure team	Check DNS/CDN
Content incorrect	Documentation team	Check source markdown

Useful Links¶

Live Site: https://audiolab.pages.dev
Workflow: https://github.com/joseewowek/AudioLab/blob/main/.github/workflows/docs-cloudflare.yml
Actions: https://github.com/joseewowek/AudioLab/actions/workflows/docs-cloudflare.yml
Cloudflare Dashboard: https://dash.cloudflare.com/pages
MkDocs Docs: https://www.mkdocs.org
Material Theme: https://squidfunk.github.io/mkdocs-material/

Quick Fixes¶

Reset everything¶

# Clean build
cd 03_INFRA/03_11_documentation_platform/03_11_01_user_documentation
rm -rf ../../../../var/docs/user
mkdocs build --site-dir ../../../../var/docs/user

# Re-run workflow
gh workflow run docs-cloudflare.yml

Force rebuild¶

# Make trivial change to trigger workflow
echo "" >> README.md
git add README.md
git commit -m "docs: trigger rebuild"
git push

Skip CI¶

# Commit without triggering workflow
git commit -m "docs: update content [skip ci]"

For detailed troubleshooting: See CLOUDFLARE_PAGES_TROUBLESHOOTING.md For architecture details: See CLOUDFLARE_PAGES_DESIGN.md