Deploy to Cloudflare Pages

This guide walks you through deploying the Hermes Agent tutorial site to Cloudflare Pages with a custom domain, automatic CI/CD via GitHub Actions, and production optimizations.

Architecture Overview

GitHub Push (main branch)
        │
        ▼
GitHub Actions (CI/CD)
        │
        ▼
pnpm install → astro build → dist/
        │
        ▼
Cloudflare Pages Action
        │
        ▼
Cloudflare CDN (Global)
        │
        ▼
hermes-agents.net

Prerequisites

• A Cloudflare account (free tier works)
• Your domain managed by Cloudflare (or purchase one through Cloudflare)
• GitHub repository with the project code
• Basic familiarity with terminal commands

Step 1: Get Cloudflare API Credentials

1.1 Get API Token

1. Log in to Cloudflare Dashboard
2. Navigate to My Profile → API Tokens
3. Click Create Token
4. Use the Edit Cloudflare Workers template
5. Configure permissions:

Permission	Scope
Account - Cloudflare Pages - Edit	All accounts
Zone - DNS - Edit	All zones
Zone - Zone - Read	All zones

6. Click Continue to summary → Create Token
7. Copy the token — you’ll only see it once

1.2 Get Account ID

1. In Cloudflare Dashboard, click any domain or go to Websites
2. On the right sidebar, find Account ID
3. Copy the 32-character hex string

Step 2: Configure GitHub Secrets

In your GitHub repository, add the two secrets:

1. Go to your repository: https://github.com/bigwei08028/hermes-agent-net
2. Navigate to Settings → Secrets and variables → Actions
3. Click New repository secret and add:

Secret Name	Value
CLOUDFLARE_API_TOKEN	Your API token from Step 1.1
CLOUDFLARE_ACCOUNT_ID	Your Account ID from Step 1.2

Caution

Never commit these values to the repository. Always use GitHub Secrets.

Step 3: Create Cloudflare Pages Project

Option A: Via Dashboard (Recommended First Time)

1. Go to Cloudflare Dashboard → Workers & Pages
2. Click Create → Pages → Connect to Git
3. Select your GitHub repository hermes-agent-net
4. Configure build settings:

Setting	Value
Framework preset	None
Build command	pnpm build
Build output directory	dist
Root directory	/

5. Click Save and Deploy

Note

The first deployment via the dashboard creates the Pages project. After that, GitHub Actions will handle all subsequent deployments.

Option B: Via GitHub Actions (Automatic)

The project already includes .github/workflows/deploy.yml. Once you push to main with the secrets configured, the workflow will:

1. Install Node.js 20 + pnpm 10
2. Run pnpm install --frozen-lockfile
3. Run pnpm build (outputs to dist/)
4. Deploy to Cloudflare Pages using cloudflare/pages-action@v1

The first push will automatically create the Pages project if it doesn’t exist.

Step 4: Configure Custom Domain

4.1 Add Domain in Cloudflare Pages

1. Go to Workers & Pages → select hermes-agents-net
2. Click Custom domains tab
3. Click Set up a custom domain
4. Enter hermes-agents.net
5. Click Continue
6. Select Activate domain (if domain is on Cloudflare) or Enter DNS records manually

4.2 DNS Configuration

If your domain is managed by Cloudflare (recommended), the DNS records are added automatically. If not, add these records at your domain registrar:

Type	Name	Value	Proxy
CNAME	@	hermes-agents-net.pages.dev	Proxied
CNAME	www	hermes-agents-net.pages.dev	Proxied

4.3 Enable HTTPS

Cloudflare automatically provisions a free SSL certificate. No manual configuration needed.

1. Go to SSL/TLS → Overview
2. Set encryption mode to Full (strict) for maximum security
3. Verify the certificate is active under Edge Certificates

Step 5: Verify Deployment

5.1 Check Build Status

# In your GitHub repository
# Go to Actions tab → "Deploy to Cloudflare Pages" workflow

5.2 Verify the Site

# Check if the site is live
curl -I https://hermes-agents.net

# Expected: HTTP/2 200
# Check security headers
curl -I https://hermes-agents.net | grep -i "x-frame\|x-content-type\|referrer"

Expected security headers (configured in public/_headers):

X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin

5.3 Verify Sitemap

curl https://hermes-agents.net/sitemap-index.xml

Step 6: Production Optimizations

6.1 Caching Strategy

The project already includes caching rules in public/_headers:

