Skip to main content

Vercel setup, infrastructure, environment variables and storage backends for a deployment of your own, which needs Flaggr's source (available on request)

Last updated November 21, 2026

Deployment

Flaggr is a Next.js application that deploys as a full-stack app with serverless API routes. This guide covers deployment options, required infrastructure, and configuration.

You need the source to deploy Flaggr

If you use flaggr.dev, there's nothing to deploy. Running your own deployment needs Flaggr's source code, which isn't public: self-hosting is available on request. There's no public container image or one-click deploy.

Deployment Options

PlatformBest ForComplexity
Vercel (recommended)Production use, zero-opsLow
Containers (Docker, Kubernetes, Cloud Run)Self-hosted, custom infrastructure (on request)Medium
Local DevelopmentDevelopment and testingLow

Setup

From a checkout of the source:

# Install Vercel CLI
npm i -g vercel
 
# Deploy to preview
vercel
 
# Deploy to production
vercel --prod

Vercel Configuration

Flaggr is pre-configured for Vercel with:

  • Serverless API routes (automatic scaling)
  • Edge-compatible middleware
  • A shared cache from a KV REST store, such as Upstash Redis from the Vercel Marketplace (see KV store)
  • Automatic HTTPS and CDN

Required Environment Variables

Set these in your Vercel project settings (Settings > Environment Variables):

VariableRequiredDescription
DATABASE_URLYesPooled Neon Postgres connection string. Without it the app uses file storage, which is for development only
DATABASE_URL_DIRECTRecommendedDirect connection for npm run db:migrate (falls back to DATABASE_URL_UNPOOLED, then DATABASE_URL)
NEXT_PUBLIC_FIREBASE_API_KEYYesFirebase client API key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAINYesFirebase auth domain (e.g., your-project.firebaseapp.com)
NEXT_PUBLIC_FIREBASE_PROJECT_IDYesFirebase project ID
FIREBASE_PROJECT_IDYesFirebase Admin SDK project ID
FIREBASE_CLIENT_EMAILYesFirebase service account email
FIREBASE_PRIVATE_KEYYesFirebase service account private key

Optional Environment Variables

VariableDescription
REDIS_URLRedis for the shared cache and real-time pub/sub. A shared cache (this, REDIS_WRITE_URL, or KV_REST_API_URL with KV_REST_API_TOKEN) is required in production: see Shared cache
REDIS_READ_URL / REDIS_WRITE_URLSeparate Redis endpoints for the read and write cache planes (each falls back to REDIS_URL); credentials, identities and SSO lookups use the write plane
KV_REST_API_URLREST URL of a KV store for caching (the shared cache when no Redis is set; it counts only with KV_REST_API_TOKEN); see KV store
KV_REST_API_TOKENThat store's REST token
UPSTASH_REDIS_REST_URLUpstash Redis REST endpoint for rate limiting only; without it, limits are per instance
UPSTASH_REDIS_REST_TOKENUpstash Redis token
FLAGGR_MAINTENANCE_SECRETSecret for internal maintenance endpoints such as org migrations
DEBUG_SECRETOperator secret for /api/debug*, sent only in the X-Debug-Secret header (the ?secret= query is no longer accepted). Without it, only verified platform-admin dashboard sessions can use the debug endpoints; everyone else gets 404. Never set NEXT_PUBLIC_DEBUG_SECRET to the same value: it ships to browsers, and the secret is then ignored.
METRICS_BEARER_TOKENBearer secret that Prometheus scrapers send to read /api/metrics (trimmed; unset or blank → only platform-admin dashboard sessions can read it)
ANALYTICS_CLIENT_HASH_SECRET32 random bytes as hex. Keys the daily client hash (data._c) on the analytics rows the app's own ingest routes write (POST /api/analytics/sdk-telemetry, POST /api/ingest/mobile-events): HMAC-SHA256 of the client's IPv4 address or IPv6 /64, keyed with HMAC-SHA256(secret, the UTC date YYYY-MM-DD), first 12 hex characters. The address itself is never stored. Without it, those rows carry no _c, rollout RUM checks can't cap one client's sessions, and the app logs a warning once per instance in production. The browser analytics ingest Worker has its own secret (INGEST_CLIENT_HASH_SECRET)
CRON_SECRETBearer secret for /api/cron/rollouts (rollout tick), /api/cron/alerts (alert evaluation) and /api/analytics/vitals/rollup, compared in constant time; they answer 503 without it. Schedule the first two every 5 minutes; a live alert run needs /api/cron/alerts?dryRun=0 (without dryRun it only dry-runs). Schedule the rollup every hour: it recomputes the last 3 hours, and ?hours= (1–744) backfills a longer gap

