Environment setup

This guide covers all environment variables used by OOOC Fête Finder. Copy .env.example to .env.local for local development, and configure these values in your hosting platform for production deployments.

Required variables

These variables are required for the app to run:

AUTH_SECRET

string

required

Minimum 32 characters — used for JWT signing and session security.Generate with:

openssl rand -base64 48

Example:

AUTH_SECRET=dGhpc2lzYXJlYWxseWxvbmdzZWNyZXR0aGF0aXNtb3JldGhhbjMy

Never commit this value to version control. Use different secrets for development and production.

DATABASE_URL

string

required

PostgreSQL connection string including user, password, host, port, and database name.Format:

DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=require

Examples:

Local: postgresql://postgres:password@localhost:5432/oooc_fete_finder
Vercel Postgres: Automatically set by Vercel when you add Postgres storage
Neon: postgresql://user:pass@ep-xxx-xxx.us-east-1.aws.neon.tech/dbname?sslmode=require
Supabase: Available in project settings under Database → Connection string

The app reads only DATABASE_URL. It does not use PGHOST, POSTGRES_*, or other Postgres environment variables that may be set by your hosting provider.

DATA_MODE

enum

required

Data source mode for the app. Required in production.Options:

remote — Use Postgres event store (primary) with local CSV fallback
local — Use local CSV file only (not recommended for production)
test — Use test fixtures (development/testing only)

Recommended:

DATA_MODE=remote

In Vercel preview/production environments, DATA_MODE is required. The app will fail fast at startup if it’s missing.

Core configuration

These variables control fundamental app behavior:

NODE_ENV

enum

default:"development"

Node.js environment mode.Options:

development — Local development with hot reload
production — Production build and runtime
test — Testing environment

Usually set automatically by your framework or platform.

ADMIN_KEY

string

Admin authentication key for accessing /admin and admin APIs.Generate with:

openssl rand -hex 24

Example:

ADMIN_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

If unset or empty, admin login and all admin API endpoints are disabled. This is optional for builds but recommended for any deployment where you need admin access.

ADMIN_RESET_PASSCODE

string

Optional secondary passcode for destructive admin actions like factory reset.Generate with:

openssl rand -hex 32

Keep this different from ADMIN_KEY for step-up authentication on dangerous operations.

POSTGRES_POOL_MAX

number

Maximum PostgreSQL connection pool size.Defaults:

Development: 1
Production: 3

Valid range: 1 to 10Example:

POSTGRES_POOL_MAX=3

Most deployments don’t need to change this. Increase only if you see connection pool exhaustion in logs.

Public variables

These variables are exposed to the client (browser) and must be prefixed with NEXT_PUBLIC_:

NEXT_PUBLIC_SITE_URL

string

default:"http://localhost:3000"

Full public URL of your site, including protocol.Examples:

Local: http://localhost:3000
Production: https://fete-finder.example.com

NEXT_PUBLIC_SITE_URL=https://fete-finder.example.com

Used for:

OG image generation
Share links
API endpoint construction

NEXT_PUBLIC_BASE_PATH

string

default:""

Base path for the app if deployed to a subdirectory.Example for deployment at example.com/fete:

NEXT_PUBLIC_BASE_PATH=/fete

Leave empty for root deployment (most common).

Google integrations

Optional variables for Google Sheets import/preview and geocoding:

GOOGLE_MAPS_API_KEY

string

Google Cloud API key with Geocoding API enabled.Setup:

Create a project in Google Cloud Console
Enable Geocoding API
Create an API key under Credentials
Restrict the key to Geocoding API only (security best practice)

GOOGLE_MAPS_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

If unset, the app uses arrondissement center fallback for event coordinates. This is acceptable for many use cases.

GOOGLE_SHEET_ID

string

Google Sheet ID for admin backup import/preview.Extract from your sheet URL:

https://docs.google.com/spreadsheets/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/edit
                                    ^^^^^^^^^^^^^^^^^^^^^^^^
                                    This is your SHEET_ID

GOOGLE_SHEET_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz

