Cutting over the docs site to a company-owned Cloudflare account#

The Hugo docs are currently deployed under a personal Cloudflare account at cube2-backend-docs.pages.dev. This is the playbook to move it under the company’s Cloudflare account with a company domain (e.g. docs.manex.com) with zero downtime.

The code is already set up so the cutover is a repo-variable change, not a code edit: CLOUDFLARE_PAGES_PROJECT in Bitbucket controls the target project name. deploy-docs.sh reads the same var.

Phase 1 — Ops (company side)#

  1. Cloudflare account — create or use existing for the company
  2. Domain in Cloudflare — pick one:
    • Subdomain-only (recommended first pass): keep existing registrar/DNS; add CNAME docs → <new-project>.pages.dev
    • Full zone: Cloudflare nameservers on manex.com — bigger change, one-time nameserver flip at registrar
  3. API token — Cloudflare dashboard → My Profile → API Tokens → Create Token → template “Edit Cloudflare Workers” or a custom token with scope Cloudflare Pages: Edit on the company account
  4. Copy Account ID — visible in the dashboard sidebar

Ops hands back: API token, Account ID, agreed project name (e.g. manex-cube2-docs), agreed custom domain (e.g. docs.manex.com).

Phase 2 — Bitbucket cutover (zero downtime)#

The old project keeps serving traffic until step 5.

  1. Repo settings → Repository variables — replace with company values:

    • CLOUDFLARE_API_TOKEN (secured) — company token
    • CLOUDFLARE_ACCOUNT_ID — company account ID
    • CLOUDFLARE_PAGES_PROJECT — new project name (e.g. manex-cube2-docs)

  2. First deploy under the new account — trigger a build on the develop branch (or any push). Pipeline calls wrangler pages project create "$CF_PROJECT" which creates the project idempotently, then uploads. Site is live at <new-project>.pages.dev immediately.

  3. Attach the custom domain — Cloudflare dashboard → Pages → new project → Custom domains → add docs.manex.com. Cloudflare shows the CNAME target and auto-issues an SSL cert.

  4. Update DNS at your registrar / DNS provider — add CNAME docs → <new-project>.pages.dev. Propagation is typically minutes.

  5. Re-apply Cloudflare Access (Google SSO gating for @manex.com) under the new account:

    • Zero Trust dashboard → Access → Applications → Add application → Self-hosted
    • Application domain: docs.manex.com
    • Policy: Include → Emails ending in @manex.com
    • Identity provider: Google (or company Google Workspace SSO)
    • Test in an incognito window — expect Google login prompt

Phase 3 — Retire the old (personal) project#

Only after Phase 2 step 5 works end-to-end.

  1. Old Cloudflare account → Pages → cube2-backend-docs → Delete project
  2. Revoke old personal CLOUDFLARE_API_TOKEN
  3. Remove any stale CNAMEs pointing at the old pages.dev URL
  4. (Optional) wrangler logout on your laptop, then wrangler login under the company account

Phase 4 — Update in-repo URLs#

Bulk-replace the old public URL wherever it’s mentioned:

grep -rn 'cube2-backend-docs.pages.dev' docs/ scripts/ README.md
# then bulk-replace to docs.manex.com — one commit, no code change

Places to check:

  • README.md
  • docs/content/docs/** (any href="https://cube2-backend-docs.pages.dev/…")
  • Jira ticket comments — historical, no action needed

Local dev after cutover#

wrangler logout                     # drop personal auth
wrangler login                      # re-auth under company account
export CLOUDFLARE_PAGES_PROJECT=manex-cube2-docs
./scripts/deploy-docs.sh --branch=<any>

Rollback#

If the cutover fails mid-flight (bad token, wrong project name, DNS not propagating):

  1. Revert the three repo variables to the personal-account values
  2. Trigger a pipeline run → old project resumes accepting deploys
  3. Old cube2-backend-docs.pages.dev continues serving traffic uninterrupted

DNS is the only irreversible-in-cache step — TTL should be set low (60s) before step 4 to make rollback fast.

Why this playbook#

Cloudflare has no “transfer project between accounts” primitive. Recreating is the supported path, and because Pages projects are just “point at a build output,” creation cost is near zero. The zero-downtime property comes from serving the two .pages.dev origins in parallel while DNS decides which one traffic reaches.

Backward Running in Docker Architecture Forward