Run with Docker
Run Rebutdesk with Docker Compose or plain Node, behind a TLS proxy, and keep it upgraded and backed up.
The repository ships a Dockerfile and a compose.yaml. Compose starts two services: db (PostgreSQL 17 with pgvector, image pgvector/pgvector:pg17) and app (Rebutdesk on Node 24). The app container serves the console, the API, websockets and background jobs from one process.
Quick start
cp .env.example .env
# Edit .env: set POSTGRES_PASSWORD, BETTER_AUTH_SECRET and BETTER_AUTH_URL
docker compose up -d
Open http://localhost:8787 (or the PORT you set), create an account and then a workspace. Whoever creates a workspace becomes its admin.
Only three values in .env are required:
| Variable | What to put there |
|---|---|
POSTGRES_PASSWORD |
Password for the bundled PostgreSQL. Compose refuses to start without it. |
BETTER_AUTH_SECRET |
At least 32 random characters, for example the output of openssl rand -base64 48. |
BETTER_AUTH_URL |
The public URL people open in the browser, for example https://help.example.com. |
Compose builds DATABASE_URL for the app from POSTGRES_PASSWORD, so you do not set it yourself. Every other line in .env is passed to the app as well; see Configuration for the full list.
BETTER_AUTH_SECRET does more than sign sessions. It also encrypts the Stripe, PayPal and AI keys stored in the database and signs live chat visitor tokens. Keep it safe and do not change it: if it changes, everyone is signed out and stored payment and AI keys can no longer be read, so they must be entered again.
The app exits at start if DATABASE_URL, BETTER_AUTH_SECRET or BETTER_AUTH_URL is missing. If the secret is shorter than 32 characters, the API answers 503 with auth_not_configured.
What happens on start
- The app connects to the
postgresdatabase on the server and creates the Rebutdesk database if it does not exist. - It applies any pending migrations from
/app/migrations. - It starts listening on port 8787 inside the container.
- It starts a timer that runs background work every minute: dispute deadline reminders, overdue promise checks, webhook retries, website reading for the knowledge base and embedding updates.
- If
INBOUND_EMAIL_DOMAINis set, it starts the inbound SMTP listener on port 2525 inside the container. See Email.
Set MIGRATE_ON_START=false to skip steps 1 and 2, for example when you run migrations separately.
The image has a health check that calls GET /healthz. It answers {"ok":true,"database":true} when a database URL is configured.
Ports
| Container port | Host port | Purpose |
|---|---|---|
| 8787 | PORT (default 8787) |
Console, API, webhooks and websockets |
| 2525 | SMTP_PUBLISH_PORT (default 2525) |
Inbound SMTP, only active when INBOUND_EMAIL_DOMAIN is set |
For a real MX record, publish SMTP on port 25: set SMTP_PUBLISH_PORT=25.
Reverse proxy and TLS
The app speaks plain HTTP. For production, put a TLS reverse proxy in front of it and set BETTER_AUTH_URL to the public https:// URL.
Things the proxy must do:
- Proxy websockets. The console opens a websocket at
/api/w/<workspace id>/realtimeand the chat widget at/api/chat/<channel id>/ws. Without websockets the console still works, but new messages do not appear live and the sidebar shows “Offline”. - Keep the browser’s
Originheader. The console websocket only accepts the origin ofBETTER_AUTH_URLand the origins inTRUSTED_ORIGINS. - Send the client IP. Sign-in rate limits use
cf-connecting-iporx-forwarded-for.
The Node server builds every request URL from BETTER_AUTH_URL, so links, cookies and origin checks are correct behind the proxy without forwarding the Host header.
Caddy proxies websockets on its own:
help.example.com {
reverse_proxy 127.0.0.1:8787
}
With nginx, pass the upgrade headers:
server {
listen 443 ssl;
server_name help.example.com;
# ssl_certificate and ssl_certificate_key here
location / {
proxy_pass http://127.0.0.1:8787;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 1h;
client_max_body_size 25m;
}
}
client_max_body_size matters for the .mbox import (up to 20 MB) and the inbound email HTTP endpoint (up to 25 MB).
Run a single app container
Live chat and console sockets are held in the app process. If you start several app containers, a message handled by one container is not pushed to sockets connected to another. Run one app container.
Prebuilt images
Images for linux/amd64 and linux/arm64 are published on Docker Hub as rebutdesk/rebutdesk:
:latestand:X.Y.Z(also:X.Y) for releases:edgefor the main branch
To use one instead of building, replace build: . with the image in compose.yaml:
app:
image: rebutdesk/rebutdesk:latest
Run without Compose
Build the image and point it at any PostgreSQL server:
docker build -t rebutdesk .
docker run -d --name rebutdesk -p 8787:8787 \
-e DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/rebutdesk \
-e BETTER_AUTH_SECRET=YOUR_SECRET \
-e BETTER_AUTH_URL=https://help.example.com \
rebutdesk
pgvector is optional. When the vector extension is available on the server the first time migrations run, Rebutdesk creates the extension and an embedding column and uses semantic search in the knowledge base. Without it, knowledge search uses full-text search only. The migration only checks once: if you install pgvector later, the column is not added.
The database user needs permission to connect to the postgres database, and to create the Rebutdesk database if it does not exist yet. If your provider does not allow that, create the database yourself, run the migrations with another tool or user, and set MIGRATE_ON_START=false.
Run on Node without Docker
This is what the Dockerfile does. You need Node 24 and pnpm.
pnpm install
pnpm --filter @rebutdesk/web build # console and chat widget into apps/api/public
pnpm --filter @rebutdesk/api bundle:node # one file: apps/api/dist/server.mjs
DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/rebutdesk \
BETTER_AUTH_SECRET=YOUR_SECRET \
BETTER_AUTH_URL=https://help.example.com \
MIGRATIONS_DIR=packages/db/migrations \
NODE_ENV=production \
node apps/api/dist/server.mjs
Set MIGRATIONS_DIR when you run the bundle from the repository, because the bundled default location does not exist there. PUBLIC_DIR defaults to apps/api/public next to the bundle. The server listens on PORT (default 8787) on HOST (default 0.0.0.0).
Upgrading
Migrations run on start, so an upgrade is a new image and a restart.
With a prebuilt image:
docker compose pull
docker compose up -d
When you build from source, update your checkout and rebuild:
docker compose up -d --build
Migrations only go forward. Back up the database before you upgrade.
Backups
Everything Rebutdesk stores is in PostgreSQL, except email attachments, which go to your S3-compatible bucket when one is configured. Back up three things:
- The database.
BETTER_AUTH_SECRET: a database backup without the same secret cannot decrypt the stored payment and AI keys.- The attachment bucket, if you use one, with your storage provider’s own tools.
With compose, dump the database like this:
docker compose exec -T db pg_dump -U rebutdesk rebutdesk > rebutdesk.sql
To restore into an empty database:
docker compose exec -T db psql -U rebutdesk rebutdesk < rebutdesk.sql
The database lives in the db Docker volume. docker compose down keeps it; docker compose down -v deletes it.