CI/CD with GitHub Actions

The source includes a Quality Scan workflow (.github/workflows/quality-scan.yaml):

  • Pull requests and pushes to main build the app and run the test suites.
  • Push to main: once the scan passes, its deploy-vercel job builds and deploys to production (vercel pull --yes --environment=production, vercel build --prod, then vercel deploy --prebuilt --prod --archive=tgz, which uploads the build as one compressed archive).

The workflow doesn't create preview deployments. Its jobs run on self-hosted runners labelled cuttlefish; change runs-on to run them elsewhere. The deploy job needs:

VERCEL_TOKEN      — repository secret; get one from vercel.com/account/tokens
VERCEL_ORG_ID     — repository variable; run `vercel whoami` or check Vercel settings
VERCEL_PROJECT_ID — repository variable; find it in Vercel project settings

Docker / Cloud Run

There's no public container image. Running Flaggr in containers (Docker, Kubernetes or Cloud Run) is part of self-hosting, which is available on request (the platform's source isn't public). That page lists what a deployment needs, its environment variables and its health checks.

Required Infrastructure

Firebase Authentication + Neon Postgres

A production deployment needs two services:

  1. Firebase Authentication — User login (Google, email/password, credentials)
  2. Neon Postgres — Production data storage

Setup

  1. Create a Firebase project at console.firebase.google.com
  2. Enable Authentication with your desired providers
  3. Create a Neon project at neon.tech and copy the pooled connection string
  4. Generate a Firebase service account key (Project Settings > Service Accounts > Generate new private key)
  5. Set the environment variables (DATABASE_URL, DATABASE_URL_DIRECT, Firebase credentials)
  6. Create the flaggr schema before the first deploy, and again after upgrades that add migrations: DATABASE_URL_DIRECT="postgresql://..." npm run db:migrate. The build doesn't run migrations

Client SDK Variables (Safe to Expose)

Get these from Firebase Console > Project Settings > General > Your apps > Web app:

NEXT_PUBLIC_FIREBASE_API_KEY=AIzaSy...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project

Admin SDK Variables (Keep Secret)

Get these from the service account JSON key file:

FIREBASE_PROJECT_ID=your-project
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your-project.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

Upstash Redis (Rate Limiting)

For production rate limiting that works across serverless instances:

  1. Create a database at console.upstash.com
  2. Copy the REST API credentials
UPSTASH_REDIS_REST_URL=https://your-db.upstash.io
UPSTASH_REDIS_REST_TOKEN=AXxx...

Without Upstash, rate limiting falls back to in-memory storage (not shared across serverless instances — only suitable for development).

KV store (Caching)

Vercel no longer offers its own KV stores. For production caching on Vercel, add Upstash for Redis from the Vercel Marketplace (vercel integration add upstash) and connect it to the project; from the source, scripts/setup-vercel-kv.sh reports which environments have a shared cache and offers to run the integration. Flaggr reads the store's REST URL and token from KV_REST_API_URL and KV_REST_API_TOKEN, and uses the store only when both are set; if the integration names its variables differently, add these two yourself:

KV_REST_API_URL=https://your-db.upstash.io
KV_REST_API_TOKEN=AXxx...

Without a KV store (or Redis), caching falls back to in-memory storage.

Shared cache (required in production)

