Run on Cloudflare Workers
Deploy Rebutdesk as a Cloudflare Worker with Hyperdrive, a Durable Object for live updates, a cron trigger and Email Routing.
On Cloudflare, Rebutdesk runs as one Worker defined in apps/api/wrangler.jsonc. The Worker serves the API, the console as static assets, live updates through a Durable Object, background work from a cron trigger, and inbound mail from Cloudflare Email Routing. You still need a PostgreSQL database reachable from Cloudflare.
What wrangler.jsonc sets up
| Setting | Value | Purpose |
|---|---|---|
main |
src/worker.ts |
The Worker entry. It also exports the RealtimeHub Durable Object class. |
compatibility_flags |
nodejs_compat |
Needed by the PostgreSQL driver and other dependencies. |
assets.directory |
./public |
The built console and chat widget (widget.js). |
assets.not_found_handling |
single-page-application |
Unknown paths get the console’s index.html. |
assets.run_worker_first |
/api/*, /healthz, /webhooks/*, /plugins/* |
These paths go to the Worker instead of the static files. |
triggers.crons |
* * * * * |
Background work every minute. |
durable_objects |
binding REALTIME, class RealtimeHub |
Live push to the console and the chat widget. |
migrations |
tag v1, new_sqlite_classes: ["RealtimeHub"] |
Creates the Durable Object class. |
observability.enabled |
true |
Workers logs. |
hyperdrive |
commented out | Add your Hyperdrive binding here for production. |
There is no binding for email: inbound mail reaches the Worker’s email handler through Email Routing, and attachments go to an S3-compatible bucket configured with secrets.
The cron trigger
Each run does, in order: dispute deadline reminders, overdue promise checks, queued jobs (webhook deliveries and retries, website reading, knowledge extraction, learning from resolved cases and mailbox imports), and embedding updates. Webhook deliveries are also attempted right after the change that caused them, so the cron mainly handles retries. Without the cron trigger, reminders and retries do not happen.
The Durable Object
RealtimeHub holds one hub per workspace for console and chat widget websockets. It uses the hibernation API, so idle sockets do not keep it running. If the REALTIME binding is missing, the API still works but nothing is pushed live.
Database: Hyperdrive or DATABASE_URL
The Worker reads its database from the HYPERDRIVE binding when present, else from the DATABASE_URL secret. Hyperdrive is the recommended setup: the Worker opens one connection per request, and Hyperdrive pools them upstream. Queries are sent without prepared statements, so they also work through Hyperdrive and transaction poolers.
Create a Hyperdrive configuration for your database (see Cloudflare’s Hyperdrive docs) and add the binding to apps/api/wrangler.jsonc:
"hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<your hyperdrive id>" }]
Deploy
1. Install
pnpm install
2. Run the migrations
Migrations are not run by the Worker. Run them from your machine or CI against a direct connection to the database (not the Hyperdrive URL):
DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/rebutdesk pnpm db:migrate
This creates the database if it does not exist and applies every pending migration. It connects to the postgres database first, so the user needs permission for that. If pgvector is available on the server the first time this runs, the knowledge base gets an embedding column for semantic search; see AI. Run it again after each upgrade, before you deploy the new code.
3. Build the console
pnpm --filter @rebutdesk/web build
This writes the console and widget.js into apps/api/public, which is the Worker’s assets directory.
4. Set secrets
Set at least these, from apps/api:
cd apps/api
pnpm exec wrangler secret put BETTER_AUTH_SECRET # 32 or more random characters
pnpm exec wrangler secret put BETTER_AUTH_URL # e.g. https://help.example.com
Add DATABASE_URL as a secret only if you do not use Hyperdrive. Everything else is optional: OAuth apps, S3 attachments, inbound email, server-wide AI. See Configuration for the full list. You can also put non-secret values such as BETTER_AUTH_URL or INBOUND_EMAIL_DOMAIN under vars in wrangler.jsonc.
If BETTER_AUTH_SECRET is missing or shorter than 32 characters, every API call answers 503 with auth_not_configured. If no database is configured, the API answers 503 with database_not_configured.
5. Deploy
cd apps/api
pnpm run deploy
The deploy script runs wrangler deploy. Use pnpm run deploy, because pnpm deploy on its own is a different, built-in pnpm command.
Then open the Worker’s URL (or the custom domain you attached) and create an account.
Inbound email with Email Routing
- Set
INBOUND_EMAIL_DOMAINto the domain that receives support mail, for examplein.example.com. The console builds forwarding addresses from it. - In the Cloudflare dashboard, turn on Email Routing for that domain and route its catch-all address to the Worker (see Cloudflare’s Email Routing docs).
Mail for an unknown or disabled mailbox is rejected back to the sender. The SMTP listener does not exist on Workers, but the HTTP endpoint POST /api/webhooks/email works on both runtimes. See Email.
Attachments
Set S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY and S3_ENDPOINT as secrets. Cloudflare R2 works through its S3 API: use https://<account id>.r2.cloudflarestorage.com as the endpoint. Without these, attachments are skipped and the message text is still filed.
Local development
pnpm install
cp apps/api/.dev.vars.example apps/api/.dev.vars # set DATABASE_URL and BETTER_AUTH_SECRET
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/rebutdesk pnpm db:migrate
pnpm dev # wrangler dev
pnpm db:migrate does not read .dev.vars, so pass DATABASE_URL in the shell. pnpm --filter @rebutdesk/api start:node runs the same app on the Node runtime instead, reading .dev.vars.
Next: Configuration