Files
chatwoot/developer-docs/self-hosted/configuration/environment-variables.mdx
T

748 lines
14 KiB
Plaintext

---
title: Environment Variables
description: Complete reference for Chatwoot environment variables and configuration options
sidebarTitle: Environment Variables
---
# Environment Variables Reference
Chatwoot uses environment variables for configuration. This guide provides a comprehensive reference for all available environment variables and their usage.
## Core Application Settings
### Basic Configuration
```bash
# Rails Environment
RAILS_ENV=production
# Node Environment
NODE_ENV=production
# Frontend URL (required)
FRONTEND_URL=https://chatwoot.yourdomain.com
# Force SSL (recommended for production)
FORCE_SSL=true
# Secret Key Base (auto-generated during installation)
SECRET_KEY_BASE=your-secret-key-base
# Rails Log Level
RAILS_LOG_LEVEL=info
# Rails Max Threads
RAILS_MAX_THREADS=5
# Web Concurrency (Puma workers)
WEB_CONCURRENCY=2
```
### Application Behavior
```bash
# Enable/disable account signup
ENABLE_ACCOUNT_SIGNUP=false
# Auto-assign conversations to online agents
AUTO_ASSIGN_CONVERSATIONS=true
# Enable conversation continuity (link conversations across sessions)
CONVERSATION_CONTINUITY=true
# Maximum file upload size (in MB)
MAXIMUM_FILE_UPLOAD_SIZE=40
# Enable IP-based rate limiting
ENABLE_IP_RATE_LIMIT=true
# Rate limit per IP (requests per minute)
IP_RATE_LIMIT=100
```
## Database Configuration
### PostgreSQL
```bash
# Database URL (primary configuration method)
DATABASE_URL=postgresql://username:password@hostname:port/database_name
# Alternative: Individual components
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USERNAME=chatwoot
POSTGRES_PASSWORD=your-password
POSTGRES_DATABASE=chatwoot_production
# Database pool size
DATABASE_POOL_SIZE=5
# Database timeout (seconds)
DATABASE_TIMEOUT=5000
# Enable prepared statements
DATABASE_PREPARED_STATEMENTS=true
```
### Database SSL Configuration
```bash
# SSL Mode (disable, allow, prefer, require, verify-ca, verify-full)
DATABASE_SSL_MODE=require
# SSL Certificate paths (for verify-ca and verify-full modes)
DATABASE_SSL_CERT=/path/to/client-cert.pem
DATABASE_SSL_KEY=/path/to/client-key.pem
DATABASE_SSL_ROOT_CERT=/path/to/ca-cert.pem
```
## Redis Configuration
### Basic Redis Settings
```bash
# Redis URL (primary configuration method)
REDIS_URL=redis://localhost:6379/0
# Alternative: Individual components
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=your-redis-password
# Redis connection pool size
REDIS_POOL_SIZE=5
# Redis timeout (seconds)
REDIS_TIMEOUT=1
```
### Redis SSL Configuration
```bash
# Enable SSL for Redis
REDIS_SSL=true
# Redis SSL certificate verification
REDIS_SSL_VERIFY=true
# Redis SSL certificate paths
REDIS_SSL_CERT=/path/to/redis-client.crt
REDIS_SSL_KEY=/path/to/redis-client.key
REDIS_SSL_CA=/path/to/redis-ca.crt
```
### Sidekiq Configuration
```bash
# Sidekiq concurrency (number of worker threads)
SIDEKIQ_CONCURRENCY=10
# Sidekiq Redis namespace
SIDEKIQ_REDIS_NAMESPACE=chatwoot_sidekiq
# Sidekiq log level
SIDEKIQ_LOG_LEVEL=info
# Enable Sidekiq web UI
SIDEKIQ_WEB_UI=true
# Sidekiq web UI username/password
SIDEKIQ_WEB_USERNAME=admin
SIDEKIQ_WEB_PASSWORD=your-password
```
## Email Configuration
### SMTP Settings
```bash
# Sender email address
MAILER_SENDER_EMAIL=noreply@yourdomain.com
# SMTP server configuration
SMTP_ADDRESS=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_OPENSSL_VERIFY_MODE=peer
# SMTP domain (for HELO command)
SMTP_DOMAIN=yourdomain.com
# Force TLS
SMTP_TLS=true
```
### Email Provider Examples
<Tabs>
<Tab title="Gmail">
```bash
SMTP_ADDRESS=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
```
</Tab>
<Tab title="SendGrid">
```bash
SMTP_ADDRESS=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=your-sendgrid-api-key
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
```
</Tab>
<Tab title="Mailgun">
```bash
SMTP_ADDRESS=smtp.mailgun.org
SMTP_PORT=587
SMTP_USERNAME=postmaster@mg.yourdomain.com
SMTP_PASSWORD=your-mailgun-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
```
</Tab>
<Tab title="AWS SES">
```bash
SMTP_ADDRESS=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=your-ses-username
SMTP_PASSWORD=your-ses-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
```
</Tab>
</Tabs>
### Email Templates
```bash
# Custom email template path
CUSTOM_EMAIL_TEMPLATE_PATH=/path/to/custom/templates
# Email template language
EMAIL_TEMPLATE_LANGUAGE=en
# Enable email tracking
EMAIL_TRACKING_ENABLED=true
# Email delivery method (smtp, sendmail, test)
EMAIL_DELIVERY_METHOD=smtp
```
## File Storage Configuration
### Local Storage
```bash
# Active storage service
ACTIVE_STORAGE_SERVICE=local
# Local storage path
LOCAL_STORAGE_PATH=/home/chatwoot/chatwoot/storage
```
### Amazon S3
```bash
# Active storage service
ACTIVE_STORAGE_SERVICE=amazon
# S3 configuration
S3_BUCKET_NAME=your-chatwoot-bucket
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-east-1
# S3 endpoint (for S3-compatible services)
S3_ENDPOINT=https://s3.amazonaws.com
# S3 force path style (for MinIO and other S3-compatible services)
S3_FORCE_PATH_STYLE=false
# S3 public URL (for CDN)
S3_PUBLIC_URL=https://cdn.yourdomain.com
```
### Google Cloud Storage
```bash
# Active storage service
ACTIVE_STORAGE_SERVICE=google
# GCS configuration
GCS_PROJECT=your-project-id
GCS_BUCKET=your-chatwoot-bucket
# GCS credentials (JSON key file path)
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
# GCS public URL (for CDN)
GCS_PUBLIC_URL=https://cdn.yourdomain.com
```
### Azure Blob Storage
```bash
# Active storage service
ACTIVE_STORAGE_SERVICE=azure
# Azure configuration
AZURE_STORAGE_ACCOUNT_NAME=your-storage-account
AZURE_STORAGE_ACCESS_KEY=your-access-key
AZURE_STORAGE_CONTAINER=your-container-name
# Azure public URL (for CDN)
AZURE_PUBLIC_URL=https://cdn.yourdomain.com
```
## Third-Party Integrations
### Facebook
```bash
# Facebook App ID and Secret
FB_APP_ID=your-facebook-app-id
FB_APP_SECRET=your-facebook-app-secret
# Facebook Verify Token
FB_VERIFY_TOKEN=your-verify-token
# Facebook API Version
FB_API_VERSION=v13.0
```
### Twitter
```bash
# Twitter API credentials
TWITTER_APP_ID=your-twitter-app-id
TWITTER_CONSUMER_KEY=your-consumer-key
TWITTER_CONSUMER_SECRET=your-consumer-secret
TWITTER_ENVIRONMENT=your-twitter-environment
```
### Slack
```bash
# Slack App credentials
SLACK_CLIENT_ID=your-slack-client-id
SLACK_CLIENT_SECRET=your-slack-client-secret
```
### Google OAuth
```bash
# Google OAuth credentials
GOOGLE_OAUTH_CLIENT_ID=your-google-client-id
GOOGLE_OAUTH_CLIENT_SECRET=your-google-client-secret
```
### Microsoft OAuth
```bash
# Microsoft OAuth credentials
MICROSOFT_APP_ID=your-microsoft-app-id
MICROSOFT_APP_SECRET=your-microsoft-app-secret
```
## Push Notifications
### FCM (Firebase Cloud Messaging)
```bash
# FCM Server Key
FCM_SERVER_KEY=your-fcm-server-key
# FCM Project ID
FCM_PROJECT_ID=your-firebase-project-id
# FCM credentials file
GOOGLE_APPLICATION_CREDENTIALS=/path/to/firebase-service-account.json
```
### Vapid Keys (Web Push)
```bash
# Vapid public and private keys
VAPID_PUBLIC_KEY=your-vapid-public-key
VAPID_PRIVATE_KEY=your-vapid-private-key
# Vapid subject (email or URL)
VAPID_SUBJECT=mailto:admin@yourdomain.com
```
## Analytics and Monitoring
### Application Monitoring
```bash
# Enable application metrics
ENABLE_METRICS=true
# Metrics endpoint path
METRICS_PATH=/metrics
# Prometheus exporter
PROMETHEUS_EXPORTER=true
PROMETHEUS_EXPORTER_PORT=9394
# New Relic
NEW_RELIC_LICENSE_KEY=your-newrelic-license-key
NEW_RELIC_APP_NAME=Chatwoot
# Sentry error tracking
SENTRY_DSN=your-sentry-dsn
```
### Google Analytics
```bash
# Google Analytics tracking ID
GOOGLE_ANALYTICS_ID=UA-XXXXXXXXX-X
# Google Tag Manager ID
GOOGLE_TAG_MANAGER_ID=GTM-XXXXXXX
```
### Hotjar
```bash
# Hotjar site ID
HOTJAR_SITE_ID=your-hotjar-site-id
```
## Security Configuration
### Authentication
```bash
# JWT secret key
JWT_SECRET_KEY=your-jwt-secret-key
# Session timeout (in seconds)
SESSION_TIMEOUT=86400
# Password minimum length
PASSWORD_MIN_LENGTH=8
# Enable two-factor authentication
ENABLE_2FA=true
# TOTP issuer name
TOTP_ISSUER_NAME=Chatwoot
```
### CORS Configuration
```bash
# Allowed origins for CORS
CORS_ORIGINS=https://yourdomain.com,https://www.yourdomain.com
# Enable CORS credentials
CORS_CREDENTIALS=true
```
### Content Security Policy
```bash
# Enable CSP
ENABLE_CSP=true
# CSP report URI
CSP_REPORT_URI=/csp-report
# CSP directives
CSP_DEFAULT_SRC='self'
CSP_SCRIPT_SRC='self' 'unsafe-inline' 'unsafe-eval'
CSP_STYLE_SRC='self' 'unsafe-inline'
```
## Performance Configuration
### Caching
```bash
# Enable caching
ENABLE_CACHING=true
# Cache store (memory_store, redis_cache_store)
CACHE_STORE=redis_cache_store
# Cache namespace
CACHE_NAMESPACE=chatwoot_cache
# Cache TTL (seconds)
CACHE_TTL=3600
```
### Rate Limiting
```bash
# Enable rate limiting
ENABLE_RATE_LIMITING=true
# Rate limit store (memory_store, redis_store)
RATE_LIMIT_STORE=redis_store
# API rate limit (requests per minute)
API_RATE_LIMIT=100
# Login rate limit (attempts per minute)
LOGIN_RATE_LIMIT=5
```
### Asset Configuration
```bash
# Asset host (for CDN)
ASSET_HOST=https://cdn.yourdomain.com
# Enable asset compression
ENABLE_ASSET_COMPRESSION=true
# Asset cache TTL (seconds)
ASSET_CACHE_TTL=31536000
```
## Development and Testing
### Development Settings
```bash
# Enable development features
ENABLE_DEVELOPMENT_FEATURES=false
# Development email delivery
DEVELOPMENT_EMAIL_DELIVERY=true
# Development file storage
DEVELOPMENT_FILE_STORAGE=local
# Enable SQL logging
ENABLE_SQL_LOGGING=false
```
### Testing Configuration
```bash
# Test database URL
TEST_DATABASE_URL=postgresql://username:password@localhost/chatwoot_test
# Test Redis URL
TEST_REDIS_URL=redis://localhost:6379/1
# Enable test coverage
ENABLE_TEST_COVERAGE=true
# Test email delivery
TEST_EMAIL_DELIVERY=test
```
## Logging Configuration
### Log Settings
```bash
# Log level (debug, info, warn, error, fatal)
LOG_LEVEL=info
# Log format (text, json)
LOG_FORMAT=text
# Log to stdout
LOG_TO_STDOUT=true
# Log file path
LOG_FILE_PATH=/var/log/chatwoot/chatwoot.log
# Log rotation
LOG_ROTATION=daily
LOG_RETENTION=30
```
### Structured Logging
```bash
# Enable structured logging
ENABLE_STRUCTURED_LOGGING=true
# Log correlation ID
LOG_CORRELATION_ID=true
# Log request ID
LOG_REQUEST_ID=true
# Log user context
LOG_USER_CONTEXT=true
```
## Feature Flags
### Experimental Features
```bash
# Enable experimental features
ENABLE_EXPERIMENTAL_FEATURES=false
# Feature flags
FEATURE_FLAG_CONVERSATION_CONTINUITY=true
FEATURE_FLAG_AUTO_RESOLVE=false
FEATURE_FLAG_CUSTOM_ATTRIBUTES=true
FEATURE_FLAG_TEAM_MANAGEMENT=true
```
## Webhook Configuration
```bash
# Webhook URL for external integrations
WEBHOOK_URL=https://your-webhook-endpoint.com/chatwoot
# Webhook secret for verification
WEBHOOK_SECRET=your-webhook-secret
# Webhook timeout (seconds)
WEBHOOK_TIMEOUT=30
# Webhook retry attempts
WEBHOOK_RETRY_ATTEMPTS=3
```
## Custom Branding
```bash
# Custom brand name
BRAND_NAME=Your Company
# Custom logo URL
BRAND_LOGO_URL=https://yourdomain.com/logo.png
# Custom favicon URL
BRAND_FAVICON_URL=https://yourdomain.com/favicon.ico
# Custom primary color
BRAND_PRIMARY_COLOR=#1f93ff
# Custom secondary color
BRAND_SECONDARY_COLOR=#f0f0f0
```
## Environment-Specific Examples
### Production Environment
```bash
# Production .env example
RAILS_ENV=production
NODE_ENV=production
FRONTEND_URL=https://chat.yourcompany.com
FORCE_SSL=true
SECRET_KEY_BASE=your-production-secret-key
# Database
DATABASE_URL=postgresql://chatwoot:secure-password@db.yourcompany.com:5432/chatwoot_production
# Redis
REDIS_URL=redis://redis.yourcompany.com:6379/0
# Email
MAILER_SENDER_EMAIL=noreply@yourcompany.com
SMTP_ADDRESS=smtp.yourcompany.com
SMTP_PORT=587
SMTP_USERNAME=noreply@yourcompany.com
SMTP_PASSWORD=your-smtp-password
# Storage
ACTIVE_STORAGE_SERVICE=amazon
S3_BUCKET_NAME=yourcompany-chatwoot
AWS_ACCESS_KEY_ID=your-aws-key
AWS_SECRET_ACCESS_KEY=your-aws-secret
AWS_REGION=us-east-1
# Security
ENABLE_2FA=true
ENABLE_RATE_LIMITING=true
CORS_ORIGINS=https://yourcompany.com
# Monitoring
SENTRY_DSN=your-sentry-dsn
NEW_RELIC_LICENSE_KEY=your-newrelic-key
```
### Development Environment
```bash
# Development .env example
RAILS_ENV=development
NODE_ENV=development
FRONTEND_URL=http://localhost:3000
FORCE_SSL=false
# Database
DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
# Redis
REDIS_URL=redis://localhost:6379/0
# Email (development)
MAILER_SENDER_EMAIL=dev@localhost
EMAIL_DELIVERY_METHOD=test
# Storage (local)
ACTIVE_STORAGE_SERVICE=local
# Development features
ENABLE_DEVELOPMENT_FEATURES=true
ENABLE_SQL_LOGGING=true
LOG_LEVEL=debug
```
## Validation and Best Practices
### Required Variables
<Warning>
These environment variables are required for Chatwoot to function properly:
- `FRONTEND_URL`
- `SECRET_KEY_BASE`
- `DATABASE_URL` or individual database components
- `REDIS_URL` or individual Redis components
</Warning>
### Security Best Practices
<Tip>
**Security Recommendations:**
- Use strong, unique passwords for all services
- Enable SSL/TLS for all external connections
- Use environment-specific secret keys
- Enable rate limiting and CORS protection
- Regularly rotate API keys and passwords
- Use managed services for databases when possible
</Tip>
### Performance Optimization
<Note>
**Performance Tips:**
- Adjust `SIDEKIQ_CONCURRENCY` based on your server resources
- Use Redis for caching and session storage
- Configure CDN for static assets
- Enable compression and caching
- Monitor and adjust database pool sizes
</Note>
---
This comprehensive environment variables reference covers all aspects of Chatwoot configuration. Customize these settings based on your specific deployment requirements and infrastructure setup.