Required only if you want to import events from Google Sheets via /admin/operations.

GOOGLE_SERVICE_ACCOUNT_KEY

string

Google Cloud service account credentials as compact JSON in one line (no file path).Setup:

Create a service account in Google Cloud Console
Grant it access to Google Sheets API
Generate and download a JSON key
Share your Google Sheet with the service account email (found in the JSON)
Compact the JSON to a single line:
```
cat service-account-key.json | jq -c .
```

Set as environment variable:

GOOGLE_SERVICE_ACCOUNT_KEY='{"type":"service_account","project_id":"...","private_key":"..."}'

This is sensitive. Never commit it to version control. Use your platform’s secret management.

REMOTE_CSV_URL

string

Alternative to Sheet API — direct CSV URL (e.g., “Publish to web” from Google Sheets).Example:

REMOTE_CSV_URL=https://docs.google.com/spreadsheets/d/e/.../pub?output=csv

Use either Sheet API (GOOGLE_SHEET_ID + GOOGLE_SERVICE_ACCOUNT_KEY) or REMOTE_CSV_URL, not both.

Stripe integration

Optional variables for partner payment processing:

STRIPE_WEBHOOK_SECRET

string

Stripe webhook signing secret for verifying webhook events from Stripe.Setup:

Create a webhook endpoint in Stripe Dashboard
Point it to: https://yourdomain.com/api/webhooks/stripe
Select events: checkout.session.completed
Copy the signing secret (starts with whsec_)

STRIPE_WEBHOOK_SECRET=whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Required for /api/webhooks/stripe to process payment events.

NEXT_PUBLIC_STRIPE_LINK_SPOTLIGHT_STANDARD

string

Stripe Payment Link URL for Spotlight Standard package.Format:

NEXT_PUBLIC_STRIPE_LINK_SPOTLIGHT_STANDARD=https://buy.stripe.com/XXXXXXXX

If missing, partner page CTAs fall back to contact email.

NEXT_PUBLIC_STRIPE_LINK_SPOTLIGHT_TAKEOVER

string

Stripe Payment Link URL for Spotlight Takeover package.

NEXT_PUBLIC_STRIPE_LINK_PROMOTED

string

Stripe Payment Link URL for Promoted package.

NEXT_PUBLIC_STRIPE_LINK_ADDON_WHATSAPP

string

Stripe Payment Link URL for WhatsApp Add-on.

Stripe Payment Link URL for Newsletter Add-on.

STRIPE_PAYMENT_LINK_ID_SPOTLIGHT_STANDARD

string

Optional mapping of Stripe Payment Link ID to package key for admin queue labels.Example:

STRIPE_PAYMENT_LINK_ID_SPOTLIGHT_STANDARD=plink_XXXXXXXXXXXXXXXXXXXXXXXX

Helps identify which package was purchased in the admin panel.

STRIPE_PAYMENT_LINK_ID_SPOTLIGHT_TAKEOVER

string

Payment Link ID for Spotlight Takeover package.

STRIPE_PAYMENT_LINK_ID_PROMOTED

string

Payment Link ID for Promoted package.

STRIPE_PAYMENT_LINK_ID_ADDON_WHATSAPP

string

Payment Link ID for WhatsApp add-on.

Payment Link ID for Newsletter add-on.

Automation & webhooks

Variables for scheduled jobs and deployment hooks:

CRON_SECRET

string

Bearer token for authenticating scheduled cron job requests.Generate with:

openssl rand -base64 48

Used by:

/api/cron/cleanup-admin-sessions — Removes expired admin sessions (7+ days old)
/api/cron/cleanup-rate-limits — Removes stale rate limit counters (24h grace)
/api/cron/backup-event-store — Creates daily Postgres snapshots at 04:20 UTC

Configure in vercel.json:

{
  "crons": [
    {
      "path": "/api/cron/backup-event-store",
      "schedule": "20 4 * * *"
    }
  ]
}

Vercel automatically sends Authorization: Bearer <CRON_SECRET> header.

DEPLOY_REVALIDATE_SECRET