# Static assets (JS/CSS/images) - 1 year cache
/_astro/*  → Cache-Control: public, max-age=31536000, immutable

# Fonts - 1 year cache
/fonts/*   → Cache-Control: public, max-age=31536000, immutable

# HTML pages - 1 hour cache (for quick updates)
/*.html    → Cache-Control: public, max-age=3600

6.2 Cloudflare Cache Rules

For additional control, configure cache rules in the Cloudflare dashboard:

1. Go to Caching → Cache Rules
2. Create a rule for Pagefind search index:

Field	Value
Expression	URI Path contains "/pagefind/"
Cache TTL	1 hour
Browser TTL	1 hour

6.3 Page Rules (Optional)

Configure in Rules → Page Rules:

URL Pattern	Setting	Value
hermes-agents.net/*	Security Level	Medium
hermes-agents.net/_astro/*	Cache Level	Cache Everything
hermes-agents.net/pagefind/*	Cache Level	Standard

Step 7: Cloudflare Analytics

Enable Web Analytics

1. Go to Web Analytics in Cloudflare Dashboard
2. Click Add a site
3. Enter hermes-agents.net
4. Copy the JavaScript snippet (optional — Cloudflare also supports beacon-less analytics)

Enable Workers Analytics

1. Go to Workers & Pages → your project → Metrics
2. Monitor request counts, error rates, and latency

Understanding the CI/CD Workflow

The .github/workflows/deploy.yml file defines the complete pipeline:

name: Deploy to Cloudflare Pages

on:
  push:
    branches: [main]       # Trigger on push to main
  workflow_dispatch:        # Allow manual trigger

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - Checkout code
      - Setup Node.js 20
      - Install pnpm 10
      - Install dependencies (pnpm install --frozen-lockfile)
      - Build (pnpm build → outputs to dist/)
      - Deploy to Cloudflare Pages (cloudflare/pages-action@v1)

How It Works

1. Trigger: Every push to main branch (or manual trigger)
2. Build: Astro builds static HTML + CSS + JS to dist/
3. Deploy: Cloudflare Pages Action uploads dist/ to Cloudflare’s global CDN
4. Propagation: Changes propagate to all 300+ Cloudflare edge locations within seconds

Build Output Structure

dist/
├── index.html                    # English homepage
├── zh-cn/                        # Chinese version
│   └── index.html
├── getting-started/              # Content pages
├── features/
├── configuration/
├── troubleshooting/
├── _astro/                       # Static assets (hashed for cache busting)
├── pagefind/                     # Search index
├── sitemap-index.xml             # Sitemap
└── robots.txt                    # Crawler rules

Troubleshooting

Build Fails on GitHub Actions

# Check the workflow logs in GitHub Actions tab
# Common causes:
# 1. pnpm version mismatch → update pnpm/action-setup version
# 2. Node.js version → ensure Node 20
# 3. Dependency conflicts → run pnpm install locally first

Deployment Succeeds but Site Shows 404

1. Check the Pages project name matches projectName in the workflow
2. Verify the directory is set to dist (not dist/)
3. Check Cloudflare Pages dashboard for deployment history

Custom Domain Not Working

# Check DNS propagation
dig hermes-agents.net

# Check SSL status
curl -vI https://hermes-agents.net 2>&1 | grep -E "subject|issuer|expire"

# Verify CNAME records
nslookup -type=CNAME hermes-agents.net

Cache Not Updating

1. Go to Caching → Configuration → Purge Everything
2. Or use the API:

curl -X POST "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/purge_cache" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"purge_everything": true}'

Search (Pagefind) Not Working After Deploy

Pagefind builds its index during astro build. If search doesn’t work:

1. Verify dist/pagefind/ exists in the build output
2. Check browser console for Pagefind errors
3. Purge Cloudflare cache for the /pagefind/ path

Cost Summary

Service	Cost	Notes
Cloudflare Pages	Free	Unlimited sites, 500 builds/month
Custom Domain	Free	If managed by Cloudflare
SSL Certificate	Free	Auto-provisioned
Cloudflare CDN	Free	Global edge network
Web Analytics	Free	Up to 100K requests/day
GitHub Actions	Free	2000 minutes/month (free tier)

Total cost: $0/month for a typical documentation site.

Next Steps

After deployment is working:

• Submit sitemap to Google Search Console
• Submit sitemap to Bing Webmaster Tools
• Set up Cloudflare Web Analytics
• Configure Cloudflare Email Routing (optional)