Cloudflare Pages Deployment

This site is deployed to Cloudflare Pages with Zero Trust authentication.

Architecture

Component Value

URL

docs.domusdigitalis.dev

Platform

Cloudflare Pages

Build Tool

Antora

Authentication

Cloudflare Access (Zero Trust)

Build Configuration

Cloudflare Pages Settings

Setting Value

Build command

./build.sh

Output directory

build/site

Node version

22 (auto-detected)

Environment Variables

Variable Description Location

CF_ANTORA_GIT_TOKEN

GitHub PAT for cloning private repos

Cloudflare Pages → Settings → Environment Variables

Token Requirements

Fine-grained GitHub PAT with:

  • Repository access: All 6 domus-* repos

  • Permissions: Contents (read-only)

Repos requiring access:

  • domus-docs

  • domus-infra-ops

  • domus-ise-linux

  • domus-netapi-docs

  • domus-secrets-ops

  • domus-linux-ops

Build Script

The build.sh script injects the GitHub token into playbook URLs at build time:

#!/bin/bash
set -e

# Check for required token
if [ -z "$CF_ANTORA_GIT_TOKEN" ]; then
    echo "ERROR: CF_ANTORA_GIT_TOKEN environment variable not set"
    exit 1
fi

# Inject token into playbook URLs
sed -i "s|https://github.com/EvanusModestus/|https://${CF_ANTORA_GIT_TOKEN}@github.com/EvanusModestus/|g" antora-playbook.yml

# Run Antora build (--quiet suppresses URL logging)
npx antora --quiet antora-playbook.yml
The --quiet flag prevents token exposure in build logs.

Cloudflare Access

The site is protected by Cloudflare Zero Trust Access.

Configuration

Setting Value

Application name

Domus Docs

Domain

docs.domusdigitalis.dev

Authentication

Email-based

Login Page Branding

Setting Value

Background color

#1a1a1a

Organization name

Domus Digitalis

Header text

(custom message)

Customized at: Zero Trust → Reusable components → Custom pages → Access login page

Deployment Workflow

  1. Make changes to any domus-* repo

  2. Push to GitHub

  3. Cloudflare Pages automatically rebuilds (via deploy hooks)

All content repos have webhooks configured to trigger rebuilds on push.

Deploy Hooks

Deploy hooks enable automatic rebuilds when any content repo is updated.

Architecture

domus-infra-ops   ──┐
domus-ise-linux   ──┼──→ GitHub Webhook ──→ Cloudflare Deploy Hook ──→ Rebuild
domus-netapi-docs ──┤
domus-secrets-ops ──┤
domus-linux-ops   ──┘

Configured Webhooks

Repository Webhook Status

domus-infra-ops

✓ Active

domus-ise-linux

✓ Active

domus-netapi-docs

✓ Active

domus-secrets-ops

✓ Active

domus-linux-ops

✓ Active

Setup (For Reference)

1. Create Deploy Hook in Cloudflare

  1. Cloudflare Dashboard → Pages → domus-docs → Settings → Builds & deployments

  2. Scroll to Deploy hooks

  3. Click Add deploy hook

  4. Name: github-content-repos

  5. Copy the generated URL

2. Add Webhook to GitHub Repos

HOOK_URL="https://api.cloudflare.com/client/v4/pages/webhooks/deploy_hooks/YOUR_HOOK_ID"

for repo in domus-infra-ops domus-ise-linux domus-netapi-docs domus-secrets-ops domus-linux-ops; do
  gh api repos/EvanusModestus/$repo/hooks \
    --method POST \
    -f name=web \
    -f "config[url]=$HOOK_URL" \
    -f "config[content_type]=json" \
    -F "events[]=push" \
    -F active=true
done

3. Verify Webhooks

# List webhooks on a repo
gh api repos/EvanusModestus/domus-infra-ops/hooks --jq '.[] | "ID: \(.id) | Events: \(.events)"'

# Check recent deliveries in GitHub
# Repo → Settings → Webhooks → (click hook) → Recent Deliveries

Troubleshooting

Webhook Not Triggering

  1. Check GitHub → Repo → Settings → Webhooks → Recent Deliveries

  2. Look for failed deliveries (red X)

  3. Verify Cloudflare deploy hook URL is still valid

Manual Rebuild

If webhooks fail, trigger manually:

# Option 1: Empty commit to domus-docs
cd domus-docs && git commit --allow-empty -m "chore: trigger rebuild" && git push

# Option 2: Cloudflare Dashboard
# Pages → domus-docs → Deployments → Retry deployment

Troubleshooting

Token Issues

# Test token locally
dsource d000 dev/app
curl -s -H "Authorization: token $CF_ANTORA_GIT_TOKEN" \
  https://api.github.com/repos/EvanusModestus/domus-infra-ops | head -5

Expected: JSON with repo info. If 401/404, token is invalid or missing permissions.

Broken Symlinks

Content repos must use relative symlinks, not absolute paths:

# Bad (breaks in CI)
/home/user/path/to/file.adoc

# Good (works everywhere)
../../../../../../runbooks/file.adoc

Secrets Management

Token stored in dsec:

dsec edit d000 dev/app

Under # --- Cloudflare Pages --- section.