Skip to Content
Docs

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

  1. At supabase.com/dashboard, create a project. Note the database password you choose.
  2. 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_…).
  3. 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

  1. Clone the repository and run the installer:

    Terminal
    git clone https://github.com/Fewerlabs/helpwren.git && cd helpwren
    pnpm install
    pnpm helpwren install
  2. 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.local with your answers and a fresh CRON_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:

Terminal
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
FlagEnvironment variableValue
--modeHELPWREN_MODEcloud or docker
--app-urlNEXT_PUBLIC_APP_URLThe address people will use
--supabase-urlNEXT_PUBLIC_SUPABASE_URLThe Supabase Project URL
--publishable-keyNEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEYThe publishable key
--secret-keySUPABASE_SECRET_KEYA secret key
--db-urlSUPABASE_DB_URLThe connection string, for the migrations
--access-tokenSUPABASE_ACCESS_TOKENA personal access token, to apply the Auth settings
--demo-dataLoads the demo team, contacts and conversations
--overwriteReplaces values already in the env file, never its secrets
--skip-prereqsSkips the checks for Node, pnpm and Docker
--yesCIAsks 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:

  1. Authentication → Sign In / Providers: turn on Allow anonymous sign-ins. Visitors chat as anonymous users; without this the chat cannot start.
  2. Authentication → Emails → Magic link: set the subject to Your Helpwren sign-in code and paste supabase/templates/sign-in-code.html as the body. Team members sign in with the six-digit code it shows.
  3. 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

Deploy with Vercel

  1. Click Deploy. Vercel copies the repository to your Git account and sets the project's Root Directory to apps/web.

  2. Connect a Supabase project when Vercel offers the Supabase integration. It fills in NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY and SUPABASE_SECRET_KEY.

  3. Add the remaining two variables:

    VariableValue
    NEXT_PUBLIC_APP_URLThe address people will use, such as https://support.example.com
    CRON_SECRETopenssl rand -hex 32, or the one the installer wrote to .env.local
  4. 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_POOLING under 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

Terminal
pnpm build
pnpm --filter @helpwren/web start          # serves on port 3000; PORT=8080 to change it

Give 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:

Terminal
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.