Self-hosting

A self-hosted installation is one app container and one PostgreSQL database. It serves exactly one Workspace with unlimited Products and agents. It never requires Stripe, the hosted API or external telemetry. This page summarises the installation guide. The full guide on GitHub is canonical.

Quick start#

git clone https://github.com/pietervw/supportseal.git
cd supportseal
cp .env.example .env        # then edit (see the reference below)
docker compose up -d

Open http://<host>:3000. On a fresh installation the root page redirects to /register, and the first account becomes the Workspace Admin. Once the Workspace exists, public registration closes automatically. Further users are invited from Settings → Team. A teammate with no account cannot yet join that way. See issue 180.

The three services#

docker compose up starts three services.

Environment reference#

Copy .env.example to .env and fill in at least the required values. Stripe variables are for hosted mode only and are never needed here.

Email setup#

Email needs an inbound path and an outbound provider. The widget works without either.

Inbound mail#

1. Find the generated address

   Open Settings → Products → your Product → Email. It shows the generated inbound address, product_xxx@your-inbound-domain.

2. Forward your support address

   With your mail provider, forward [email protected] to that address.

3. Point the webhook at the app

   Point your provider's webhook or forwarder at https://<your-host>/api/email/inbound with the header x-supportseal-inbound-secret: <INBOUND_WEBHOOK_SECRET>. If your provider cannot set headers, embed ?secret= in the destination URL instead.

A Product can also own a custom mail domain. Set INBOUND_MX_HOSTS to the host or hosts your inbound provider listens on. Your mail provider must also accept the domain, for example as an Inbound Parse hostname. Verification proves the customer's DNS, not your provider configuration.

Outbound mail#

Configure one outbound provider, either SMTP_URL or a SendGrid API key. Agent replies are then delivered from a sender named after the Product, such as "Acme Support" <no-reply@…>, with a reply-to that threads back into the same Conversation. Without a provider, replies are recorded but not delivered.

SendGrid#

SendGrid can replace the webhook and the outbound steps. Mail to [email protected] still needs forwarding to your Product's inbound address. Alternatively, point your product domain's MX at mx.sendgrid.net and use it as INBOUND_EMAIL_DOMAIN.

• Inbound. Add an Inbound Parse hostname in SendGrid. It must be the same domain as INBOUND_EMAIL_DOMAIN. Create the MX record SendGrid shows you. Set the destination URL to https://<your-host>/api/email/inbound?secret=<INBOUND_WEBHOOK_SECRET>. Use a URL-safe secret, or percent-encode it.
• Outbound. Set SENDGRID_API_KEY with the Mail Send scope only. Authenticate the sending domain in SendGrid, or verify the no-reply@… address (OUTBOUND_EMAIL_LOCAL) as a single sender. When both SENDGRID_API_KEY and SMTP_URL are set, SendGrid wins.

HTTPS and reverse proxy#

Terminate TLS in front of the app with Caddy, Traefik, nginx or similar. Three requirements apply.

• Do not buffer server-sent events. The app already sends X-Accel-Buffering: no, which was sufficient through a stock nginx configuration. proxy_buffering off; and a raised proxy_read_timeout for /api/ are harmless extra headroom.
• Never gzip text/event-stream. Compressing the event stream at the proxy holds messages back even when buffering is disabled. Exclude text/event-stream from gzip_types in nginx or from the encode matcher in Caddy. The app's 15 second heartbeats keep idle streams alive past default 60 second proxy read timeouts on their own.
• Pass the client headers. Preserve the Host header and pass X-Forwarded-For. The widget's per-IP rate limiter uses it. The limiter also caps how many anonymous chat sessions one IP may start per minute.

Trusted client IP header#

By default the per-IP rate limits read the client IP from the first value of X-Forwarded-For. That is correct behind a plain nginx, Caddy or Traefik setup, where the proxy overwrites the header. Ignoring the header would put every visitor behind the proxy into one shared bucket.

If your origin sits behind a proxy that provides a dedicated client-IP header, such as cf-connecting-ip on Cloudflare, set TRUSTED_PROXY_HEADER=cf-connecting-ip. Only that header is then used, and a spoofed X-Forwarded-For is ignored. Requests missing the header all share one bucket, so a misconfiguration fails closed.

Backups#

• Database. Use standard pg_dump or pg_dumpall on the db service, or a managed snapshot. It holds every Workspace, Product, Conversation, message and the delivery ledger.
• Attachments. Back up the volume mounted at STORAGE_DIR, or your S3-compatible bucket if you swap the storage adapter.

Upgrades#

git pull
docker compose build
docker compose run --rm migrate   # applies pending prisma migrations
docker compose up -d

The migrate step is idempotent. Check GET /api/health after upgrading.

Security notes#

• Keep BETTER_AUTH_SECRET and INBOUND_WEBHOOK_SECRET secret. Rotate one by setting a new value and restarting. Sessions are invalidated, and widgets re-issue visitor cookies automatically.
• The widget key in the embed snippet is public by design. It only works on the domains you allowlisted for that Product.
• Registration closes itself once the Workspace exists. Users join by invitation only.
• Attachments are validated by type sniffing and size caps, and are served with nosniff and authorized access only.

Uninstall#

docker compose down -v removes containers, the network and volumes. That deletes all data.

The full guide#

The GitHub guide also covers the maintenance script that purges stale anonymous chat visitors, and other details this page leaves out. Read docs/self-hosting.md on GitHub (opens on GitHub) for the canonical text.