Cloudflare
Deploy the console on Workers using your existing D1 database and R2 bucket.
Prerequisites
Complete Basics first. This guide uses native D1/R2 bindings.
Copy the Worker example
cp examples/cloudflare/console.config.ts.example console.config.ts
cp examples/cloudflare/wrangler.jsonc wrangler.jsoncBuild the configuration from the Worker's bindings for each request, with
d1Database and r2Storage from @hot-updater/cloudflare/worker. Import
apiKeys, insights, and remoteConfig from
@hot-updater/server/plugins, and set
plugins: [apiKeys(), insights(), remoteConfig()] to match the managed server.
Install these runtime packages:
npm install @hot-updater/cloudflare @hot-updater/serverThen sign in to Wrangler, which the console repository includes:
npx wrangler login
npx wrangler whoamiConnect your resources
Edit the root wrangler.jsonc using your existing OTA backend's values:
| Field | Set to |
|---|---|
name | A new console Worker name |
account_id | Your Cloudflare account ID |
vars.BETTER_AUTH_URL | Your public console HTTPS origin |
vars.BUCKET_NAME | Your existing R2 bucket name |
d1_databases[0] | Your existing D1 database name and ID |
r2_buckets[0].bucket_name | The same R2 bucket name |
The default origin is https://<worker-name>.<account-subdomain>.workers.dev. Register its OAuth callback, or use your custom domain consistently.
To find resource names and IDs:
npx wrangler d1 list
npx wrangler r2 bucket listReuse the existing production resources; no new database or console-specific migration is needed. Local preview uses a separate database that needs initialization below.
Add secrets
Create the ignored .secrets.production.json:
{
"BETTER_AUTH_SECRET": "REPLACE_WITH_RANDOM_SECRET",
"HOT_UPDATER_CONSOLE_ALLOWED_EMAILS": "owner@example.com",
"GITHUB_CLIENT_ID": "REPLACE_WITH_CLIENT_ID",
"GITHUB_CLIENT_SECRET": "REPLACE_WITH_CLIENT_SECRET"
}Fill the values from sign-in setup.
chmod 600 .secrets.production.jsonFor Google, replace the GitHub pair in this file and wrangler.jsonc → secrets.required.
Build and deploy
npm run cf:typegen
npm run test:type
npm run build:cloudflare
npx wrangler deploy --dry-run
npm run test:cloudflare
npx wrangler deploy --secrets-file .secrets.production.jsonWrangler reports the deployed URL. Open it and follow Verify the deployment.
Edit only the root Wrangler config, then rebuild. Deployment uses Nitro's generated config automatically; do not pass the root file with --config.
Local preview
Copy the example and fill in local OAuth credentials, secrets, and BETTER_AUTH_URL=http://localhost:3000:
cp examples/cloudflare/.dev.vars.example .dev.varsnpm run build:cloudflare
npx wrangler d1 execute DB --local --file node_modules/@hot-updater/cloudflare/sql/bundles.sql
npm run preview:cloudflareRun these commands from the console checkout root. The SQL file ships with
@hot-updater/cloudflare and initializes the local DB binding that preview
uses with the tables of core, Insights, API keys, and Remote Config. For a
server with other plugins, apply the migration that
hot-updater db generate writes
for them instead. Repeat initialization if you clear the local Wrangler state.
Register the localhost OAuth callback. Preview uses separate local D1/R2 data by default; it does not copy production bundles or reports. See D1 local development.
Rebuild and deploy with the same commands. Omit --secrets-file to keep existing secrets. For a secret change, run wrangler secret put NAME through your package manager.
npx wrangler deployments list
npx wrangler rollback <previous-version-id>Rollback restores Worker code/configuration, not D1 or R2 data.
| Symptom | Check |
|---|---|
| Bindings unavailable | Build and run the Worker preset, not Vite's Node server |
| Insights missing from the navigation | plugins in console.config.ts includes insights() from @hot-updater/server/plugins |
| Empty Insights | Correct D1 binding; local preview uses separate data |
| Bucket mismatch | BUCKET_NAME, the R2 binding, and stored bundle URI use the same bucket |
| Stale bindings | Edit root config, rebuild, and deploy the generated output |
npx wrangler tailSee Nitro on Cloudflare and Worker secrets.