Skip to main content
OpenCouncil uses environment variables to configure database connections, API keys, and external service integrations. This guide covers all required and optional environment variables.

​
Initial setup

Copy the example environment file to create your configuration: 
cp .env.example .env
Then edit .env to add your specific values.
The .env.example file contains safe defaults for local development. Variables with defaults are not listed in the example file. See the full environment reference for all available options.

​
Database connection

OpenCouncil requires PostgreSQL 14+ with the PostGIS extension for geospatial features.
OpenCouncil uses two connection strings to support connection pooling in production: 
# Automatically set by development tools (Nix/Docker)
DATABASE_URL="postgresql://opencouncil@localhost:5432/opencouncil?sslmode=disable"
DIRECT_URL="postgresql://opencouncil@localhost:5432/opencouncil?sslmode=disable"

​
Database initialization variables

These variables are used by Docker containers to initialize PostgreSQL: 
DATABASE_USER=postgres
DATABASE_PASSWORD=postgres
DATABASE_NAME=development
When using local databases via Nix or Docker, the development tools automatically override DATABASE_URL and DIRECT_URL with the correct local values. You can keep your .env configured for remote databases.

​
Application URLs

# Base URL for the application (used for authentication callbacks)
NEXTAUTH_URL=http://localhost:3000

# Secret for NextAuth.js session encryption
# Generate with: openssl rand -base64 32
NEXTAUTH_SECRET=your_generated_secret_here
Always generate a unique NEXTAUTH_SECRET for production deployments. Never commit secrets to version control.

​
Required API keys

OpenCouncil requires several API keys for core functionality:
1

Email service (Resend)

Used for authentication emails and notifications.
RESEND_API_KEY=your_resend_api_key
Get your API key from Resend Dashboard
2

AI summaries (Anthropic Claude)

Generates meeting summaries and powers the chat interface.
ANTHROPIC_API_KEY=your_anthropic_api_key
Get your API key from Anthropic Console
3

Search (Elasticsearch)

Full-text search across transcripts.
ELASTICSEARCH_URL=http://localhost:9200
ELASTICSEARCH_API_KEY=your_elasticsearch_api_key
4

Task processing server

Backend server for transcription and async jobs.
TASK_API_URL=http://localhost:3005
TASK_API_KEY=your_task_api_key
See opencouncil-tasks for setup.
5

Maps (Mapbox)

Interactive maps for location-based features.
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_mapbox_access_token
Get your token from Mapbox Account

​
Storage configuration

OpenCouncil uses S3-compatible storage for media files: 
# DigitalOcean Spaces (or any S3-compatible storage)
DO_SPACES_ENDPOINT=https://fra1.digitaloceanspaces.com
DO_SPACES_KEY=your_do_spaces_key
DO_SPACES_SECRET=your_do_spaces_secret
DO_SPACES_BUCKET=your_do_spaces_bucket
CDN_URL=https://data.opencouncil.gr

​
Optional integrations

​
Google Calendar

Automate meeting scheduling: 
GOOGLE_CALENDAR_CLIENT_ID=
GOOGLE_CALENDAR_CLIENT_SECRET=
GOOGLE_CALENDAR_REFRESH_TOKEN=
GOOGLE_CALENDAR_ID=
GOOGLE_CALENDAR_ENABLED=true

​
Google AI (Gemini)

Alternative AI provider: 
GOOGLE_API_KEY=your_google_api_key

​
Cron jobs

Secure cron endpoints (e.g., /api/cron/poll-decisions): 
# Generate with: openssl rand -base64 32
CRON_SECRET=your_cron_secret

​
Basic authentication

Password-protect your deployment: 
BASIC_AUTH_USERNAME=admin
BASIC_AUTH_PASSWORD=secure_password

​
Development-specific variables

​
Preview server access

Connect to preview deployment databases: 
# SSH target for preview server (for --preview-db flag)
OC_PREVIEW_SSH=[email protected]

​
Port configuration

Customize ports for local development: 
OC_APP_PORT=3000
OC_DB_PORT=5432
OC_PRISMA_STUDIO_PORT=5555

​
Environment validation

OpenCouncil validates environment variables at startup using t3-env. If required variables are missing or invalid, the application will fail to start with a clear error message. Validation schema: src/env.mjs

​
Skip validation (build time only)

During builds, you can skip validation for server-side secrets: 
SKIP_ENV_VALIDATION=1
Never skip validation in production runtime. This flag is only for build-time optimizations where secrets aren’t needed.

​
Next steps

Docker deployment

Deploy with Docker Compose

Nix deployment

Deploy with Nix flakes

Database setup

Configure PostgreSQL and PostGIS

Build docs developers (and LLMs) love

Get started for freeTalk to us