Skip to content

Environment Variables Reference

This document provides a comprehensive reference for all environment variables used in Coalition Builder.

Backend Environment Variables

Database Configuration

Variable Description Default Required
DATABASE_URL Full PostgreSQL connection string - Yes
DB_NAME Database name coalition No
DB_USER Database username postgres No
DB_PASSWORD Database password - No
DB_HOST Database host localhost No
DB_PORT Database port 5432 No

Example:

DATABASE_URL=postgresql://user:password@localhost:5432/coalition

Django Configuration

Variable Description Default Required
SECRET_KEY Django secret key for cryptographic signing - Yes
DEBUG Enable debug mode False No
ALLOWED_HOSTS Comma-separated list of allowed hosts localhost No
CSRF_TRUSTED_ORIGINS Trusted origins for CSRF - No
TIME_ZONE Application timezone UTC No
LANGUAGE_CODE Default language en-us No

Example:

SECRET_KEY=your-very-secure-secret-key-here
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1,yourdomain.com
CSRF_TRUSTED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com

Organization Configuration

Variable Description Default Required
ORGANIZATION_NAME Organization name for emails and branding Coalition Builder Yes
ORG_TAGLINE Organization tagline (fallback) Building advocacy partnerships No
CONTACT_EMAIL Primary contact email address info@example.org Yes

Note: ORGANIZATION_NAME and CONTACT_EMAIL are required for proper email functionality. These also serve as fallbacks when no active homepage configuration exists in the database.

Example:

ORGANIZATION_NAME="Environmental Coalition"
ORG_TAGLINE="Protecting our planet through policy"
CONTACT_EMAIL="info@environmentalcoalition.org"

File Storage Configuration

Variable Description Default Required
AWS_STORAGE_BUCKET_NAME S3 bucket name for media file uploads - Production
AWS_REGION AWS region for S3 bucket us-east-1 No

Note: In production, media files (uploaded images) are automatically stored in AWS S3. The ECS task role provides authentication for S3 access.

File Organization:

  • logos/ - Organization logos from theme settings
  • favicons/ - Favicon uploads
  • backgrounds/ - Hero background images
  • content_blocks/ - Images from content blocks

Example:

AWS_STORAGE_BUCKET_NAME="my-org-static-assets"
AWS_REGION="us-west-2"

Email Configuration

Note: When deployed on AWS ECS, email credentials are automatically pulled from AWS Secrets Manager if configured via Terraform. See Email Configuration for automated AWS SES setup.

Variable Description Default Required
EMAIL_BACKEND Django email backend SafeSMTPBackend (production) No
EMAIL_HOST SMTP host email-smtp.us-east-1.amazonaws.com No
EMAIL_PORT SMTP port 587 No
EMAIL_USE_TLS Use TLS encryption True No
EMAIL_HOST_USER SMTP username Auto from Secrets Manager No
EMAIL_HOST_PASSWORD SMTP password Auto from Secrets Manager No
DEFAULT_FROM_EMAIL Default sender email - Yes
ADMIN_NOTIFICATION_EMAILS Comma-separated admin emails for endorsement notifications - Yes
AUTO_APPROVE_VERIFIED_ENDORSEMENTS Auto-approve after email verification true No
AKISMET_SECRET_API_KEY Akismet API key for spam detection - No
SITE_URL Base URL for email links - Yes
API_URL Backend API URL (for admin links) http://localhost:8000 No

Email Template Configuration:

Variable Description Default Required
ORGANIZATION_NAME Name used in email templates Coalition Builder No

AWS SES Example (Automatic with Terraform):

# These are configured automatically when using Terraform deployment
EMAIL_BACKEND=coalition.core.email_backend.SafeSMTPBackend
EMAIL_HOST=email-smtp.us-east-1.amazonaws.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
# EMAIL_HOST_USER and EMAIL_HOST_PASSWORD are pulled from AWS Secrets Manager
DEFAULT_FROM_EMAIL="Coalition Builder <noreply@yourdomain.com>"
ADMIN_NOTIFICATION_EMAILS="admin1@yourdomain.com,admin2@yourdomain.com"
SITE_URL="https://yourdomain.com"
API_URL="https://api.yourdomain.com"

