658 lines
12 KiB
Plaintext
658 lines
12 KiB
Plaintext
---
|
|
title: Environment Variables for Development
|
|
description: Complete guide to environment variables for Chatwoot development and testing
|
|
sidebarTitle: Environment Variables
|
|
---
|
|
|
|
# Environment Variables for Development
|
|
|
|
This guide covers environment variables specifically for development and testing environments. For production environment variables, see the [Self-hosted Environment Variables](../../self-hosted/configuration/environment-variables) guide.
|
|
|
|
## Development Environment Setup
|
|
|
|
### Basic Development Configuration
|
|
|
|
Create your `.env` file from the example:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
### Essential Development Variables
|
|
|
|
```bash
|
|
# Rails Environment
|
|
RAILS_ENV=development
|
|
NODE_ENV=development
|
|
|
|
# Application Configuration
|
|
FRONTEND_URL=http://localhost:3000
|
|
FORCE_SSL=false
|
|
SECRET_KEY_BASE=your-secret-key-here
|
|
|
|
# Database Configuration
|
|
DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
|
|
REDIS_URL=redis://localhost:6379/0
|
|
|
|
# Development Features
|
|
ENABLE_DEVELOPMENT_FEATURES=true
|
|
RAILS_LOG_LEVEL=debug
|
|
LOG_LEVEL=debug
|
|
```
|
|
|
|
## Database Configuration
|
|
|
|
### PostgreSQL Settings
|
|
|
|
```bash
|
|
# Primary database connection
|
|
DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_development
|
|
|
|
# Alternative format (individual variables)
|
|
DB_HOST=localhost
|
|
DB_PORT=5432
|
|
DB_USERNAME=chatwoot
|
|
DB_PASSWORD=password
|
|
DB_NAME=chatwoot_development
|
|
|
|
# Test database
|
|
TEST_DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_test
|
|
```
|
|
|
|
### Redis Configuration
|
|
|
|
```bash
|
|
# Redis connection for development
|
|
REDIS_URL=redis://localhost:6379/0
|
|
|
|
# Redis with authentication
|
|
REDIS_URL=redis://:password@localhost:6379/0
|
|
|
|
# Redis Sentinel (for advanced setups)
|
|
REDIS_SENTINELS=localhost:26379
|
|
REDIS_SENTINEL_MASTER_NAME=mymaster
|
|
|
|
# Sidekiq Redis (can be separate)
|
|
SIDEKIQ_REDIS_URL=redis://localhost:6379/1
|
|
```
|
|
|
|
## Email Configuration for Development
|
|
|
|
### Local Email Testing
|
|
|
|
```bash
|
|
# MailHog configuration (recommended for development)
|
|
MAILER_SENDER_EMAIL=dev@chatwoot.local
|
|
SMTP_ADDRESS=localhost
|
|
SMTP_PORT=1025
|
|
SMTP_DOMAIN=chatwoot.local
|
|
SMTP_ENABLE_STARTTLS_AUTO=false
|
|
SMTP_TLS=false
|
|
|
|
# Alternative: Letter Opener (emails open in browser)
|
|
LETTER_OPENER=true
|
|
```
|
|
|
|
### Gmail SMTP (for testing real emails)
|
|
|
|
```bash
|
|
MAILER_SENDER_EMAIL=your-email@gmail.com
|
|
SMTP_ADDRESS=smtp.gmail.com
|
|
SMTP_PORT=587
|
|
SMTP_USERNAME=your-email@gmail.com
|
|
SMTP_PASSWORD=your-app-password
|
|
SMTP_DOMAIN=gmail.com
|
|
SMTP_ENABLE_STARTTLS_AUTO=true
|
|
SMTP_TLS=true
|
|
```
|
|
|
|
### Mailtrap (for testing)
|
|
|
|
```bash
|
|
MAILER_SENDER_EMAIL=dev@chatwoot.local
|
|
SMTP_ADDRESS=smtp.mailtrap.io
|
|
SMTP_PORT=2525
|
|
SMTP_USERNAME=your-mailtrap-username
|
|
SMTP_PASSWORD=your-mailtrap-password
|
|
SMTP_DOMAIN=chatwoot.local
|
|
```
|
|
|
|
## File Storage Configuration
|
|
|
|
### Local Storage (Default for Development)
|
|
|
|
```bash
|
|
ACTIVE_STORAGE_SERVICE=local
|
|
```
|
|
|
|
### AWS S3 for Development
|
|
|
|
```bash
|
|
ACTIVE_STORAGE_SERVICE=amazon
|
|
AWS_ACCESS_KEY_ID=your-access-key
|
|
AWS_SECRET_ACCESS_KEY=your-secret-key
|
|
AWS_REGION=us-east-1
|
|
AWS_BUCKET_NAME=chatwoot-dev-bucket
|
|
```
|
|
|
|
### Google Cloud Storage
|
|
|
|
```bash
|
|
ACTIVE_STORAGE_SERVICE=google
|
|
GCS_PROJECT_ID=your-project-id
|
|
GCS_CREDENTIALS=path/to/credentials.json
|
|
GCS_BUCKET=chatwoot-dev-bucket
|
|
```
|
|
|
|
## Development Features
|
|
|
|
### Debug and Logging
|
|
|
|
```bash
|
|
# Enable development features
|
|
ENABLE_DEVELOPMENT_FEATURES=true
|
|
|
|
# Logging levels
|
|
RAILS_LOG_LEVEL=debug
|
|
LOG_LEVEL=debug
|
|
SIDEKIQ_LOG_LEVEL=debug
|
|
|
|
# SQL query logging
|
|
ACTIVE_RECORD_VERBOSE_QUERY_LOGS=true
|
|
|
|
# Bullet gem for N+1 query detection
|
|
BULLET_ENABLED=true
|
|
```
|
|
|
|
### Performance Monitoring
|
|
|
|
```bash
|
|
# Enable query analysis
|
|
QUERY_ANALYSIS=true
|
|
|
|
# Memory profiling
|
|
MEMORY_PROFILER=true
|
|
|
|
# Rack Mini Profiler
|
|
RACK_MINI_PROFILER=true
|
|
|
|
# Benchmark mode
|
|
BENCHMARK_MODE=true
|
|
```
|
|
|
|
### Code Quality Tools
|
|
|
|
```bash
|
|
# RuboCop configuration
|
|
RUBOCOP_PARALLEL=true
|
|
|
|
# Coverage reporting
|
|
COVERAGE=true
|
|
SIMPLECOV_FORMATTER=html
|
|
|
|
# Test environment
|
|
RSPEC_RETRY_COUNT=3
|
|
PARALLEL_TEST_PROCESSORS=4
|
|
```
|
|
|
|
## Testing Environment Variables
|
|
|
|
### Test Database Configuration
|
|
|
|
```bash
|
|
# Test environment
|
|
RAILS_ENV=test
|
|
|
|
# Test database
|
|
TEST_DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_test
|
|
|
|
# Test Redis
|
|
TEST_REDIS_URL=redis://localhost:6379/15
|
|
|
|
# Disable external services in tests
|
|
DISABLE_EXTERNAL_HTTP=true
|
|
MOCK_EXTERNAL_SERVICES=true
|
|
```
|
|
|
|
### Test-Specific Settings
|
|
|
|
```bash
|
|
# Faster tests
|
|
RAILS_ENV=test
|
|
DISABLE_SPRING=true
|
|
PARALLEL_WORKERS=4
|
|
|
|
# Test coverage
|
|
COVERAGE=true
|
|
COVERAGE_REPORTS=true
|
|
|
|
# Selenium/Capybara configuration
|
|
SELENIUM_REMOTE_URL=http://localhost:4444/wd/hub
|
|
CAPYBARA_SERVER_PORT=3001
|
|
HEADLESS_CHROME=true
|
|
|
|
# Factory Bot settings
|
|
FACTORY_BOT_ALLOW_CLASS_LOOKUP=false
|
|
```
|
|
|
|
## Integration Testing
|
|
|
|
### External Service Mocking
|
|
|
|
```bash
|
|
# Mock external APIs
|
|
MOCK_FACEBOOK_API=true
|
|
MOCK_TWITTER_API=true
|
|
MOCK_WHATSAPP_API=true
|
|
MOCK_TELEGRAM_API=true
|
|
|
|
# Webhook testing
|
|
WEBHOOK_TEST_URL=http://localhost:3000/webhooks/test
|
|
NGROK_TUNNEL_URL=https://your-tunnel.ngrok.io
|
|
```
|
|
|
|
### API Testing
|
|
|
|
```bash
|
|
# API testing configuration
|
|
API_TEST_TOKEN=test-token-123
|
|
API_TEST_ACCOUNT_ID=1
|
|
API_TEST_USER_ID=1
|
|
|
|
# Rate limiting (disabled for tests)
|
|
RATE_LIMITING_ENABLED=false
|
|
```
|
|
|
|
## Development Tools
|
|
|
|
### Code Analysis
|
|
|
|
```bash
|
|
# Brakeman security scanner
|
|
BRAKEMAN_ENABLED=true
|
|
|
|
# Bundle audit
|
|
BUNDLE_AUDIT_ENABLED=true
|
|
|
|
# Reek code smell detector
|
|
REEK_ENABLED=true
|
|
|
|
# Rails Best Practices
|
|
RAILS_BEST_PRACTICES_ENABLED=true
|
|
```
|
|
|
|
### Development Servers
|
|
|
|
```bash
|
|
# Webpack dev server
|
|
WEBPACK_DEV_SERVER_HOST=localhost
|
|
WEBPACK_DEV_SERVER_PORT=3035
|
|
|
|
# Hot module replacement
|
|
HMR_ENABLED=true
|
|
|
|
# Live reload
|
|
LIVE_RELOAD=true
|
|
```
|
|
|
|
## Third-Party Integrations (Development)
|
|
|
|
### Social Media (Test Credentials)
|
|
|
|
```bash
|
|
# Facebook (use test app credentials)
|
|
FB_APP_ID=your-test-app-id
|
|
FB_APP_SECRET=your-test-app-secret
|
|
FB_VERIFY_TOKEN=test-verify-token
|
|
|
|
# Twitter (use test credentials)
|
|
TWITTER_APP_ID=your-test-app-id
|
|
TWITTER_CONSUMER_KEY=your-test-consumer-key
|
|
TWITTER_CONSUMER_SECRET=your-test-consumer-secret
|
|
|
|
# WhatsApp (use test credentials)
|
|
WHATSAPP_VERIFY_TOKEN=test-verify-token
|
|
```
|
|
|
|
### Push Notifications (Development)
|
|
|
|
```bash
|
|
# FCM (use development project)
|
|
FCM_SERVER_KEY=your-dev-server-key
|
|
FCM_PROJECT_ID=your-dev-project-id
|
|
|
|
# Vapid keys for web push
|
|
VAPID_PUBLIC_KEY=your-dev-public-key
|
|
VAPID_PRIVATE_KEY=your-dev-private-key
|
|
```
|
|
|
|
## Security Settings for Development
|
|
|
|
### Authentication
|
|
|
|
```bash
|
|
# JWT settings
|
|
JWT_SECRET_KEY=your-dev-jwt-secret
|
|
JWT_EXPIRY=24h
|
|
|
|
# Session configuration
|
|
SESSION_TIMEOUT=1440
|
|
SECURE_COOKIES=false
|
|
|
|
# CORS settings (permissive for development)
|
|
CORS_ORIGINS=http://localhost:3000,http://localhost:3001
|
|
```
|
|
|
|
### Development Security
|
|
|
|
```bash
|
|
# Disable security features for development
|
|
FORCE_SSL=false
|
|
SECURE_HEADERS=false
|
|
CSP_ENABLED=false
|
|
|
|
# Allow insecure connections
|
|
ALLOW_HTTP=true
|
|
SKIP_SSL_VERIFICATION=true
|
|
```
|
|
|
|
## Environment-Specific Configurations
|
|
|
|
### Development Environment
|
|
|
|
```bash
|
|
# .env.development
|
|
RAILS_ENV=development
|
|
NODE_ENV=development
|
|
CACHE_CLASSES=false
|
|
EAGER_LOAD=false
|
|
CONSIDER_ALL_REQUESTS_LOCAL=true
|
|
ACTION_CONTROLLER_PERFORM_CACHING=false
|
|
```
|
|
|
|
### Test Environment
|
|
|
|
```bash
|
|
# .env.test
|
|
RAILS_ENV=test
|
|
NODE_ENV=test
|
|
CACHE_CLASSES=true
|
|
EAGER_LOAD=false
|
|
PUBLIC_FILE_SERVER_ENABLED=true
|
|
SHOW_EXCEPTIONS=false
|
|
```
|
|
|
|
### Staging Environment
|
|
|
|
```bash
|
|
# .env.staging
|
|
RAILS_ENV=staging
|
|
NODE_ENV=production
|
|
FORCE_SSL=true
|
|
LOG_LEVEL=info
|
|
RAILS_SERVE_STATIC_FILES=true
|
|
```
|
|
|
|
## Docker Development
|
|
|
|
### Docker Compose Variables
|
|
|
|
```bash
|
|
# Docker-specific configuration
|
|
POSTGRES_HOST=postgres
|
|
POSTGRES_PORT=5432
|
|
POSTGRES_USER=postgres
|
|
POSTGRES_PASSWORD=postgres
|
|
POSTGRES_DB=chatwoot
|
|
|
|
REDIS_HOST=redis
|
|
REDIS_PORT=6379
|
|
|
|
# Rails configuration for Docker
|
|
RAILS_ENV=development
|
|
RAILS_MAX_THREADS=5
|
|
WEB_CONCURRENCY=2
|
|
```
|
|
|
|
### Development with Docker
|
|
|
|
```bash
|
|
# Use Docker services
|
|
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/chatwoot_development
|
|
REDIS_URL=redis://redis:6379/0
|
|
|
|
# File permissions (for volume mounts)
|
|
DOCKER_USER_ID=1000
|
|
DOCKER_GROUP_ID=1000
|
|
```
|
|
|
|
## IDE and Editor Configuration
|
|
|
|
### VS Code Settings
|
|
|
|
```bash
|
|
# Ruby LSP configuration
|
|
RUBY_LSP_ENABLED=true
|
|
RUBY_LSP_EXPERIMENTAL_FEATURES=true
|
|
|
|
# Solargraph configuration
|
|
SOLARGRAPH_ENABLED=true
|
|
```
|
|
|
|
### RubyMine Settings
|
|
|
|
```bash
|
|
# RubyMine-specific settings
|
|
RUBYMINE_PROJECT_ROOT=/path/to/chatwoot
|
|
RUBYMINE_RUBY_VERSION=3.3.3
|
|
```
|
|
|
|
## Performance and Monitoring
|
|
|
|
### Development Monitoring
|
|
|
|
```bash
|
|
# New Relic (development license)
|
|
NEW_RELIC_LICENSE_KEY=your-dev-license-key
|
|
NEW_RELIC_APP_NAME=Chatwoot Development
|
|
|
|
# Sentry (development DSN)
|
|
SENTRY_DSN=your-dev-sentry-dsn
|
|
SENTRY_ENVIRONMENT=development
|
|
|
|
# DataDog (development)
|
|
DD_API_KEY=your-dev-datadog-key
|
|
DD_ENV=development
|
|
```
|
|
|
|
### Memory and Performance
|
|
|
|
```bash
|
|
# Memory settings
|
|
RUBY_GC_HEAP_INIT_SLOTS=10000
|
|
RUBY_GC_HEAP_FREE_SLOTS=10000
|
|
RUBY_GC_HEAP_GROWTH_FACTOR=1.1
|
|
|
|
# Puma configuration
|
|
PUMA_WORKERS=1
|
|
PUMA_THREADS=5
|
|
PUMA_PRELOAD_APP=false
|
|
```
|
|
|
|
## Common Development Scenarios
|
|
|
|
### API Development
|
|
|
|
```bash
|
|
# API-specific settings
|
|
API_RATE_LIMIT=1000
|
|
API_RATE_LIMIT_WINDOW=3600
|
|
API_PAGINATION_LIMIT=100
|
|
|
|
# CORS for API development
|
|
API_CORS_ORIGINS=http://localhost:3001,http://localhost:8080
|
|
```
|
|
|
|
### Widget Development
|
|
|
|
```bash
|
|
# Widget development
|
|
WIDGET_BASE_URL=http://localhost:3000
|
|
WIDGET_API_URL=http://localhost:3000/api/v1
|
|
WIDGET_WS_URL=ws://localhost:3000/cable
|
|
```
|
|
|
|
### Mobile App Development
|
|
|
|
```bash
|
|
# Mobile API endpoints
|
|
MOBILE_API_URL=http://localhost:3000/api/v1
|
|
MOBILE_WS_URL=ws://localhost:3000/cable
|
|
|
|
# Push notification testing
|
|
MOBILE_PUSH_ENABLED=true
|
|
```
|
|
|
|
## Troubleshooting Environment Issues
|
|
|
|
### Common Environment Problems
|
|
|
|
<Accordion title="Database connection issues">
|
|
**Problem**: `ActiveRecord::ConnectionNotEstablished`
|
|
|
|
**Check these variables**:
|
|
```bash
|
|
DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_development
|
|
DB_HOST=localhost
|
|
DB_PORT=5432
|
|
```
|
|
|
|
**Verify connection**:
|
|
```bash
|
|
psql $DATABASE_URL -c "SELECT 1;"
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Redis connection issues">
|
|
**Problem**: `Redis::CannotConnectError`
|
|
|
|
**Check these variables**:
|
|
```bash
|
|
REDIS_URL=redis://localhost:6379/0
|
|
```
|
|
|
|
**Verify connection**:
|
|
```bash
|
|
redis-cli -u $REDIS_URL ping
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Email delivery issues">
|
|
**Problem**: Emails not being sent in development
|
|
|
|
**Check these variables**:
|
|
```bash
|
|
MAILER_SENDER_EMAIL=dev@chatwoot.local
|
|
SMTP_ADDRESS=localhost
|
|
SMTP_PORT=1025
|
|
```
|
|
|
|
**For MailHog**:
|
|
```bash
|
|
# Start MailHog
|
|
mailhog
|
|
|
|
# Check web interface at http://localhost:8025
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Asset compilation issues">
|
|
**Problem**: `Webpacker::Manifest::MissingEntryError`
|
|
|
|
**Check these variables**:
|
|
```bash
|
|
NODE_ENV=development
|
|
RAILS_ENV=development
|
|
```
|
|
|
|
**Recompile assets**:
|
|
```bash
|
|
pnpm run dev
|
|
# or
|
|
bundle exec rails assets:precompile
|
|
```
|
|
</Accordion>
|
|
|
|
### Environment Validation
|
|
|
|
Create a script to validate your environment:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# validate_env.sh
|
|
|
|
echo "Validating development environment..."
|
|
|
|
# Check required variables
|
|
required_vars=(
|
|
"RAILS_ENV"
|
|
"DATABASE_URL"
|
|
"REDIS_URL"
|
|
"SECRET_KEY_BASE"
|
|
"FRONTEND_URL"
|
|
)
|
|
|
|
for var in "${required_vars[@]}"; do
|
|
if [ -z "${!var}" ]; then
|
|
echo "❌ Missing required variable: $var"
|
|
else
|
|
echo "✅ $var is set"
|
|
fi
|
|
done
|
|
|
|
# Test database connection
|
|
if bundle exec rails runner "ActiveRecord::Base.connection.execute('SELECT 1')" > /dev/null 2>&1; then
|
|
echo "✅ Database connection successful"
|
|
else
|
|
echo "❌ Database connection failed"
|
|
fi
|
|
|
|
# Test Redis connection
|
|
if bundle exec rails runner "Redis.new.ping" > /dev/null 2>&1; then
|
|
echo "✅ Redis connection successful"
|
|
else
|
|
echo "❌ Redis connection failed"
|
|
fi
|
|
|
|
echo "Environment validation complete!"
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### Environment File Management
|
|
|
|
1. **Never commit `.env` files** to version control
|
|
2. **Use `.env.example`** as a template for required variables
|
|
3. **Document all variables** with comments
|
|
4. **Use different `.env` files** for different environments
|
|
5. **Validate environment** before starting development
|
|
|
|
### Security Considerations
|
|
|
|
1. **Use weak credentials** only in development
|
|
2. **Never use production credentials** in development
|
|
3. **Rotate test API keys** regularly
|
|
4. **Use local services** when possible
|
|
5. **Mock external services** in tests
|
|
|
|
### Performance Tips
|
|
|
|
1. **Use local Redis** for faster development
|
|
2. **Enable query caching** in development
|
|
3. **Use parallel testing** for faster test runs
|
|
4. **Profile memory usage** regularly
|
|
5. **Monitor database queries** for N+1 issues
|
|
|
|
---
|
|
|
|
This guide covers the essential environment variables for Chatwoot development. For production deployment, refer to the [Self-hosted Environment Variables](../../self-hosted/configuration/environment-variables) guide. |