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.
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
| Platform | Best For | Complexity |
|---|---|---|
| Vercel (recommended) | Production use, zero-ops | Low |
| Containers (Docker, Kubernetes, Cloud Run) | Self-hosted, custom infrastructure (on request) | Medium |
| Local Development | Development and testing | Low |
Vercel (Recommended)
Setup
From a checkout of the source:
# Install Vercel CLI
npm i -g vercel
# Deploy to preview
vercel
# Deploy to production
vercel --prodVercel 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):
| Variable | Required | Description |
|---|---|---|
DATABASE_URL | Yes | Pooled Neon Postgres connection string. Without it the app uses file storage, which is for development only |
DATABASE_URL_DIRECT | Recommended | Direct connection for npm run db:migrate (falls back to DATABASE_URL_UNPOOLED, then DATABASE_URL) |
NEXT_PUBLIC_FIREBASE_API_KEY | Yes | Firebase client API key |
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN | Yes | Firebase auth domain (e.g., your-project.firebaseapp.com) |
NEXT_PUBLIC_FIREBASE_PROJECT_ID | Yes | Firebase project ID |
FIREBASE_PROJECT_ID | Yes | Firebase Admin SDK project ID |
FIREBASE_CLIENT_EMAIL | Yes | Firebase service account email |
FIREBASE_PRIVATE_KEY | Yes | Firebase service account private key |
Optional Environment Variables
| Variable | Description |
|---|---|
REDIS_URL | Redis 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_URL | Separate 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_URL | REST 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_TOKEN | That store's REST token |
UPSTASH_REDIS_REST_URL | Upstash Redis REST endpoint for rate limiting only; without it, limits are per instance |
UPSTASH_REDIS_REST_TOKEN | Upstash Redis token |
FLAGGR_MAINTENANCE_SECRET | Secret for internal maintenance endpoints such as org migrations |
DEBUG_SECRET | Operator 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_TOKEN | Bearer secret that Prometheus scrapers send to read /api/metrics (trimmed; unset or blank → only platform-admin dashboard sessions can read it) |
ANALYTICS_CLIENT_HASH_SECRET | 32 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_SECRET | Bearer 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
mainbuild the app and run the test suites. - Push to
main: once the scan passes, itsdeploy-verceljob builds and deploys to production (vercel pull --yes --environment=production,vercel build --prod, thenvercel 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:
- Firebase Authentication — User login (Google, email/password, credentials)
- Neon Postgres — Production data storage
Setup
- Create a Firebase project at console.firebase.google.com
- Enable Authentication with your desired providers
- Create a Neon project at neon.tech and copy the pooled connection string
- Generate a Firebase service account key (Project Settings > Service Accounts > Generate new private key)
- Set the environment variables (
DATABASE_URL,DATABASE_URL_DIRECT, Firebase credentials) - Create the
flaggrschema 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-projectAdmin 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:
- Create a database at console.upstash.com
- 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
└── ...
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 devVisit 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:
- Copy
.env.exampleto.env.local - Set
DATABASE_URL(the pooled connection string) andDATABASE_URL_DIRECT(the direct one, for migrations), and fill in your Firebase credentials - Create the
flaggrschema withnpm run db:migrate. It reads.env, not.env.local, so pass the direct connection string on the command line - 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 devEnvironment Variable Gotchas
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 -1Health 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 lsDirect 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"Related
- Quick Start — Get up and running in 5 minutes
- Self-Hosting — Run Flaggr on your own infrastructure (on request)
- API Tokens — Set up authentication
- Environments — Multi-environment configuration
- Rate Limiting — Configure rate limits
- Caching Strategy — Multi-tier cache setup