Run production with a shared cache: REDIS_URL (or REDIS_WRITE_URL), or KV_REST_API_URL with KV_REST_API_TOKEN. REDIS_READ_URL alone doesn't count: credentials live in the write plane. Revoking a token, re-linking an identity or editing an SSO connection then reaches every instance within about 10 s. Without one, each instance keeps those entries in its own memory: they are capped at 30 s (and the API-token storage memo with them), so a revocation reaches other instances within about 30 s. /api/health then reports cache.shared: false, with cache.degraded: true and the reason in cache.warning; its HTTP status stays 200. Upstash (UPSTASH_REDIS_REST_URL/TOKEN) backs only rate limiting; without it, limits are per instance.

curl -s https://your-flaggr-instance.com/api/health | jq '.cache | {backend, shared, degraded, warning}'

Storage Backends

Flaggr supports two storage backends:

File-Based Storage (Development)

Used automatically when DATABASE_URL is not set. Data is stored in JSON files in data/ under the app's working directory:

data/
├── flags.json
├── services.json
├── projects.json
└── ...
Warning

File-based storage is for development only. Data is lost between serverless invocations and does not support concurrent access.

Neon Postgres (Production)

Used when DATABASE_URL is set. All flag state, projects, audit logs, and versions live in the flaggr Postgres schema — DATABASE_URL should be the pooled connection (app queries); DATABASE_URL_DIRECT is the direct connection for migrations and schema work.

For preview/staging environments, use a Neon branch — an isolated copy-on-write clone of production data. Set the branch's connection string as the preview deployment's DATABASE_URL.

Local Development Setup

Prerequisites

  • Node.js 18+
  • npm

Quick Start

From a checkout of the source (it isn't public: see Self-Hosting):

# Install dependencies
npm install
 
# Start development server (uses file-based storage)
npm run dev

Visit http://localhost:3000. No Firebase setup is needed for local development — file-based storage and credentials auth work out of the box.

With Postgres (Optional)

To develop against real Postgres storage:

  1. Copy .env.example to .env.local
  2. Set DATABASE_URL (the pooled connection string) and DATABASE_URL_DIRECT (the direct one, for migrations), and fill in your Firebase credentials
  3. Create the flaggr schema with npm run db:migrate. It reads .env, not .env.local, so pass the direct connection string on the command line
  4. Start the dev server
cp .env.example .env.local
# Edit .env.local: DATABASE_URL, DATABASE_URL_DIRECT and your Firebase credentials
DATABASE_URL_DIRECT="postgresql://..." npm run db:migrate
npm run dev

Environment Variable Gotchas

Warning

Always trim environment variables. Values copied from dashboards (Vercel, Upstash, Firebase) often contain trailing newlines or whitespace that cause cryptic errors.

Common symptoms of whitespace in env vars:

Error: Upstash Redis client was passed an invalid URL. Received: "https://example.upstash.io\n"
Error: Invalid Firebase private key

Flaggr trims critical environment variables internally, but if you encounter issues, verify your values:

# Check for trailing whitespace
echo -n "$UPSTASH_REDIS_REST_URL" | xxd | tail -1

Health Check

Verify your deployment is running:

curl -s https://your-flaggr-instance.com/api/health | jq .

The health endpoint returns the commit hash and environment info, useful for verifying deployments.

For monitoring and alerting, poll GET /api/readyz: it answers 503 when the storage the deployment uses (Postgres SELECT 1 within 3 seconds, or the data/ directory without DATABASE_URL) or the read cache fails. Each instance reuses its Postgres answer for 5 seconds. Keep GET /api/healthz as the Kubernetes liveness and readiness probe: every replica shares the database, so a readiness probe on /api/readyz would take every replica out of the Service during a Postgres outage. A monitor that polls /api/readyz keeps a Neon compute from suspending.

Production Debugging

Vercel Logs

# View real-time logs
vercel logs flaggr.dev --follow
 
# List recent deployments
vercel ls

Direct API Testing

# Test unauthenticated endpoint
curl -s "https://flaggr.dev/api/health"
 
# Test authenticated endpoint
curl -s -H "Authorization: Bearer fgr_your_token" "https://flaggr.dev/api/flags?projectId=proj-123"