Skip to content
Convertella Handbook

Handbook (docs.convertella.app)

The Convertella handbook is a static Starlight site deployed to Cloudflare Pages at:

URLPurpose
https://docs.convertella.appHandbook (Cloudflare Pages, zone convertella.app)

docs.convertella.app and convertella-handbook.pages.dev are Access-protected (see Cloudflare Access). The site root redirects to /getting-started/overview/. Only allow-listed operator emails and approved Access service tokens can read the site.

Deploy

Section titled “Deploy”

From the handbook/ repository:

Terminal window
npm ci
npm run setup:hostname   # CNAME docs → convertella-handbook.pages.dev + Pages custom domain
npm run deploy

Or npm run deploy:full (hostname setup + deploy).

setup:hostname reads CLOUDFLARE_* from ../platform/.env when unset locally. It runs scripts/ensure-docs-hostname.mjs.

This runs astro build and wrangler pages deploy to the Pages project convertella-handbook.

Prerequisites:

  • CLOUDFLARE_API_TOKEN with Cloudflare Pages — Edit and Zone — DNS — Edit
  • CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_ZONE_ID (zone convertella.app)
  • Custom domain docs.convertella.app on the Pages project (script creates CNAME if missing)

Access for humans

Section titled “Access for humans”

Operators sign in through the Cloudflare Access login page (Google/email OTP + MFA per team settings). Allowed emails are managed by the platform script scripts/cloudflare-access-zero-trust.mjs (see Cloudflare Access).

Access for automation (AI / support tooling)

Section titled “Access for automation (AI / support tooling)”

Use a Cloudflare Access service token — not a bypass of Access. The client sends two headers on every request:

CF-Access-Client-Id: <client-id>
CF-Access-Client-Secret: <client-secret>

Example:

Terminal window
curl -sS \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET" \
  "https://docs.convertella.app/getting-started/overview/"

Create or rotate tokens with:

Terminal window
cd platform
node --env-file=.env scripts/cloudflare-access-zero-trust.mjs --create-docs-service-token

Credentials are written only to platform/.deploy-state/docs-access-service-token.json (gitignored). Do not paste service token secrets into this handbook or commit them to git.

For MCP or ticket-reply agents, store the client id/secret in your team secret manager and inject them as environment variables in the agent runtime.

What must not appear in the handbook

Section titled “What must not appear in the handbook”

This site is for architecture and runbooks, not secret storage:

  • No live DATABASE_URL, API keys, AUTH_SECRET, R2 keys, or WhatsApp/Meta tokens
  • No production connection strings — use placeholders like postgresql://USER:REDACTED@ep-xxx.neon.tech/DB
  • The only Access-related values documented here are header names and rotation procedures, not live CF-Access-Client-Secret values