Manual SMTP Example:

EMAIL_BACKEND=coalition.core.email_backend.SafeSMTPBackend
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
DEFAULT_FROM_EMAIL="Coalition Builder <noreply@yourdomain.com>"
ADMIN_NOTIFICATION_EMAILS="admin1@yourdomain.com,admin2@yourdomain.com"
SITE_URL="https://yourdomain.com"
API_URL="https://api.yourdomain.com"

Geocoding Configuration

Variable Description Default Required
TIGER_GEOCODING_CONFIDENCE_THRESHOLD Maximum rating for accepting Tiger geocoder results (0-100) 20 No

Tiger Geocoder Rating Scale:

  • 0: Exact match
  • 1-10: Very high confidence (recommended for urban areas)
  • 10-20: High confidence (default, good for most use cases)
  • 20-30: Moderate confidence (recommended for rural areas)
  • 30+: Low confidence (may produce inaccurate results)

Example:

# Stricter matching for urban areas with high-quality address data
TIGER_GEOCODING_CONFIDENCE_THRESHOLD=10

# More lenient matching for rural areas or incomplete addresses
TIGER_GEOCODING_CONFIDENCE_THRESHOLD=25

Storage Configuration

Variable Description Default Required
USE_S3 Use AWS S3 for static/media files False No
AWS_ACCESS_KEY_ID AWS access key - No
AWS_SECRET_ACCESS_KEY AWS secret key - No
AWS_STORAGE_BUCKET_NAME S3 bucket name - No
AWS_S3_REGION_NAME S3 region us-east-1 No
AWS_S3_CUSTOM_DOMAIN Custom S3 domain - No

Example:

USE_S3=True
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_STORAGE_BUCKET_NAME=coalition-builder-static
AWS_S3_REGION_NAME=us-east-1

Endorsement System Configuration

Variable Description Default Required
ENDORSEMENT_RATE_LIMIT_WINDOW Rate limit time window (seconds) 300 No
ENDORSEMENT_RATE_LIMIT_MAX_ATTEMPTS Max attempts per time window 3 No

Spam Prevention Configuration:

These settings can be customized to adjust spam detection sensitivity:

# Rate limiting (5 minutes = 300 seconds)
ENDORSEMENT_RATE_LIMIT_WINDOW=300
ENDORSEMENT_RATE_LIMIT_MAX_ATTEMPTS=3

# Cache backend (required for rate limiting)
# Redis recommended for production and development
CACHE_URL=redis://localhost:6379/1

Note: The spam prevention system includes built-in configurations for:

  • Suspicious email domain detection
  • Content quality analysis
  • Honeypot field validation
  • Form timing analysis

Logging Configuration

Variable Description Default Required
LOG_LEVEL Application log level INFO No
SENTRY_DSN Sentry error tracking DSN - No
SENTRY_ENVIRONMENT Sentry environment tag - No

Example:

LOG_LEVEL=DEBUG
SENTRY_DSN=https://example@sentry.io/123456
SENTRY_ENVIRONMENT=production

Frontend Environment Variables

API Configuration

Variable Description Default Required
NEXT_PUBLIC_API_URL Backend API base URL http://localhost:8000/api No
REACT_APP_DEBUG Enable debug logging false No

Example:

NEXT_PUBLIC_API_URL=https://api.yourdomain.com/api
REACT_APP_DEBUG=true

Organization Branding

Variable Description Default Required
NEXT_PUBLIC_ORGANIZATION_NAME Organization name Coalition Builder No
NEXT_PUBLIC_TAGLINE Organization tagline Building advocacy partnerships No
NEXT_PUBLIC_PRIMARY_COLOR Primary brand color #1976d2 No
NEXT_PUBLIC_LOGO_URL Logo image URL - No

Example:

