Environment Variables

This page documents all environment variables used by Pongo. Variables are organized by category for easier navigation.

Database

Configure your database connection and driver.

DATABASE_URL

string

default:"file:./pongo/pongo.db"

Database connection string. Supports SQLite (file:), PostgreSQL (postgres://), and Turso (libsql://) formats.Examples:

SQLite: file:./pongo/pongo.db
PostgreSQL: postgres://user:password@host:5432/pongo
Turso: libsql://your-db.turso.io

DB_DRIVER

'sqlite' | 'pg'

default:"auto-detected"

Database driver to use. Automatically detected from DATABASE_URL but can be manually set.Values:

sqlite - SQLite driver
pg - PostgreSQL driver

TURSO_AUTH_TOKEN

string

Authentication token for Turso database connections. Required when using libsql:// connection strings.Example:

DATABASE_URL=libsql://your-db.turso.io
TURSO_AUTH_TOKEN=your-turso-token

Authentication

Control dashboard access and session management.

ACCESS_CODE

string

Password for dashboard authentication. When set, all non-public routes require login.Optional - If not set, the dashboard is open to anyone.Example:

ACCESS_CODE=your-secret-password

EXPIRY_DAYS

number

default:"7"

Session duration in days. Sessions use encrypted cookies (iron-session).Example:

EXPIRY_DAYS=30  # Sessions last 30 days

Scheduler

Configure the monitor scheduler service.

SCHEDULER_ENABLED

boolean

default:"false"

Auto-start scheduler in Docker. Used by the Docker entrypoint.Example:

SCHEDULER_ENABLED=true

SCHEDULER_PORT

number

default:"3001"

HTTP API port for the scheduler service.Example:

SCHEDULER_PORT=3001

SCHEDULER_URL

string

Scheduler service URL. Enables manual monitor runs from the dashboard UI.Example:

SCHEDULER_URL=http://scheduler:3001

SCHEDULER_MAX_CONCURRENCY

number

default:"10"

Maximum number of monitors to execute in parallel.Example:

SCHEDULER_MAX_CONCURRENCY=20

SCHEDULER_MAX_RETRIES

number

default:"3"

Number of retry attempts for failed monitor checks.Example:

SCHEDULER_MAX_RETRIES=5

SCHEDULER_RETRY_DELAY_MS

number

default:"5000"

Base retry delay in milliseconds. Uses exponential backoff.Example:

SCHEDULER_RETRY_DELAY_MS=10000  # 10 second base delay

ENABLE_MANUAL_RUN

boolean

default:"false"

Show manual run button in the dashboard UI. Requires SCHEDULER_URL to be set.Example:

ENABLE_MANUAL_RUN=true

PONGO_REGION

string

default:"default"

Region identifier for multi-region deployments. Used in alert thresholds and region-aware monitoring.Example:

PONGO_REGION=us-east
PONGO_REGION=eu-west

Archival

Configure automatic archival of check results to S3 or local storage.

ARCHIVAL_ENABLED

boolean

default:"false"

Enable automatic data archival. Archives old check results as Parquet files.Example:

ARCHIVAL_ENABLED=true

ARCHIVAL_RETENTION_DAYS

number

default:"30"

Number of days before check results are archived.Example:

ARCHIVAL_RETENTION_DAYS=90  # Archive after 90 days

ARCHIVAL_CRON

string

default:"0 3 * * *"

Cron schedule for archival jobs. Default runs at 3 AM daily.Examples:

ARCHIVAL_CRON="0 3 * * *"      # Daily at 3 AM
ARCHIVAL_CRON="0 */6 * * *"    # Every 6 hours
ARCHIVAL_CRON="0 2 * * 0"      # Weekly on Sunday at 2 AM

ARCHIVAL_BATCH_SIZE

number

default:"10000"

Number of rows to process per archival batch.Example:

ARCHIVAL_BATCH_SIZE=50000  # Process 50k rows at a time

ARCHIVAL_LOCAL_PATH

string

default:"./archives"

Local filesystem path for archives when not using S3.Example:

ARCHIVAL_LOCAL_PATH=/data/pongo/archives

ARCHIVER_PORT

number

default:"3002"

HTTP API port for the archiver service.Example:

ARCHIVER_PORT=3002

S3 Storage

Configure S3 for archival storage. All S3 variables are optional if using local archival.

S3_BUCKET

string

S3 bucket name for storing archived data.Example:

S3_BUCKET=pongo-archives

S3_REGION

string

AWS region where the S3 bucket is located.Example:

S3_REGION=us-east-1

S3_ACCESS_KEY_ID

string

AWS access key ID for S3 authentication.Example:

S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

S3_SECRET_ACCESS_KEY

string

AWS secret access key for S3 authentication.Example:

S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

S3_PREFIX

string

Prefix for S3 object keys. Useful for organizing archives within a shared bucket.Example:

S3_PREFIX=production/archives

Vercel Deployment

Specific variables for Vercel deployments.

CRON_SECRET

string

Authentication token for the Vercel cron endpoint (/api/cron).Required for Vercel deployments to secure the cron endpoint.Example:

# Generate a secure secret
CRON_SECRET=$(openssl rand -base64 32)

Application Settings

NEXT_PUBLIC_URL

string

Public URL of your Pongo instance. Used for SEO metadata and generating absolute URLs.Example:

NEXT_PUBLIC_URL=https://status.example.com

SHOW_ABOUT

boolean

default:"false"

Show the “About” section in the dashboard UI.Example:

SHOW_ABOUT=true

Quick Reference

Minimal Configuration

For a basic local development setup:

.env

# Optional - defaults are fine for development
DATABASE_URL=file:./pongo/pongo.db

Production Configuration

Recommended settings for production:

.env

# Database (required)
DATABASE_URL=postgres://user:password@host:5432/pongo

# Authentication (recommended)
ACCESS_CODE=your-secret-password

# Scheduler (if using separate scheduler service)
SCHEDULER_URL=http://scheduler:3001
ENABLE_MANUAL_RUN=true
PONGO_REGION=us-east

# Archival (optional)
ARCHIVAL_ENABLED=true
ARCHIVAL_RETENTION_DAYS=90
S3_BUCKET=pongo-archives
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-key
S3_SECRET_ACCESS_KEY=your-secret

# Application
NEXT_PUBLIC_URL=https://status.example.com

Vercel Configuration

.env

DATABASE_URL=postgres://user:password@host:5432/pongo
CRON_SECRET=$(openssl rand -base64 32)
ACCESS_CODE=your-password
NEXT_PUBLIC_URL=https://your-app.vercel.app

Docker Configuration

.env

DATABASE_URL=postgres://postgres:password@db:5432/pongo
ACCESS_CODE=your-password
SCHEDULER_ENABLED=true
ARCHIVAL_ENABLED=true
S3_BUCKET=pongo-archives
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-key
S3_SECRET_ACCESS_KEY=your-secret

Environment-Specific Notes

Public Routes: The following routes are always accessible without authentication, even when ACCESS_CODE is set:

/ - Landing page
/shared/* - Public status pages
/login - Login page
/api/* - API endpoints

Security: Never commit .env files to version control. Use environment variable management provided by your hosting platform.

Session Management: Sessions are stored as encrypted cookies using iron-session. They last for the duration specified by EXPIRY_DAYS (default 7 days).

Deployment Options

Configuration

Environment Variables

Database

Authentication

Scheduler

Archival

S3 Storage

Vercel Deployment

Application Settings

Quick Reference

Minimal Configuration

Production Configuration

Vercel Configuration

Docker Configuration

Environment-Specific Notes

Build docs developers (and LLMs) love

Deployment Options

Configuration

​Database

​Authentication

​Scheduler

​Archival

​S3 Storage

​Vercel Deployment

​Application Settings

​Quick Reference

​Minimal Configuration

​Production Configuration

​Vercel Configuration

​Docker Configuration

​Environment-Specific Notes

Build docs developers (and LLMs) love

Database

Authentication

Scheduler

Archival

S3 Storage

Vercel Deployment

Application Settings

Quick Reference

Minimal Configuration

Production Configuration

Vercel Configuration

Docker Configuration

Environment-Specific Notes