Skip to main content

Deploy docs to Cloudflare Pages

This is the docs site you are reading right now. Hosting it on Cloudflare Pages is free at any traffic level relevant to a docs site (the free tier is 500 builds/month, unlimited bandwidth, unlimited requests).

This guide takes about 10 minutes.

What you need​

  • A GitHub repo containing this docs site (or any other host Cloudflare Pages supports — GitLab works too)
  • A Cloudflare account (free tier is fine)
  • Optional: a custom domain you control (e.g. docs.example.com)

1. Push to GitHub​

If you haven't already:

cd ~/Documents/IdentSphere
git init
git add docs-site
git commit -m "docs: scaffold"
gh repo create IdentSphere --private --source=. --push

2. Connect to Cloudflare Pages​

  1. Sign in at https://dash.cloudflare.com
  2. Workers & Pages → Create application → Pages → Connect to Git
  3. Pick the IdentSphere repo, branch main
  4. Build settings:
FieldValue
Framework presetDocusaurus
Root directorydocs-site
Build commandnpm run build
Build output directorybuild
  1. Click "Save and Deploy".

The first build takes ~2 minutes. Subsequent builds are usually under 30 seconds. Cloudflare will give you a URL like identsphere-abc.pages.dev.

3. Custom domain (optional)​

Pages → Your project → Custom domains → Set up a custom domain.

If your domain is on Cloudflare, it auto-creates the CNAME record. If your domain is elsewhere, Cloudflare gives you a CNAME target like identsphere-abc.pages.dev to paste into your DNS.

HTTPS certificate provisioning is automatic and takes ~5 minutes.

4. Optional: wrangler.toml for repeatable deploys​

Already included in docs-site/wrangler.toml:

name = "identsphere-docs"
compatibility_date = "2024-01-01"
pages_build_output_dir = "build"

This lets you deploy from CI without the dashboard wizard:

npm install -g wrangler
wrangler pages deploy docs-site/build --project-name identsphere-docs

Cost expectations​

For the docs site specifically:

MetricFree tier limitWhere IdentSphere docs sits
Builds500 / monthProbably 10-50
BandwidthUnlimitedDoesn't matter
RequestsUnlimitedDoesn't matter
Custom domainsUnlimited1 or 2
TLSFree, automaticUsed

You will never hit a limit on the free tier for a docs site.

What CloudFlare can NOT host (heads up)​

  • The identsphere-server backend — it's a long-running Rust binary with a Postgres connection. That doesn't fit Cloudflare Workers (which are ephemeral functions). Host the backend on AWS Fargate / GCP Cloud Run / Fly.io / a VPS / your own Kubernetes — anywhere that runs Docker.
  • Postgres — Cloudflare D1 is a SQLite-like edge DB, NOT Postgres. Use Supabase / Neon / Crunchy / RDS / Cloud SQL.

The docs site, frontend hosting, asset CDN, and DNS — yes, all free on Cloudflare.

Production rendering for the docs​

By default Docusaurus builds a fully-static site. No SSR runtime is needed. Cloudflare Pages serves the static assets at the edge, latency is typically <50ms anywhere in the world.

If you want to add interactive components (chat widget, runtime API explorer), Docusaurus supports React components in MDX — render them client-side and they ship as part of the bundle.

See also​