NEXT_PUBLIC_ORGANIZATION_NAME="Environmental Coalition"
NEXT_PUBLIC_TAGLINE="Protecting our planet"
NEXT_PUBLIC_PRIMARY_COLOR="#2e7d32"
NEXT_PUBLIC_LOGO_URL="https://yourdomain.com/logo.png"

Analytics and Tracking

Variable Description Default Required
NEXT_PUBLIC_GA_TRACKING_ID Google Analytics tracking ID - No
NEXT_PUBLIC_HOTJAR_ID Hotjar site ID - No

Google Analytics Integration:

When NEXT_PUBLIC_GA_TRACKING_ID is provided, the application automatically:

  • Loads Google Analytics scripts client-side in both frontend and SSR applications
  • Respects cookie consent preferences (only tracks when analytics cookies are enabled)
  • Tracks page views, campaign views, endorsement submissions, and form interactions
  • Enables privacy-compliant tracking with IP anonymization and secure cookies

Example:

NEXT_PUBLIC_GA_TRACKING_ID=G-XXXXXXXXXX
NEXT_PUBLIC_HOTJAR_ID=1234567

Notes:

  • Use Google Analytics 4 (GA4) measurement IDs starting with "G-"
  • Analytics only activates when users consent to analytics cookies
  • Leave blank to disable all analytics tracking

Frontend Environment Variables

Server Configuration

