Docker Compose
Run Helpwren, Supabase's own self-hosting stack and a scheduler together on one server.
deploy/docker/docker-compose.yml includes Supabase's official Compose file
(docs), fetched unchanged at a pinned
release (self-hosted/v0.8.4) into deploy/docker/supabase.
deploy/docker/supabase-overrides.yml adds what
Helpwren needs on top: the sign-in code email, named volumes for the database and uploads, and an
optional test mailbox. A small scheduler container calls the
scheduled jobs every minute.
Before you start
- A Linux server with 4 GB of memory or more. The stack is about a dozen containers and uses about 1.5 GB once running; check Supabase's guide for its current requirements.
- Docker with Compose 2.20 or later, Git, Node 26 and pnpm 12.
- For real use, a domain and an SMTP service for sign-in emails.
Install
-
Clone the repository and run the installer in Docker mode:
Terminal git clone https://github.com/Fewerlabs/helpwren.git && cd helpwren pnpm install pnpm helpwren install --mode docker -
Answer whether to catch sign-in emails in a local test mailbox. Say yes to try Helpwren out; for real use, say no and set
SMTP_HOST,SMTP_PORT,SMTP_USER,SMTP_PASSandSMTP_ADMIN_EMAILindeploy/docker/.envto a real mail service. -
When the installer finishes, open http://localhost:3000/setup and follow the setup wizard.
The installer:
- checks that Docker is running, that Compose is 2.20 or later (for
include), and Git; - fetches Supabase's
docker/folder at the pinned release, with a sparse Git checkout; - writes
deploy/docker/.envfrom Supabase's.env.example, replacing every published example secret with a fresh one (POSTGRES_PASSWORD,JWT_SECRET, the API keys signed with it, the dashboard password and the rest), and adds Helpwren's ownHELPWREN_APP_URLandCRON_SECRET. Values you have already set are kept; - starts the database, applies the migrations through Supabase's pooler, then builds the
Helpwren image and starts everything with
docker compose up --wait.
--no-start writes the files and stops, so you can review .env first. Most of the first run
is Docker pulling Supabase's images, a few gigabytes.
| What | Where |
|---|---|
| Helpwren | http://localhost:3000 (HELPWREN_PORT to change) |
| Supabase API, Studio | http://localhost:8000 (user and password: DASHBOARD_* in .env) |
| Test mailbox | http://localhost:8025, when chosen |
| Database volume | helpwren_db-data; uploads in helpwren_storage-data |
Serve it on a domain
-
Put a reverse proxy with TLS in front of ports 3000 and 8000. Supabase's docs cover Caddy and nginx.
-
Give the installer the public addresses:
Terminal pnpm helpwren install --mode docker \ --app-url https://support.example.com --supabase-url https://api.support.example.com
The app reaches Supabase over the private Docker network (SUPABASE_INTERNAL_URL is
http://kong:8000), so it works whether or not the public address resolves from inside a
container.
Send email from Helpwren
Reply notifications are separate from Supabase Auth's sign-in emails. Set EMAIL_PROVIDER and
HELPWREN_SMTP_URL (or RESEND_API_KEY) in deploy/docker/.env, then run
docker compose up --detach helpwren. See Sending email.
Run the pieces yourself
docker compose config --quiet # check the configuration
docker compose up --detach --build # start or update everything
docker compose logs --follow helpwren schedulerThe image is built from apps/web/Dockerfile: a multi-stage build
on node:26-alpine that ships only Next's standalone server, runs as the unprivileged node
user, and reports its health from /api/health.