Skip to content
Hybrid GraphRAG Wiki & Architecture

Cloudflare Workers Deployment Guide

Overview

The documentation portal is configured for deployment to Cloudflare Workers using Cloudflare Workers Static Assets. This allows the complete documentation site, including pre-rendered static HTML, CSS, JavaScript, and Pagefind search indices, to be distributed globally across Cloudflare edge data centers with minimal latency.

Prerequisites

  1. Cloudflare Account: A registered account on Cloudflare.
  2. Node.js: Node.js v20+ and npm installed locally.
  3. Wrangler CLI: Installed in the project (wrangler devDependency in wiki/package.json).

Configuration Architecture

The deployment is managed by wrangler.jsonc located in the /wiki directory:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "hybrid-rag-wiki",
  "compatibility_date": "2026-09-06",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page",
    "html_handling": "auto-trailing-slash"
  }
}

Configuration Options Explained

  • name: Identifies the Worker application name in your Cloudflare dashboard (hybrid-rag-wiki).
  • compatibility_date: Specifies the Cloudflare Workers runtime compatibility baseline.
  • assets.directory: Points to the compiled production output (./dist) containing all static HTML pages and Pagefind assets.
  • assets.not_found_handling: Routes missing paths to the custom Astro 404 page (404-page).
  • assets.html_handling: Normalizes routing behavior by enforcing consistent trailing slashes matching Starlight URL resolution.

Authentication & Credentials

Before deploying, authenticate Wrangler with your Cloudflare account. You can choose between interactive login or environment variables for CI/CD pipelines:

Method 1: Interactive OAuth Login (Local Development)

Run the following command from the wiki/ directory:

Terminal window
npx wrangler login

A browser window will open requesting authorization to link Wrangler with your Cloudflare account.

Method 2: API Token (CI/CD and Headless Environments)

Set the CLOUDFLARE_API_TOKEN environment variable in your terminal or deployment pipeline:

Terminal window
export CLOUDFLARE_API_TOKEN="your_api_token_here"
export CLOUDFLARE_ACCOUNT_ID="your_account_id_here"

Deployment Commands

1. Build and Deploy in a Single Step

You can run the dedicated npm script configured in package.json:

Terminal window
cd wiki
npm run deploy

This script executes astro build to compile all documentation pages, generates the Pagefind search bundle, and triggers wrangler deploy.

2. Manual CLI Invocation

Alternatively, run the steps explicitly:

Terminal window
cd wiki


# Step 1: Compile the Astro static site
npm run build


# Step 2: Deploy static assets to Cloudflare Workers
npx wrangler deploy

3. Dry-Run Verification

To verify asset indexing and manifest composition without publishing to Cloudflare:

Terminal window
cd wiki
npx wrangler deploy --dry-run

Expected output:

⛅️ wrangler 4.129.0
────────────────────
✨ Read 143 files from the assets directory /home/d3lee/my-repos/hybrid-graphrag/wiki/dist
Total Upload: 0.31 KiB / gzip: 0.22 KiB
No bindings found.
--dry-run: exiting now.

Local Edge Preview

To test how your site will serve on the Cloudflare Workers runtime locally before deploying:

Terminal window
cd wiki
npm run preview:worker
# or
npx wrangler dev

Wrangler will boot a local Workers simulator (workerd) serving the compiled assets from ./dist.

Custom Domain Configuration

To map your deployed Worker to a custom domain (e.g., wiki.yourdomain.com):

  1. Navigate to Workers & Pages in the Cloudflare Dashboard.
  2. Select hybrid-rag-wiki.
  3. Go to Settings > Domains & Routes.
  4. Click Add > Custom Domain and enter your desired fully qualified domain name.