Variable Description Default Required
API_URL Backend API URL (server-side rewrites for /api/* proxying) http://localhost:8000 Production
NEXT_PUBLIC_API_URL Backend API URL (client-side) http://localhost:8000/api No
AWS_STORAGE_BUCKET_NAME S3 bucket name for next.config.js remotePatterns (image opt) - Production
PORT Server port 3000 No
NODE_ENV Node environment development No
HOSTNAME Server hostname localhost No

Example:

API_URL=http://backend:8000
NEXT_PUBLIC_API_URL=https://api.yourdomain.com/api
PORT=3000
NODE_ENV=production
HOSTNAME=0.0.0.0

Next.js Configuration

Variable Description Default Required
NEXT_TELEMETRY_DISABLED Disable Next.js telemetry false No
ANALYZE Enable bundle analyzer false No

Example:

NEXT_TELEMETRY_DISABLED=1
ANALYZE=true

Image Optimization Configuration

Variable Description Default Required
CLOUDFRONT_DOMAIN CloudFront CDN domain (used when backend serves CloudFront URLs) - See note
AWS_STORAGE_BUCKET_NAME S3 bucket name (used when backend serves direct S3 URLs) - See note
BACKEND_DOMAIN Backend domain for direct image serving (if different from CDN) - No
USE_S3_DIRECT_URLS Backend setting: whether to serve S3 URLs directly vs CloudFront false No

How Image URLs Work:

The backend (Django) generates image URLs based on its configuration:

  1. When using CloudFront (recommended for production):
  2. Backend has CLOUDFRONT_DOMAIN set and USE_S3_DIRECT_URLS=false
  3. Image URLs look like: https://d123456789.cloudfront.net/media/images/logo.jpg

  4. Next.js needs CLOUDFRONT_DOMAIN in build environment to allow these URLs

  5. When using S3 directly:

  6. Backend has USE_S3_DIRECT_URLS=true OR no CLOUDFRONT_DOMAIN set
  7. Image URLs look like: https://coalition-static-assets-a4853294.s3.amazonaws.com/media/images/logo.jpg
  8. Next.js needs AWS_STORAGE_BUCKET_NAME in build environment to allow these URLs

Important Build-Time Requirements:

  • Both CLOUDFRONT_DOMAIN and AWS_STORAGE_BUCKET_NAME should be provided at build time
  • This ensures Next.js can optimize images regardless of which URL pattern the backend uses
  • These are configured as GitHub repository variables for CI/CD deployments

GitHub Actions Configuration:

To enable image optimization in production deployments:

  1. Go to your GitHub repository → Settings → Secrets and variables → Actions
  2. Click on the "Variables" tab
  3. Add these repository variables:
  4. CLOUDFRONT_DOMAIN: Your CloudFront distribution domain (if using CDN)
  5. AWS_STORAGE_BUCKET_NAME: Your S3 bucket name (from Terraform outputs)

Both should be set to handle all scenarios. The backend configuration determines which URLs are actually generated, but Next.js needs to be prepared for both patterns.

Example:

# Both should be set for maximum compatibility
CLOUDFRONT_DOMAIN=d123456789.cloudfront.net
AWS_STORAGE_BUCKET_NAME=coalition-static-assets-a4853294

# Optional: Direct backend serving
BACKEND_DOMAIN=api.yourdomain.com

# Backend configuration (in ECS/production)
USE_S3_DIRECT_URLS=false  # Use CloudFront URLs (recommended)
# USE_S3_DIRECT_URLS=true  # Use S3 URLs directly

Terraform/Deployment Variables

Note: When using GitHub Actions for deployment, these variables are configured as GitHub environment variables and automatically passed to Terraform. See GitHub Environment Setup for details.

AWS Configuration

Variable Description Default Required
AWS_REGION AWS deployment region us-east-1 Yes
AWS_ACCESS_KEY_ID AWS access key - Yes
AWS_SECRET_ACCESS_KEY AWS secret key - Yes
TF_VAR_aws_region Terraform AWS region - Yes
TF_VAR_environment Deployment environment production No
TF_VAR_project_name Project name for resources coalition-builder No

Domain and SSL

Variable Description Default Required
TF_VAR_domain_name Primary domain name - Yes
TF_VAR_acm_certificate_arn SSL certificate ARN - Yes
TF_VAR_route53_zone_id Route53 hosted zone ID - Yes

Example:

TF_VAR_domain_name=yourdomain.com
TF_VAR_acm_certificate_arn=arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012
TF_VAR_route53_zone_id=Z1D633PJN98FT9

Database Configuration

Variable Description Default Required
TF_VAR_db_name Database name coalition No
TF_VAR_db_master_username Master database username coalition_master No
TF_VAR_db_username Application database username coalition_app No
TF_VAR_use_secrets_manager Use AWS Secrets Manager true No

Email Configuration (SES)

Variable Description Default Required
TF_VAR_ses_from_email Default sender email for SES noreply@example.com Yes
TF_VAR_ses_verify_domain Whether to verify entire domain in SES true No
TF_VAR_ses_notification_email Email for SES bounce/complaint notifications - No
TF_VAR_contact_email Organization contact email info@example.org Yes
TF_VAR_admin_notification_emails Comma-separated admin emails for endorsements - Yes
TF_VAR_organization_name Organization name for email templates Coalition Builder Yes

Example:

TF_VAR_ses_from_email=noreply@yourdomain.com
TF_VAR_ses_verify_domain=true
TF_VAR_ses_notification_email=admin@yourdomain.com
TF_VAR_contact_email=info@yourdomain.com
TF_VAR_admin_notification_emails=admin1@yourdomain.com,admin2@yourdomain.com
TF_VAR_organization_name="Your Organization Name"

Monitoring and Alerts

Variable Description Default Required
TF_VAR_alert_email Email for alerts - Yes
TF_VAR_budget_limit Monthly budget limit (USD) 30 No

Example:

TF_VAR_alert_email=admin@yourdomain.com
TF_VAR_budget_limit=50

Environment Files

Development (.env.development)

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/coalition

# Django
DEBUG=True
SECRET_KEY=development-secret-key-change-in-production
ALLOWED_HOSTS=localhost,127.0.0.1,backend

# Organization (fallbacks)
ORGANIZATION_NAME="Coalition Builder Development"
ORG_TAGLINE="Building advocacy partnerships"
CONTACT_EMAIL="dev@coalitionbuilder.org"

# Email (development - uses console backend)
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
DEFAULT_FROM_EMAIL="Coalition Builder Dev <noreply@localhost>"
ADMIN_NOTIFICATION_EMAILS="admin@localhost"
SITE_URL="http://localhost:3000"

# Endorsement System
ENDORSEMENT_RATE_LIMIT_WINDOW=300
ENDORSEMENT_RATE_LIMIT_MAX_ATTEMPTS=3

# Cache (for rate limiting) - Redis container in docker compose
CACHE_URL=redis://redis:6379/1

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8000/api
REACT_APP_DEBUG=true

# Frontend
API_URL=http://api:8000
NEXT_PUBLIC_API_URL=http://localhost:8000
PORT=3000
NODE_ENV=development

# Image Sources (optional for development)
# CLOUDFRONT_DOMAIN=
# BACKEND_DOMAIN=

Production (.env.production)

# Database (use AWS Secrets Manager in production)
# DATABASE_URL loaded from secrets

# Django
DEBUG=False
SECRET_KEY=${SECRET_KEY}
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com,api.yourdomain.com
CSRF_TRUSTED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com

# Organization
ORGANIZATION_NAME="Your Organization"
ORG_TAGLINE="Your mission statement"
CONTACT_EMAIL="info@yourdomain.com"

# Email
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.yourmailprovider.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=${EMAIL_USER}
EMAIL_HOST_PASSWORD=${EMAIL_PASSWORD}
DEFAULT_FROM_EMAIL="Your Organization <noreply@yourdomain.com>"
ADMIN_NOTIFICATION_EMAILS="admin@yourdomain.com,moderator@yourdomain.com"
SITE_URL="https://yourdomain.com"

# Endorsement System
ENDORSEMENT_RATE_LIMIT_WINDOW=300
ENDORSEMENT_RATE_LIMIT_MAX_ATTEMPTS=3

# Cache (Redis recommended for production)
CACHE_URL=redis://redis:6379/1

# Storage
USE_S3=True
AWS_STORAGE_BUCKET_NAME=${S3_BUCKET_NAME}

# Frontend
API_URL=http://api:8000
NEXT_PUBLIC_API_URL=https://yourdomain.com
NODE_ENV=production
NEXT_TELEMETRY_DISABLED=1

# Image Sources (Required for Next.js image optimization)
CLOUDFRONT_DOMAIN=${CLOUDFRONT_DOMAIN}          # e.g., d123456789.cloudfront.net
AWS_STORAGE_BUCKET_NAME=${S3_BUCKET_NAME}       # e.g., coalition-static-assets-a4853294
BACKEND_DOMAIN=${BACKEND_DOMAIN}                # Optional: api.yourdomain.com

# Monitoring
LOG_LEVEL=INFO
SENTRY_DSN=${SENTRY_DSN}
SENTRY_ENVIRONMENT=production

Testing (.env.test)

# Test Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/coalition_test

# Django Test Settings
DEBUG=True
SECRET_KEY=test-secret-key-for-testing-only
ALLOWED_HOSTS=localhost,testserver

# Disable external services in tests
EMAIL_BACKEND=django.core.mail.backends.locmem.EmailBackend
USE_S3=False

# Email settings for testing
DEFAULT_FROM_EMAIL="Test Coalition <test@example.com>"
ADMIN_NOTIFICATION_EMAILS="admin@example.com"
AUTO_APPROVE_VERIFIED_ENDORSEMENTS="false"  # Require manual admin review
SITE_URL="http://testserver"

# Endorsement system testing
ENDORSEMENT_RATE_LIMIT_WINDOW=60
ENDORSEMENT_RATE_LIMIT_MAX_ATTEMPTS=10

# Cache for testing (in-memory)
CACHE_URL=locmem://

# Test Organization Settings
ORGANIZATION_NAME="Test Coalition"
ORG_TAGLINE="Testing advocacy partnerships"
CONTACT_EMAIL="test@example.com"

# Frontend Test Settings
API_URL=http://localhost:8000
NEXT_PUBLIC_API_URL=http://localhost:8000
NODE_ENV=test

For more information on specific configurations, see the relevant component documentation.