Skip to content

Cloudflare Pages Deployment

This guide walks through deploying your AI Knowledge Base to Cloudflare Pages with Cloudflare Access protection.

Overview

  • Hosting: Cloudflare Pages (static site hosting)
  • Build: Automated from GitHub repository
  • Access Control: Cloudflare Access (private URL)
  • Domain: Custom domain or *.pages.dev subdomain

Prerequisites

  • GitHub repository with your knowledge base
  • Cloudflare account (free tier is sufficient)
  • Domain managed by Cloudflare (optional, for custom domain)

Step 1: Create GitHub Repository

First, push your local repository to GitHub:

# In your local ai-knowledge-base directory
git remote add origin https://github.com/YOUR-USERNAME/ai-knowledge-base.git
git branch -M main
git push -u origin main

Make sure your repository is: - Private (recommended for internal knowledge base) - Contains all files including requirements.txt, mkdocs.yml, scripts, and data

Step 2: Create Cloudflare Pages Project

Via Cloudflare Dashboard

  1. Log in to Cloudflare Dashboard
  2. Go to Pages in the left sidebar
  3. Click Create a project
  4. Choose Connect to Git
  5. Select your GitHub account and repository
  6. Choose the main branch

Build Configuration

IMPORTANT: Use these exact build settings:

Setting Value
Framework preset None
Build command pip install -r requirements.txt && python scripts/build_index.py && mkdocs build
Build output directory site
Root directory /
Node.js version (leave default)
Environment variables (none needed)

Advanced Settings

Under Advanced: - Build timeout: 10 minutes (default is fine) - Python version: 3.8+ (usually auto-detected)

Click Save and Deploy.

Step 3: Verify Deployment

After the first build completes:

  1. Visit your Pages URL (e.g., https://ai-knowledge-base.pages.dev)
  2. Verify the site loads correctly
  3. Check that all navigation links work
  4. Test the search functionality
  5. Verify data tables display properly

Step 4: Set Up Cloudflare Access

Create an Access Application

  1. In Cloudflare Dashboard, go to Zero Trust → Access → Applications
  2. Click Add an application
  3. Choose Self-hosted
  4. Configure the application:

Application Details: - Application name: AI Knowledge Base - Application domain: Your Pages URL (e.g., ai-knowledge-base.pages.dev) - Application type: Self-hosted web application

Identity providers: - Enable the providers you want (Google, GitHub, email OTP, etc.)

Policies: Create a policy to control access:

  • Policy name: Knowledge Base Access
  • Action: Allow
  • Rules:
  • Include: Emails → Add your email address
  • Require: (optional additional requirements)

Test Access Control

  1. Open a private/incognito browser window
  2. Navigate to your knowledge base URL
  3. You should see the Cloudflare Access login page
  4. Log in with your configured identity provider
  5. Verify you can access the site after authentication

Step 5: Custom Domain (Optional)

To use a custom domain:

Add Custom Domain to Pages

  1. In Pages project settings, go to Custom domains
  2. Click Set up a custom domain
  3. Enter your domain (e.g., kb.yourdomain.com)
  4. Follow the DNS setup instructions

Update Access Application

  1. In Access → Applications, edit your knowledge base app
  2. Update the Application domain to your custom domain
  3. Save the changes

Step 6: Automated Deployments

Cloudflare Pages automatically rebuilds when you push to GitHub:

# Make changes locally
python scripts/update_item.py --entity providers --id openai --set website="https://openai.com"

# Commit and push
git add .
git commit -m "Update OpenAI website URL"
git push origin main

The site will automatically rebuild and deploy within a few minutes.

Environment Variables

If you need environment variables (usually not required for this setup):

  1. Go to Pages project Settings → Environment variables
  2. Add variables for Production environment
  3. Redeploy if needed

Build Troubleshooting

Common Build Failures

Python/pip issues: 

# Build command that handles Python setup better
pip install --upgrade pip && pip install -r requirements.txt && python scripts/build_index.py && mkdocs build

Schema validation failures: - Check that all JSON files validate locally first - Run make validate before pushing

Missing dependencies: - Ensure requirements.txt is complete and accurate - Test build locally: mkdocs build

Path issues: - Use relative paths in scripts - Ensure all referenced files exist in the repository

Build Logs

To debug build issues:

  1. Go to Pages project Deployments tab
  2. Click on the failed deployment
  3. View the build log output
  4. Look for specific error messages

Common errors: - ModuleNotFoundError: Missing dependency in requirements.txt - FileNotFoundError: Script can't find data files - JSONDecodeError: Invalid JSON syntax in data files

Access Control Troubleshooting

Access Issues

If users can't access the site:

  1. Check Access policy: Ensure user's email is in the Allow policy
  2. Verify domain: Make sure Access application domain matches the site URL
  3. Test incognito: Try accessing in a private browser window
  4. Check identity provider: Ensure the user's identity provider is configured

Policy Examples

Team access: 

Include:
- Emails ending in: @yourcompany.com

Require:
- (empty - just the email domain restriction)

Individual access: 

Include:
- Emails: user1@example.com, user2@example.com, user3@example.com

Require:
- (empty - just the specific emails)

MFA required: 

Include:
- Emails ending in: @yourcompany.com

Require:
- Authentication factor: Any MFA

Monitoring and Maintenance

Analytics

Monitor your deployment:

  1. Pages Analytics: Traffic and performance metrics
  2. Access Logs: Who's accessing your knowledge base
  3. Build History: Deployment success/failure rates

Regular Maintenance

  1. Update dependencies: Periodically update requirements.txt
  2. Monitor build times: Watch for performance degradation
  3. Review Access logs: Ensure appropriate access patterns
  4. Test functionality: Regularly verify search and navigation work

Security Considerations

  1. Private repository: Keep your GitHub repository private
  2. Access control: Use Cloudflare Access rather than making the site public
  3. Audit logs: Review Access logs periodically
  4. Principle of least privilege: Only grant access to users who need it
  5. Regular reviews: Periodically review and update access policies

Cost Considerations

Cloudflare Pages

  • Free tier: 500 builds/month, unlimited requests
  • Paid tier: $20/month for more builds and features

Cloudflare Access

  • Free tier: Up to 50 users
  • Paid tier: $3/user/month for additional users and features

For most internal knowledge bases, the free tiers are sufficient.

For content management instructions, see Workflow Guide