Configuration
Every environment variable and binding Rebutdesk reads, what it does, its default and which runtime uses it.
Rebutdesk is configured with environment variables. With Docker they come from .env (see Run with Docker); on Cloudflare Workers they are secrets or vars (see Run on Cloudflare Workers). “Both” in the tables means the Node runtime (Docker included) and Workers.
Settings that belong to one workspace, such as payment accounts, the AI model, chat widgets and mailboxes, are set in the console, not here.
Required
| Variable | Runtime | Default | What it does |
|---|---|---|---|
DATABASE_URL |
Both | none | PostgreSQL connection string. On Workers the HYPERDRIVE binding is used instead when present. The Node server exits at start without it. |
BETTER_AUTH_SECRET |
Both | none | Signs sessions, encrypts stored Stripe, PayPal and AI keys, and signs chat visitor tokens. Must be at least 32 characters, else the API answers 503 auth_not_configured. Do not change it once in use. |
BETTER_AUTH_URL |
Both | none | Public URL of the console, for example https://help.example.com. Used for sign-in callbacks, trusted origins, the passkey host name and the payment webhook URLs. On Node every request URL is built from its origin. The Node server exits at start without it. |
Node server
| Variable | Runtime | Default | What it does |
|---|---|---|---|
PORT |
Node | 8787 |
HTTP port. In compose, PORT is the host port and the container always listens on 8787. |
HOST |
Node | 0.0.0.0 |
Address the HTTP and SMTP servers listen on. |
MIGRATE_ON_START |
Node | on | Set to false to skip creating the database and applying migrations at start. |
MIGRATIONS_DIR |
Node | bundled path | Folder with the SQL migrations. The Docker image sets /app/migrations. |
PUBLIC_DIR |
Node | public next to the server bundle |
Folder with the built console and widget.js. The Docker image sets /app/public. |
NODE_ENV |
Node | unset | The Docker image sets production. |
Docker Compose only
These are read by compose.yaml, not by the app.
| Variable | Default | What it does |
|---|---|---|
POSTGRES_PASSWORD |
none, required | Password of the bundled PostgreSQL user rebutdesk. Compose builds DATABASE_URL from it. |
PORT |
8787 |
Host port mapped to the app’s port 8787. |
SMTP_PUBLISH_PORT |
2525 |
Host port mapped to the app’s SMTP port 2525. Use 25 for a real MX record. |
Sign-in
See Sign-in and security for how these fit together.
| Variable | Runtime | Default | What it does |
|---|---|---|---|
AUTH_PASSWORD |
Both | auto | true or false forces email and password sign-in on or off. When unset, it is on unless an OAuth provider is configured. |
AUTH_EMAIL_OTP |
Both | auto | true or false forces email code sign-in on or off. When unset, it is on once the server can send email, unless an OAuth provider is configured. |
AUTH_PROVIDERS |
Both | all configured | Comma separated OAuth providers to offer, for example github,google. Lets you hold back a provider whose app is not ready for this host yet. |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET |
Both | none | Google OAuth app. Both must be set to offer Google. |
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET |
Both | none | GitHub OAuth app. |
MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET |
Both | none | Microsoft Entra ID app. |
OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET |
Both | none | Client on your own OAuth 2.0 or OIDC server, offered as sso. Also needs OAUTH_DISCOVERY_URL, or all of OAUTH_AUTHORIZATION_URL, OAUTH_TOKEN_URL and OAUTH_USERINFO_URL. |
OAUTH_SCOPES |
Both | openid email profile with discovery, none otherwise |
Space or comma separated scopes. |
OAUTH_REDIRECT_URI |
Both | <BETTER_AUTH_URL>/api/auth/callback/sso |
Callback registered with the server, when it differs. Route it to /api/auth/callback/sso. |
OAUTH_NAME |
Both | SSO |
Button label: “Continue with |
TRUSTED_ORIGINS |
Both | none | Comma separated extra origins allowed to call the API with cookies and to open the console websocket. |
AUTH_LOG_OTP |
Both | unset | true offers email sign-in codes without a mailer and logs them instead of sending them. Local development only. |
MAIL_FROM |
Both | Rebutdesk <no-reply@localhost> |
Sender of sign-in codes and team invitations. Set it to an address your mail provider accepts. |
MAIL_SMTP_URL |
Node | none | Outbound mail through an SMTP relay, for example smtps://user:pass@smtp.example.com:465. |
MAIL_TRANSPORT |
Both | see text | Which configured transport (smtp, ses, cloudflare, cloudflare-binding or resend) sends system mail and replies on channels that have not picked one. When unset: SMTP, SES, Cloudflare, the binding, then Resend. Naming one that is not configured stops the server from starting. See Email. |
AWS_SES_ACCESS_KEY_ID, AWS_SES_SECRET_ACCESS_KEY, AWS_SES_REGION |
Both | none | Outbound mail through the Amazon SES v2 API. Also verifies your support address’s domain so replies come from it. |
AWS_SES_CONFIGURATION_SET |
Both | none | SES configuration set to send with. |
AWS_SES_MAIL_FROM_SUBDOMAIN |
Both | none | Label for a custom MAIL FROM on SES domains, for example bounce. Each domain then gets two optional records (MX and SPF TXT on bounce.<domain>), so SPF aligns with the domain for DMARC. The SES user also needs ses:PutEmailIdentityMailFromAttributes. |
CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_EMAIL_API_TOKEN |
Both | none | Outbound mail through Cloudflare Email Service. The token needs Email Sending: Edit and Zone: Read. Sending domains must be onboarded for Email Sending in that account. Domains on other Cloudflare accounts can bring their own account ID and token instead. |
RESEND_API_KEY |
Both | none | Outbound mail through Resend. Also adds and verifies your support address’s domain in that Resend account. Domains can bring their own key instead. |
SEND_EMAIL (binding) |
Workers | none | A send_email binding to Cloudflare Email Service, so no API token is needed. Sending domains must be onboarded in the Worker’s account. |
See Email.
| Variable | Runtime | Default | What it does |
|---|---|---|---|
INBOUND_EMAIL_DOMAIN |
Both | none | Domain that receives support mail, for example in.example.com. Mailbox addresses are <mailbox>@<this domain>. Without it the console shows no forwarding address. |
SMTP_PORT |
Node | none | Port of the inbound SMTP listener. It only starts when INBOUND_EMAIL_DOMAIN is also set. Compose sets 2525. |
SMTP_TLS_CERT, SMTP_TLS_KEY |
Node | none | Paths to a PEM certificate and key. When both are set, the SMTP listener offers STARTTLS. |
INBOUND_EMAIL_SECRET |
Both | none | Bearer token for POST /api/webhooks/email. When unset, that endpoint answers 404. |
Attachments
Email attachments go to any S3-compatible store. Without the bucket and both keys, attachments are skipped.
| Variable | Runtime | Default | What it does |
|---|---|---|---|
S3_BUCKET |
Both | none | Bucket name. |
S3_ACCESS_KEY_ID |
Both | none | Access key. |
S3_SECRET_ACCESS_KEY |
Both | none | Secret key. |
S3_ENDPOINT |
Both | AWS S3 | API origin for anything that is not AWS, for example https://<account>.r2.cloudflarestorage.com or a MinIO URL. With an endpoint, path-style URLs are used. |
S3_REGION |
Both | auto with an endpoint, else us-east-1 |
Signing region. |
S3_VIRTUAL_HOSTED |
Both | unset | true puts the bucket in the host name (https://<bucket>.<endpoint host>) instead of the path. Needed for Aliyun OSS, for example S3_ENDPOINT=https://oss-cn-hongkong.aliyuncs.com with S3_REGION=oss-cn-hongkong. |
AI
A server-wide model is used by every workspace that has not set its own in the console. See AI.
| Variable | Runtime | Default | What it does |
|---|---|---|---|
AI_BASE_URL |
Both | none | Base URL of an OpenAI-compatible API, ending before /chat/completions, for example https://api.openai.com/v1. |
AI_API_KEY |
Both | none | API key for that endpoint. |
AI_MODEL |
Both | none | Chat model name. All three of AI_BASE_URL, AI_API_KEY and AI_MODEL must be set. |
AI_EMBEDDING_MODEL |
Both | none | Embedding model on the same endpoint. It must return 1024 dimensions. Turns on semantic knowledge search. |
Licenses
| Variable | Runtime | Default | Meaning |
|---|---|---|---|
REBUTDESK_LICENSE_KEY |
Both | none | License keys for Pro and paid plugins, separated by commas. See Pro license. |
LICENSE_SERVER |
Both | https://app.rebutdesk.com |
License service origin. |
Developers and tests
| Variable | Runtime | Default | What it does |
|---|---|---|---|
WEBHOOK_ALLOW_HTTP |
Both | unset | true allows http and local addresses for outgoing webhook endpoints. For development only. |
STRIPE_API_BASE |
Both | https://api.stripe.com |
Overrides the Stripe API host, for mocks. |
STRIPE_FILES_BASE |
Both | https://files.stripe.com |
Overrides the Stripe file upload host. Falls back to STRIPE_API_BASE when only that is set. |
PAYPAL_API_BASE |
Both | live or sandbox host | Overrides the PayPal API host, for mocks. |
TEST_DATABASE_URL |
Tests | none | Database the test suite uses. |
WIDGET_OUT_DIR |
Build | ../api/public |
Where the chat widget build writes widget.js. |
Workers bindings
These are bindings in wrangler.jsonc, not variables.
| Binding | What it does |
|---|---|
HYPERDRIVE |
Hyperdrive configuration for PostgreSQL. Preferred over DATABASE_URL when present. |
REALTIME |
Durable Object namespace of RealtimeHub. Without it the API works but nothing is pushed live. |
Next: Sign-in and security