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.

Deployment Options

Vercel (Recommended)

One-Click Deploy

Manual Setup

# 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
• Built-in Redis/KV integration via Vercel KV
• Automatic HTTPS and CDN

Required Environment Variables

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

Optional Environment Variables

CI/CD with GitHub Actions

Flaggr includes workflows for automatic deployment:

• Push to main → Production deployment
• Pull requests → Preview deployment
• Feature branches → Preview deployment

Add these GitHub secrets:

VERCEL_TOKEN     — Get from vercel.com/account/tokens
VERCEL_ORG_ID    — Run `vercel whoami` or check Vercel settings
VERCEL_PROJECT_ID — Find in Vercel project settings

Docker / Cloud Run

Building the Image

Flaggr includes a Dockerfile.grpc for containerized deployment:

# Build the Docker image
docker build -f Dockerfile.grpc -t flaggr .
 
# Run locally
docker run -p 8080:8080 \
  -e FIREBASE_PROJECT_ID=your-project \
  -e FIREBASE_CLIENT_EMAIL=your-email \
  -e FIREBASE_PRIVATE_KEY="$(cat service-account-key.pem)" \
  flaggr

Cloud Run Deployment

# Build and push to Google Container Registry
gcloud builds submit --tag gcr.io/YOUR_PROJECT/flaggr
 
# Deploy to Cloud Run
gcloud run deploy flaggr \
  --image gcr.io/YOUR_PROJECT/flaggr \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "FIREBASE_PROJECT_ID=your-project" \
  --set-env-vars "FIREBASE_CLIENT_EMAIL=your-email" \
  --set-secrets "FIREBASE_PRIVATE_KEY=firebase-key:latest"

Required Infrastructure

Firebase (Authentication + Storage)

Firebase provides two critical 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)

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).

Vercel KV (Caching)

For production caching:

1. Create a KV store in your Vercel project dashboard
2. Environment variables are automatically populated

KV_REST_API_URL=https://your-kv.kv.vercel-storage.com
KV_REST_API_TOKEN=AXxx...
KV_REST_API_READ_ONLY_TOKEN=AXxx...

Without Vercel KV, caching falls back to in-memory storage.

Storage Backends

Flaggr supports two storage backends:

File-Based Storage (Development)

Used automatically when FIREBASE_PROJECT_ID is not set. Data is stored in JSON files:

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

Configure the data directory:

DATA_DIR=./data  # Default: ./data

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

# Clone the repository
git clone https://github.com/flaggr/flaggr.git
cd flaggr
 
# 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. Fill in your Firebase credentials
3. Start the dev server

cp .env.example .env.local
# Edit .env.local with your Firebase credentials
npm run dev

Environment Variable Gotchas

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.

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"

Related

• Quick Start — Get up and running in 5 minutes
• API Tokens — Set up authentication
• Environments — Multi-environment configuration
• Rate Limiting — Configure rate limits
• Caching Strategy — Multi-tier cache setup