Configuration

Reference for all environment variables and optional configuration options.

Environment Variables

All environment variables used by PiggyBack. Set these in your .env.local file or in your hosting provider's dashboard.

Variable	Description	Required	Default
NEXT_PUBLIC_SUPABASE_URL	Your Supabase project URL	Yes	—
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anon/public key	Yes	—
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key (server-side only)	Yes	—
UP_API_ENCRYPTION_KEY	32-character AES encryption key for storing Up Bank tokens	Yes	—
NEXT_PUBLIC_APP_URL	Your deployment URL (used for auth redirects and webhooks)	Recommended	Falls back to VERCEL_URL on Vercel
CRON_SECRET	Secret token for the daily notification cron job	Optional	—
NEXT_PUBLIC_SKIP_LANDING	Skip marketing landing page (useful for personal deployments)	Optional	false

Generate Your Keys

terminal

# Generate a 32-character encryption key
node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"

# Generate a cron secret
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Supabase Auth URLs

You must configure these in your Supabase dashboard under Authentication → URL Configuration:

Site URL

Your deployment URL (e.g. https://your-app.vercel.app or http://localhost:3000)

Redirect URLs

Add both of the following:

https://your-app.vercel.app/auth/callback
https://your-app.vercel.app/update-password

Auth will not work without these. Supabase sends users to these URLs after email confirmation and password resets. If they're not configured, login and signup will fail silently.

Cron Jobs

PiggyBack has a daily cron job for payment reminders and AI-generated weekly summaries.

On Vercel (automatic)

Already configured in vercel.json — runs daily at 9am UTC
Requires the CRON_SECRET environment variable
Only runs on production deployments

Self-hosted (manual)

Set CRON_SECRET in your .env.local file, then set up a cron job:

crontab

0 9 * * * curl -H "Authorization: Bearer <your-cron-secret>" http://localhost:3000/api/cron/notifications

AI Assistant

No server-side API keys needed. Each user configures their own provider in Settings → AI.

Supported Providers

Google Gemini — free tier available
OpenAI — requires paid API access
Anthropic — requires paid API access

API keys are encrypted and stored per-user. They never leave the server except to call the provider's API.

Up Bank Webhooks

Cloud Deployments

Webhooks are registered automatically when you connect Up Bank in Settings
Endpoint: /api/upbank/webhook on your deployment URL
Requires NEXT_PUBLIC_APP_URL to be set correctly

Local Deployments

Need a tunnel service (ngrok or Cloudflare Tunnel) to expose your local server
Set WEBHOOK_BASE_URL in .env.local to your tunnel URL
Without webhooks, transactions sync when you open the app

Custom Domain

Vercel

In Vercel, go to Settings → Domains and add your domain
Update NEXT_PUBLIC_APP_URL to your new domain
Update Supabase Site URL and Redirect URLs with your new domain
Redeploy

Self-hosted (VPS with Caddy)

Example Caddy configuration for reverse-proxying to your PiggyBack instance:

Caddyfile

piggyback.yourdomain.com {
    reverse_proxy localhost:3000
}