Cloudflare Pages Deployment

Step-by-step guide for deploying TradePsykl documentation to Cloudflare Pages with Cloudflare Access authentication.

For hosting strategy and cost overview, see overview.md

---

Current Setup

Project: tradepsykl-docs

URL: Provided in Cloudflare dashboard

Production branch: main

Status: ✅ Active (deployed November 2025)

---

Architecture

Features:

• Search: VitePress local search (client-side, no server required) accessible via Ctrl+K / Cmd+K or the search button in navigation
• Diagrams: Mermaid support for architecture diagrams
• Authentication: Cloudflare Access with GitHub OAuth for org members only

---

Deployment Configuration

Build Settings

Project name: tradepsykl-docs

Production branch: main (or is9/vuepress during initial setup)

Framework preset: VitePress (auto-detected)

Build command:

cd docs && npm ci && npx vitepress build

Build output directory: docs/.vitepress/dist

Root directory: / (repository root)

Environment variables: None required (Node.js 20 auto-detected)

VitePress Configuration

docs/.vitepress/config.ts is configured for Cloudflare deployment:

export default withMermaid({
    base: '/',  // Root deployment (not subpath)
    ignoreDeadLinks: true,  // Allow localhost URLs and .html extensions
    // ... other config
});

Key settings:

• base: '/' — Deploys to root domain, not /trade_psykl/ subpath
• ignoreDeadLinks: true — Prevents build failures from development URLs (localhost) and missing .html extensions

---

Authentication (Cloudflare Access)

Current Configuration

• Identity provider: GitHub OAuth
• Access policy: GitHub organization t4apps members only
• Session duration: 24 hours

Adding New Team Members

1. Invite user to t4apps GitHub organization
2. User accepts GitHub org invite
3. User can immediately access documentation (no additional Cloudflare config needed)

Access Flow

1. User visits documentation URL
2. Cloudflare Access prompts for GitHub authentication
3. User logs in with GitHub account
4. Cloudflare verifies GitHub org membership
5. Access granted (24-hour session)

---

Deployment Workflow

Automatic Deployment

On push to main branch:

1. Cloudflare detects push via GitHub integration
2. Build executes: cd docs && npm ci && npx vitepress build
3. Static files uploaded to CDN (~159 files)
4. Site live in ~30 seconds

Build time: ~27 seconds | Upload time: ~3.5 seconds

Manual Deployment

Cloudflare dashboard → Pages → tradepsykl-docs → Deployments → "Retry deployment"

Preview Deployments

Automatic preview deployments for:

• Pull requests: <pr-number>.<project>.pages.dev
• Non-production branches: <branch>.<project>.pages.dev

Access: Same Cloudflare Access policy (GitHub org members only)

---

Build Troubleshooting

Common Issues

Issue: Build fails with "Cannot find package 'vitepress-plugin-mermaid'"

Cause: Using npx vitepress build without installing project dependencies

Fix: Use npm ci && npx vitepress build in build command

---

Issue: Build fails with "36 dead links found"

Cause: VitePress strict dead link checking fails on localhost URLs and missing .html extensions

Fix: Set ignoreDeadLinks: true in docs/.vitepress/config.ts

---

Issue: Site loads but styles/navigation broken

Cause: Incorrect base path in VitePress config

Fix: Verify base: '/' in docs/.vitepress/config.ts (root deployment, not subpath)

---

Local Testing

Test Build

cd docs
npm ci
npm run docs:build

Expected output: ✓ build complete in 79.21s.

Preview Build

cd docs
npm run docs:preview

Access at http://localhost:4173

---

References

• Hosting overview: overview.md — Strategy, costs, alternatives
• Architecture decision: docs/architecture/04-decisions.md — Hosting rationale
• VitePress config: docs/.vitepress/config.ts — Build configuration
• Cloudflare dashboard: Pages → tradepsykl-docs → Settings