Cloudflare Workers deployment

Proxy and Admin are separate Workers sharing one D1 database (binding DB). This is OctaFuse’s default production path—individuals and light traffic can usually deploy and run within the Workers / D1 free tier.

One-command bootstrap (recommended)

git clone https://github.com/OctaFuse/octafuse-gateway.git
cd octafuse-gateway
npm install
npx wrangler login
npm run bootstrap:cloudflare

The script will: create or reuse D1 → remote migrate → deploy Proxy / Admin → put ADMIN_PASSWORD → print downstream GATEWAY_* hints.

Try locally without deploying: Quick start · local.

How to upgrade

For an already-deployed instance, work from the octafuse-gateway repo root. Back up important config first, and read the Upgrade notes in that version’s Release / Changelog.

git pull --ff-only
npm ci

When new D1 migrations land (prefer migrate first, then deploy Workers that depend on the new schema):

npm run deploy:cloudflare -- <instance> --migrate

When there are no schema changes:

npm run deploy:cloudflare -- <instance>

Or update one side only:

npm run deploy:cloudflare -- <instance> --proxy-only
npm run deploy:cloudflare -- <instance> --admin-only

<instance> maps to cloudflare-worker/<instance>.env (for example production). Redeploying Workers does not run D1 migrations. Workers Builds (Connect to Git) also skip migrations—use --migrate or db:migrate:remote when new SQL lands.

Full troubleshooting: gateway Cloudflare quickstart · Upgrades.

Configuration model (deeper)

Layer	Role
`packages/*/wrangler.base.jsonc`	Committed templates (no production `database_id`)
`packages/proxy/wrangler.jsonc`, etc.	Generated (gitignored) by `gen:wrangler`
`cloudflare-worker/example.env`	Dev demo canonical config (committed)
`cloudflare-worker/<instance>.env`	Production/private (gitignored); or Dashboard Build variables only

gen-wrangler reads environment variables (process.env) only.

Other paths

Path	When
Local dev	Laptop + local D1 (Quick start)
Dev demo	Public test `test-api.octafuse.dev` (`example.env` + CLI)
Workers Builds	Connect to Git auto-deploy (D1 migrations still manual)

Returning to local after remote deploys

After deploy:* or db:migrate:remote, generated wrangler.jsonc may include the remote D1_DATABASE_ID. Before local development, run npm run gen:wrangler from a shell without D1_DATABASE_ID exported, then restart dev:proxy / dev:admin.

Workers Builds commands (optional)

Leave Root directory empty (monorepo root). npm ci → postinstall → gen:wrangler.

Worker	Build command	Deploy command
Proxy	`npm ci && npm run gen:wrangler`	`npm run deploy -w @octafuse/proxy`
Admin	`npm ci && npm run gen:wrangler && npm run build:cf -w @octafuse/admin`	`cd packages/admin && npx opennextjs-cloudflare deploy`

Secrets and downstream

ADMIN_PASSWORD: set by bootstrap; or npx wrangler secret put ADMIN_PASSWORD --name <ADMIN_WORKER_NAME>.
Downstream: GATEWAY_URL (Proxy), GATEWAY_MASTER_URL (Admin), GATEWAY_MASTER_KEY (D1 system_config.MASTER_KEY). Rotate if still the seed sk-dev-admin-key.

vs Docker

Default / edge / no server to babysit → this page (Cloudflare).
Data residency, VPC, BYO Postgres/MySQL → Docker.