Skip to main content

Configuration Guide

This guide covers all available configuration options for Chirp, from basic settings to advanced customization.

Environment Variables​

Chirp uses environment variables for configuration. Create a .env file in the server/ directory based on .env.example, or set them directly in your docker-compose.yml for Docker deployments.

Core Settings​

# Application Environment
NODE_ENV=development          # development|production
PORT=3001                     # Server port
CORS_ORIGIN=http://localhost:5173  # Allowed CORS origin (frontend URL)
BASE_URL=http://localhost:5173     # Public base URL of the application

Database Configuration (PostgreSQL)​

DB_HOST=localhost              # Database host
DB_PORT=5432                   # Database port
DB_USER=chirp_dev              # Database username
DB_PASSWORD=chirp_dev_password # Database password
DB_NAME=chirp_dev              # Database name
DB_SSL=false                   # Enable SSL connection

Security Settings​

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

# Limits
MAX_SERVERS_PER_USER=15        # Max servers a user can create/join
MAX_BOTS_PER_USER=3            # Max bot tokens per user

Redis Configuration​

Redis is used for caching and session management.

REDIS_HOST=localhost           # Redis host
REDIS_PORT=6379                # Redis port
REDIS_PASSWORD=                # Redis password (empty for no auth)
REDIS_DB=0                     # Redis database number
REDIS_URL=redis://localhost:6379  # Full Redis connection URL

Email Configuration​

Email is required for registration verification and password resets.

EMAIL_HOST=                    # SMTP server host
EMAIL_PORT=587                 # SMTP server port
EMAIL_USER=                    # SMTP username
EMAIL_PASS=                    # SMTP password
EMAIL_FROM=                    # From email address
EMAIL_FROM_NAME=Chirp          # From display name

Email Providers​

Gmail:

EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your_app_specific_password
EMAIL_FROM=your-email@gmail.com
EMAIL_FROM_NAME=Chirp

Outlook/Office 365:

EMAIL_HOST=smtp-mail.outlook.com
EMAIL_PORT=587

SendGrid:

EMAIL_HOST=smtp.sendgrid.net
EMAIL_PORT=587

Web Push Notifications (VAPID)​

VAPID keys are auto-generated on first run and saved to server/config/vapid-keys.json. You can also set them manually:

VAPID_PUBLIC_KEY=              # Auto-generated if not set
VAPID_PRIVATE_KEY=             # Auto-generated if not set
VAPID_SUBJECT=mailto:admin@your-domain.com

WebRTC TURN Server Configuration​

A TURN server is required for voice channels to work behind NAT/firewalls, especially for Firefox users.

Docker users: Coturn is included in docker-compose.yml. Just set TURN_EXTERNAL_IP to your server's public IP.

Standalone users: Install coturn or use a hosted TURN service:

# Include both UDP and TCP transports (comma-separated) for Firefox compatibility
TURN_SERVER_URLS=turn:your-turn-server.com:3478,turn:your-turn-server.com:3478?transport=tcp
TURN_USERNAME=your-turn-username
TURN_CREDENTIAL=your-turn-password

# Additional TURN servers (comma-separated, optional)
# TURN_SERVER_URLS_2=turn:your-backup-turn-server.com:3478

External API Configuration​

# Tenor API (GIF search)
TENOR_API_KEY=your-tenor-api-key

Docker Configuration​

When using Docker, environment variables are set directly in docker-compose.yml under the chirp service's environment section. The Docker setup includes PostgreSQL, Redis, the Chirp app, and a Coturn TURN server.

Key Docker-specific differences:

  • DB_HOST=postgres (container name instead of localhost)
  • REDIS_HOST=redis (container name instead of localhost)
  • REDIS_URL=redis://redis:6379
  • The app is exposed on port 8080 by default (mapped to internal port 3001)
  • BASE_URL and CORS_ORIGIN should be set to your public-facing URL

See the Docker Deployment Guide for full details.

Need help? Check our troubleshooting guide.