Self-Hosting

Prerequisites

• Node.js 18+ and pnpm
• A Convex account (free tier available)
• A Vercel account (or any Node.js hosting)
• A Meta Business App with WhatsApp Cloud API access

1. Clone and install

git clone https://github.com/NicolaiSchmid/pons.git
cd pons
pnpm install

2. Set up Convex

# Start Convex dev (opens browser for auth on first run)
npx convex dev

This will create a new Convex project and deploy the schema. Note the deployment URL.

3. Configure environment

Create .env.local:

BETTER_AUTH_SECRET=<generate with: openssl rand -base64 32>
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site

Also set BETTER_AUTH_SECRET in your deployment environment.

4. Configure Facebook Login

1. Go to Meta for Developers
2. Create or reuse a Meta app with Facebook Login and WhatsApp permissions
3. Add your app domains and whitelist these exact OAuth redirect URIs:
   • http://localhost:3000/api/auth/callback/facebook
   • https://your-domain.example/api/auth/callback/facebook
4. Set FACEBOOK_APP_ID and FACEBOOK_APP_SECRET in your environment
5. Keep the WhatsApp webhook environment variables configured as usual

5. Run locally

# Terminal 1: Convex dev server
npx convex dev

# Terminal 2: Next.js dev server
pnpm run dev:next

Visit http://localhost:3000 to see the app.

6. Deploy to Vercel

1. Push your fork to GitHub
2. Connect the repo to Vercel
3. Set environment variables:
   • NEXT_PUBLIC_CONVEX_URL — your Convex deployment URL
   • NEXT_PUBLIC_CONVEX_SITE_URL — your Convex site URL
   • NEXT_PUBLIC_APP_URL — your public app URL
   • BETTER_AUTH_SECRET — shared Better Auth secret
   • FACEBOOK_APP_ID and FACEBOOK_APP_SECRET — Meta login credentials
   • CONVEX_DEPLOY_KEY — from Convex dashboard (Settings > Deploy Key)
4. Build command is pre-configured: pnpm convex deploy --cmd 'pnpm run build'
5. Disable Deployment Protection for production (WhatsApp webhooks need unauthenticated access to /api/webhook)

Region selection

For best latency, deploy Vercel and Convex in the same region. The default Pons setup uses:

• Vercel: FRA1 (Frankfurt)
• Convex: eu-west-1 (Ireland)

Configure this in vercel.json:

{
  "regions": ["fra1"]
}

7. Set up WhatsApp

Follow the WhatsApp Setup guide, replacing pons.chat with your own domain.

Development commands

pnpm dev              # Convex + Next.js in parallel
pnpm run dev:next     # Just Next.js
pnpm run check:write  # Biome lint + format (auto-fix)
pnpm run typecheck    # TypeScript check
pnpm run build        # Production build