Skip to content

Docs Infrastructure Setup Guide

Step-by-step guide to set up docs deployment infrastructure.

Prerequisites

  • Cloudflare API token with Pages, Access, and DNS permissions
  • GCP project: clearlyops
  • gcloud CLI installed and authenticated
  • jq installed (for JSON parsing)

Step 1: Discover Configuration

Run the discovery script to find all required values:

export CLOUDFLARE_DOCS_API_TOKEN='your-token-here'
./scripts/discover-docs-config.sh

This will output: - Cloudflare Account ID - Cloudflare Zone ID - GCP project details - Existing resource status

Step 2: Set Up GCP Resources

Create Workload Identity, Service Account, and Secret:

# Set your token (if not already set)
export CLOUDFLARE_DOCS_API_TOKEN='your-token-here'

# Dry-run first to see what will be created
./scripts/setup-docs-gcp.sh --dry-run

# Apply changes
./scripts/setup-docs-gcp.sh

This creates: - Workload Identity Pool (github-pool) - Workload Identity Provider (github-provider) - Service Account ([email protected]) - Secret (cloudflare-pages-api-token) with your token value - IAM bindings for GitHub Actions access

Step 3: Update Configuration File

Edit deploy/infra/docs.toml with discovered values:

[gcp]
project_id = "clearlyops"
secret_cloudflare_api_token = "cloudflare-pages-api-token"
workload_identity_provider = "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider"
service_account_email = "[email protected]"

[cloudflare]
account_id = "your-account-id"  # From discovery
zone_id = "your-zone-id"         # From discovery

[access]
allowed_emails = ["[email protected]"]  # Your Google Workspace email

Production Branch Note

Docs deploy from the production branch configured in Cloudflare Pages. For this setup, use:

[docs.public]
production_branch = "integration"

[docs.internal]
production_branch = "integration"

Step 4: Set GitHub Repository Variables

Go to GitHub → Settings → Secrets and variables → Actions → Variables tab.

Add these variables (not secrets):

Variable Value
CLOUDFLARE_ACCOUNT_ID From discovery output
GCP_PROJECT_ID clearlyops
GCP_WORKLOAD_IDENTITY_PROVIDER Full resource name from discovery
GCP_SERVICE_ACCOUNT [email protected]

Step 5: Test Infrastructure Setup

Test the configuration:

./scripts/test-docs-setup.sh

This validates: - Configuration file completeness - GCP authentication - Secret existence - Infrastructure tool functionality

Step 6: Plan Infrastructure Changes

Preview what will be created:

python scripts/setup_docs_infra.py plan --config deploy/infra/docs.toml

Review the output to ensure it matches expectations.

Step 7: Apply Infrastructure

Create the Cloudflare resources:

python scripts/setup_docs_infra.py apply \
  --config deploy/infra/docs.toml \
  --confirm docs-internal.clearlyops.com

This creates: - Two Cloudflare Pages projects (public + internal) - Custom domains attached to projects - DNS CNAME records - Cloudflare Access application for internal docs

Step 8: Verify Deployment

After pushing to integration or main:

  1. Check GitHub Actions workflow runs successfully
  2. Visit https://docs.clearlyops.com (should be public)
  3. Visit https://docs-internal.clearlyops.com (should require Cloudflare Access login)
  4. Verify *.pages.dev URLs are also protected (for internal project)

Troubleshooting

Discovery script fails

  • Verify CLOUDFLARE_DOCS_API_TOKEN is set and valid
  • Check token has required permissions (Pages, Access, DNS)
  • Ensure jq is installed: brew install jq

GCP setup fails

  • Verify gcloud auth login completed
  • Check project is set: gcloud config set project clearlyops
  • Ensure you have IAM admin permissions

Infrastructure plan fails

  • Check all values in deploy/infra/docs.toml are filled
  • Verify Cloudflare token can be fetched from GCP Secret Manager
  • Test token manually: gcloud secrets versions access latest --secret=cloudflare-pages-api-token --project=clearlyops

GitHub Actions deploy fails

  • Verify all repository variables are set
  • Check Workload Identity binding includes your repository
  • Review workflow logs for specific error messages

Quick Reference

# Discover all config
export CLOUDFLARE_DOCS_API_TOKEN='token'
./scripts/discover-docs-config.sh

# Set up GCP
./scripts/setup-docs-gcp.sh

# Test setup
./scripts/test-docs-setup.sh

# Plan changes
python scripts/setup_docs_infra.py plan

# Apply changes
python scripts/setup_docs_infra.py apply --confirm docs-internal.clearlyops.com