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

  1. The app connects to the postgres database on the server and creates the Rebutdesk database if it does not exist.
  2. It applies any pending migrations from /app/migrations.
  3. It starts listening on port 8787 inside the container.
  4. 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.
  5. If INBOUND_EMAIL_DOMAIN is 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>/realtime and 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 Origin header. The console websocket only accepts the origin of BETTER_AUTH_URL and the origins in TRUSTED_ORIGINS.
  • Send the client IP. Sign-in rate limits use cf-connecting-ip or x-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:

  • :latest and :X.Y.Z (also :X.Y) for releases
  • :edge for 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.

Next: Run on Cloudflare Workers