Deploy Flaggr to Vercel, Docker, or Cloud Run — infrastructure setup, environment variables, and storage backends

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

Platform	Best For	Complexity
Vercel (recommended)	Production use, zero-ops	Low
Docker / Cloud Run	Self-hosted, custom infrastructure	Medium
Local Development	Development and testing	Low

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

Variable	Required	Description
`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
`KV_REST_API_URL`	Vercel KV URL for caching
`KV_REST_API_TOKEN`	Vercel KV token
`KV_REST_API_READ_ONLY_TOKEN`	Vercel KV read-only token
`UPSTASH_REDIS_REST_URL`	Upstash Redis for rate limiting
`UPSTASH_REDIS_REST_TOKEN`	Upstash Redis token
`DATA_DIR`	Custom data directory (file-based storage)
`DEBUG_SECRET`	Secret for debug endpoints

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:

Firebase Authentication — User login (Google, email/password, credentials)
Cloud Firestore — Production data storage

Setup

Create a Firebase project at console.firebase.google.com
Enable Authentication with your desired providers
Enable Cloud Firestore
Generate a service account key (Project Settings > Service Accounts > Generate new private key)
Set the environment variables from the service account JSON

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:

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

Vercel KV (Caching)

For production caching:

Create a KV store in your Vercel project dashboard
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

Warning

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

Firestore (Production)

Used automatically when FIREBASE_PROJECT_ID is set. Data is stored in Cloud Firestore collections.

For preview/staging environments, collections are prefixed with preview_ to isolate data:

Firestore Collections:
├── projects          (production)
├── preview_projects  (preview)
├── flags             (production)
├── preview_flags     (preview)
└── ...

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 Firebase (Optional)

To develop with Firestore storage and Firebase Authentication:

Copy .env.example to .env.local
Fill in your Firebase credentials
Start the dev server

cp .env.example .env.local
# Edit .env.local with your Firebase credentials
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.

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 flg_your_token" "https://flaggr.dev/api/flags?projectId=proj-123"

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

Platform

Previous←

Authentication & Tokens