string

Bearer token for post-deploy revalidation webhook.Generate with:

openssl rand -base64 48

After each deployment, call:

curl -X POST "https://yourdomain.com/api/revalidate/deploy" \
  -H "Authorization: Bearer $DEPLOY_REVALIDATE_SECRET"

This forces:

Live events reload from Postgres
Homepage revalidation
Immediate data freshness after deploy

Useful when deploying with no code changes but new data in the database.

Advanced configuration

ADMIN_NOTIFICATION_CACHE_SECONDS

number

Cache duration (in seconds) for admin header notification counters.Examples:

0 — Disable caching (always fetch fresh)
15 — Cache for 15 seconds (recommended for testing)
Unset — Use default caching behavior

ADMIN_NOTIFICATION_CACHE_SECONDS=15

Lower values provide more real-time notifications but increase database load. Use 0 only for debugging.

Example configurations

# Core (required)
NODE_ENV=development
AUTH_SECRET=<generate-with-openssl-rand-base64-48>
DATABASE_URL=postgresql://postgres:password@localhost:5432/oooc_fete_finder
DATA_MODE=remote

# Admin access
ADMIN_KEY=<generate-with-openssl-rand-hex-24>

# Public URLs
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_BASE_PATH=

# Optional: Google integrations (for testing)
GOOGLE_MAPS_API_KEY=
GOOGLE_SHEET_ID=
GOOGLE_SERVICE_ACCOUNT_KEY=

Validation and testing

The app validates environment variables at startup using @t3-oss/env-nextjs and Zod schemas (see lib/config/env.ts:65).

Common validation errors

AUTH_SECRET must be at least 32 characters long

Your AUTH_SECRET is too short. Generate a proper secret:

openssl rand -base64 48

Missing required DATA_MODE in production

DATA_MODE is required in Vercel preview/production. Set it explicitly:

DATA_MODE=remote

DATABASE_URL is required

Make sure DATABASE_URL is set and formatted correctly:

DATABASE_URL=postgresql://user:pass@host:5432/dbname?sslmode=require

REMOTE_CSV_URL must be a valid URL

If set, REMOTE_CSV_URL must be a complete URL with protocol:

REMOTE_CSV_URL=https://docs.google.com/spreadsheets/d/e/.../pub?output=csv

Skip validation (not recommended)

You can skip environment validation during build:

SKIP_ENV_VALIDATION=true

Only use this for debugging. Never skip validation in production — it prevents runtime errors.

Security best practices

Use different secrets for dev and production

Never reuse AUTH_SECRET, ADMIN_KEY, or other secrets across environments.

Store secrets securely

Use your platform’s secret management:

Vercel: Environment Variables in project settings
GitHub Actions: Repository secrets
Local: .env.local (never commit to git)

Restrict API keys

Limit Google Cloud API keys to specific APIs and domains/IPs.

Rotate secrets periodically

Change AUTH_SECRET, ADMIN_KEY, and webhook secrets every 90 days or after team changes.

Use step-up authentication

Set ADMIN_RESET_PASSCODE different from ADMIN_KEY for destructive actions.

Next steps

Deploy to production

Learn how to deploy OOOC Fête Finder to Vercel or other platforms.

Set up Google Sheets

Configure Google Sheets import for admin backup/preview.

Configure geocoding

Enable precise event coordinates with Google Maps Geocoding API.

Stripe webhooks

Process partner payments with Stripe webhook integration.

Documentation Index

​Environment setup

​Required variables

​Core configuration

​Public variables

​Google integrations

​Stripe integration

​Automation & webhooks

​Advanced configuration

​Example configurations

​Validation and testing

​Common validation errors

​Skip validation (not recommended)

​Security best practices

​Next steps

Deploy to production

Set up Google Sheets

Configure geocoding

Stripe webhooks

Environment setup

Required variables

Core configuration

Public variables

Google integrations

Stripe integration

Automation & webhooks

Advanced configuration

Example configurations

Validation and testing

Common validation errors

Skip validation (not recommended)

Security best practices

Next steps