add mintlify intro docs

2025-05-28 23:42:34 +05:30
parent b5ebc47637
commit f429db89b4
19 changed files with 10055 additions and 1 deletions
@@ -0,0 +1,748 @@
+---
+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.