Supabase Cloud and Vercel
Install Helpwren with its database in a Supabase project you own and the app on Vercel or any Node host.
Before you start
- Node 26 and pnpm 12 on the machine you install from.
- A Supabase account.
- A Vercel account, or another host that runs Node 26.
- The address your install will use, such as
https://support.example.com.
Create a Supabase project
- At supabase.com/dashboard, create a project. Note the database password you choose.
- When it has finished setting up, open Project Settings → API Keys. Keep the tab open: you
need the Project URL, the publishable key (
sb_publishable_…) and a secret key (sb_secret_…). - Open Connect at the top of the dashboard and copy the Session pooler connection string, with your database password in it. The installer uses it only to apply the migrations.
Run the installer
-
Clone the repository and run the installer:
Terminal git clone https://github.com/Fewerlabs/helpwren.git && cd helpwren pnpm install pnpm helpwren install -
Choose Supabase Cloud when it asks how you will run Helpwren, then give it the values from the previous step.
The installer checks Node, pnpm and the Supabase CLI (a dev dependency, which pnpm install
brings), then:
- writes
apps/web/.env.localwith your answers and a freshCRON_SECRET, readable only by you, and never prints a secret back; - applies the database migrations with
supabase db push. It never loads the demo data unless you say yes, and never resets anything; - with
--access-token(a personal access token), applies the Auth settings in the next step through the Management API. Without it, it lists them for you to set by hand.
To leave the connection string out, the installer can run supabase link instead, which signs
you in to Supabase in the browser.
Run it unattended
For CI or scripts, give everything as flags or environment variables and add --yes:
NEXT_PUBLIC_SUPABASE_URL=https://abcd.supabase.co \
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_... \
SUPABASE_SECRET_KEY=sb_secret_... \
SUPABASE_DB_URL='postgresql://postgres.abcd:PASSWORD@aws-0-eu-west-1.pooler.supabase.com:5432/postgres' \
SUPABASE_ACCESS_TOKEN=sbp_... \
pnpm helpwren install --yes --mode cloud --app-url https://support.example.com| Flag | Environment variable | Value |
|---|---|---|
--mode | HELPWREN_MODE | cloud or docker |
--app-url | NEXT_PUBLIC_APP_URL | The address people will use |
--supabase-url | NEXT_PUBLIC_SUPABASE_URL | The Supabase Project URL |
--publishable-key | NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY | The publishable key |
--secret-key | SUPABASE_SECRET_KEY | A secret key |
--db-url | SUPABASE_DB_URL | The connection string, for the migrations |
--access-token | SUPABASE_ACCESS_TOKEN | A personal access token, to apply the Auth settings |
--demo-data | Loads the demo team, contacts and conversations | |
--overwrite | Replaces values already in the env file, never its secrets | |
--skip-prereqs | Skips the checks for Node, pnpm and Docker | |
--yes | CI | Asks nothing: takes flags, the environment and defaults |
pnpm helpwren --help lists every option.
Configure Auth
Skip this step if you gave the installer --access-token. Otherwise, in the Supabase dashboard:
- Authentication → Sign In / Providers: turn on Allow anonymous sign-ins. Visitors chat as anonymous users; without this the chat cannot start.
- Authentication → Emails → Magic link: set the subject to
Your Helpwren sign-in codeand pastesupabase/templates/sign-in-code.htmlas the body. Team members sign in with the six-digit code it shows. - Authentication → URL Configuration: set the Site URL to your install's address.
Note
Supabase's built-in email reaches only the members of your Supabase organisation, a few times an hour. That is enough for the first admin if you use your own address. To sign in anyone else, set up Authentication → Emails → SMTP Settings (guide).
Deploy the app
Deploy to Vercel
-
Click Deploy. Vercel copies the repository to your Git account and sets the project's Root Directory to
apps/web. -
Connect a Supabase project when Vercel offers the Supabase integration. It fills in
NEXT_PUBLIC_SUPABASE_URL,NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEYandSUPABASE_SECRET_KEY. -
Add the remaining two variables:
Variable Value NEXT_PUBLIC_APP_URLThe address people will use, such as https://support.example.comCRON_SECRETopenssl rand -hex 32, or the one the installer wrote to.env.local -
If you deployed before running the installer, run it now against the same project, then configure Auth. Vercel lists the project's
POSTGRES_URL_NON_POOLINGunder Settings → Environment Variables; it works as--db-url.
Note
The deploy does not touch the database. Without the integration, add all five variables by
hand from apps/web/.env.local. Environment variables
lists every one.
Deploy to another Node host
pnpm build
pnpm --filter @helpwren/web start # serves on port 3000; PORT=8080 to change itGive the host the variables from apps/web/.env.local. NEXT_PUBLIC_ values are written into
the browser's code at build time, so build where those variables are set.
Schedule the jobs
Emails about unread replies and ticket changes, and pushes to phones, are sent by two jobs that
a scheduler must call every minute with CRON_SECRET:
curl -X POST https://support.example.com/api/jobs/email -H "Authorization: Bearer $CRON_SECRET"
curl -X POST https://support.example.com/api/jobs/push -H "Authorization: Bearer $CRON_SECRET"Any scheduler works: the host's cron, a GitHub Actions schedule, an uptime monitor, or the
database itself with pg_cron. Scheduled jobs has the SQL.
Warning
Vercel Cron Jobs call routes with GET, and on the Hobby plan at most once a day. The jobs
accept only POST, so use another scheduler.
Create the first admin
Open https://support.example.com/setup and follow the setup wizard.