akadmin/chatwoot
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

remove developer docs files

Browse Source
This commit is contained in:
Tanmay Deep Sharma
2025-06-08 18:17:13 +05:30
parent f24514433b
commit 806ddaa9ab
19 changed files with 1 additions and 10055 deletions
Download Patch File Download Diff File Expand all files Collapse all files
developer-docs/contributing/environment-setup/local-development.mdx
-588
View File
@@ -1,588 +0,0 @@
---
title: Local Development Setup
description: Set up Chatwoot for local development on your machine
sidebarTitle: Local Development
---
# Local Development Setup
This guide will help you set up Chatwoot for local development on your machine. Follow these steps to get a complete development environment running.
## Prerequisites
Before setting up Chatwoot locally, ensure you have the following installed:
### Required Software
<CardGroup cols={2}>
<Card title="Ruby" icon="gem">
Ruby 3.3.3 (managed with rbenv or RVM)
</Card>
<Card title="Node.js" icon="node-js">
Node.js 20+ with pnpm package manager
</Card>
<Card title="PostgreSQL" icon="database">
PostgreSQL 13+ for the database
</Card>
<Card title="Redis" icon="redis">
Redis 6+ for caching and background jobs
</Card>
</CardGroup>
### System Dependencies
<Tabs>
<Tab title="macOS">
```bash
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install dependencies
brew install postgresql@15 redis imagemagick git
# Install rbenv for Ruby version management
brew install rbenv ruby-build
# Install Node.js and pnpm
brew install node
npm install -g pnpm
# Start services
brew services start postgresql@15
brew services start redis
```
</Tab>
<Tab title="Ubuntu/Debian">
```bash
# Update package list
sudo apt update
# Install dependencies
sudo apt install -y curl git build-essential libssl-dev libreadline-dev \
zlib1g-dev libpq-dev imagemagick libmagickwand-dev libffi-dev \
postgresql postgresql-contrib redis-server
# Install rbenv
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
# Install Node.js (using NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Install pnpm
npm install -g pnpm
# Start services
sudo systemctl start postgresql
sudo systemctl start redis-server
sudo systemctl enable postgresql
sudo systemctl enable redis-server
```
</Tab>
<Tab title="CentOS/RHEL">
```bash
# Install EPEL repository
sudo yum install -y epel-release
# Install dependencies
sudo yum groupinstall -y "Development Tools"
sudo yum install -y curl git openssl-devel readline-devel zlib-devel \
postgresql-devel ImageMagick-devel libffi-devel postgresql-server \
postgresql-contrib redis
# Initialize PostgreSQL
sudo postgresql-setup initdb
# Install rbenv
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
# Install Node.js
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs
# Install pnpm
npm install -g pnpm
# Start services
sudo systemctl start postgresql
sudo systemctl start redis
sudo systemctl enable postgresql
sudo systemctl enable redis
```
</Tab>
</Tabs>
## Ruby Setup
### Install Ruby with rbenv
```bash
# Add rbenv to your shell profile
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
# Install Ruby 3.3.3
rbenv install 3.3.3
rbenv global 3.3.3
# Verify installation
ruby --version
# Should output: ruby 3.3.3
# Install bundler
gem install bundler
```
### Alternative: Using RVM
```bash
# Install RVM
curl -sSL https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm
# Install Ruby 3.3.3
rvm install 3.3.3
rvm use 3.3.3 --default
# Verify installation
ruby --version
gem install bundler
```
## Database Setup
### PostgreSQL Configuration
```bash
# Create PostgreSQL user (macOS with Homebrew)
createuser -s chatwoot
# Create PostgreSQL user (Linux)
sudo -u postgres createuser -s chatwoot
# Set password for the user
sudo -u postgres psql
postgres=# ALTER USER chatwoot PASSWORD 'password';
postgres=# \q
# Create databases
createdb chatwoot_development
createdb chatwoot_test
```
### PostgreSQL Authentication Setup
Edit PostgreSQL configuration to allow local connections:
```bash
# Find pg_hba.conf location
sudo -u postgres psql -c "SHOW hba_file;"
# Edit the file (example path)
sudo nano /etc/postgresql/15/main/pg_hba.conf
# Add or modify these lines:
local all chatwoot md5
host all chatwoot 127.0.0.1/32 md5
host all chatwoot ::1/128 md5
# Restart PostgreSQL
sudo systemctl restart postgresql
```
## Project Setup
### Clone the Repository
```bash
# Fork the repository on GitHub first, then clone your fork
git clone https://github.com/YOUR_USERNAME/chatwoot.git
cd chatwoot
# Add upstream remote
git remote add upstream https://github.com/chatwoot/chatwoot.git
# Verify remotes
git remote -v
```
### Install Dependencies
```bash
# Install Ruby dependencies
bundle install
# Install Node.js dependencies
pnpm install
# Install Playwright for E2E tests (optional)
pnpm exec playwright install
```
### Environment Configuration
```bash
# Copy environment file
cp .env.example .env
# Edit the environment file
nano .env
```
Update the `.env` file with your local configuration:
```bash
# Database configuration
DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
REDIS_URL=redis://localhost:6379/0
# Application settings
FRONTEND_URL=http://localhost:3000
FORCE_SSL=false
RAILS_ENV=development
NODE_ENV=development
# Email configuration (for development)
MAILER_SENDER_EMAIL=dev@chatwoot.local
SMTP_ADDRESS=localhost
SMTP_PORT=1025
# File storage (local)
ACTIVE_STORAGE_SERVICE=local
# Development features
ENABLE_DEVELOPMENT_FEATURES=true
LOG_LEVEL=debug
```
### Database Initialization
```bash
# Create and migrate the database
bundle exec rails db:create
bundle exec rails db:migrate
# Seed the database with sample data
bundle exec rails db:seed
# Prepare the test database
RAILS_ENV=test bundle exec rails db:create
RAILS_ENV=test bundle exec rails db:migrate
```
## Running the Application
### Start Development Servers
You'll need to run multiple processes for full development:
#### Option 1: Using Foreman (Recommended)
```bash
# Install foreman
gem install foreman
# Start all services
foreman start -f Procfile.dev
```
#### Option 2: Manual Process Management
Open multiple terminal windows/tabs:
```bash
# Terminal 1: Rails server
bundle exec rails server -p 3000
# Terminal 2: Webpack dev server
pnpm run dev
# Terminal 3: Sidekiq worker
bundle exec sidekiq
# Terminal 4: MailHog (for email testing)
mailhog
```
### Access the Application
Once all services are running:
- **Web Application**: http://localhost:3000
- **API Documentation**: http://localhost:3000/swagger
- **Sidekiq Web UI**: http://localhost:3000/sidekiq
- **MailHog (Email)**: http://localhost:8025
### Default Login Credentials
After seeding the database, you can log in with:
- **Email**: john@acme.inc
- **Password**: Password1!
## Development Tools
### Code Quality Tools
```bash
# Install development gems
bundle install --with development test
# Run RuboCop (Ruby linter)
bundle exec rubocop
# Run RuboCop with auto-fix
bundle exec rubocop -a
# Run ESLint (JavaScript linter)
pnpm run lint
# Run ESLint with auto-fix
pnpm run lint:fix
# Run Prettier (code formatter)
pnpm run format
```
### Testing
```bash
# Run Ruby tests
bundle exec rspec
# Run specific test file
bundle exec rspec spec/models/user_spec.rb
# Run JavaScript tests
pnpm run test
# Run E2E tests
pnpm run test:e2e
# Run tests with coverage
COVERAGE=true bundle exec rspec
```
### Database Operations
```bash
# Reset database
bundle exec rails db:drop db:create db:migrate db:seed
# Generate migration
bundle exec rails generate migration AddColumnToTable column:type
# Run migrations
bundle exec rails db:migrate
# Rollback migration
bundle exec rails db:rollback
# Check migration status
bundle exec rails db:migrate:status
```
## IDE and Editor Setup
### VS Code Configuration
Create `.vscode/settings.json`:
```json
{
"ruby.intellisense": "rubyLocate",
"ruby.codeCompletion": "rcodetools",
"ruby.format": "rubocop",
"editor.formatOnSave": true,
"editor.rulers": [120],
"files.trimTrailingWhitespace": true,
"files.insertFinalNewline": true,
"eslint.autoFixOnSave": true,
"prettier.requireConfig": true
}
```
### Recommended VS Code Extensions
```json
{
"recommendations": [
"rebornix.ruby",
"wingrunr21.vscode-ruby",
"bradlc.vscode-tailwindcss",
"esbenp.prettier-vscode",
"dbaeumer.vscode-eslint",
"ms-vscode.vscode-typescript-next",
"bradlc.vscode-tailwindcss"
]
}
```
### RubyMine Configuration
1. Open the project in RubyMine
2. Configure Ruby SDK: File → Project Structure → SDKs
3. Set up database connection in Database tool window
4. Configure code style: File → Settings → Editor → Code Style
## Debugging
### Rails Debugging
```ruby
# Add to your code for debugging
binding.pry
# Or use the built-in debugger
debugger
```
### JavaScript Debugging
```javascript
// Add to your code
console.log('Debug info:', variable);
debugger;
```
### Database Debugging
```bash
# Rails console
bundle exec rails console
# Database console
bundle exec rails dbconsole
# Check database queries in logs
tail -f log/development.log | grep SQL
```
## Common Issues and Solutions
### Bundle Install Issues
<Accordion title="pg gem installation fails">
```bash
# macOS
brew install postgresql
bundle config build.pg --with-pg-config=/usr/local/bin/pg_config
# Ubuntu/Debian
sudo apt-get install libpq-dev
bundle install
```
</Accordion>
<Accordion title="ImageMagick issues">
```bash
# macOS
brew install imagemagick pkg-config
# Ubuntu/Debian
sudo apt-get install libmagickwand-dev
# Then reinstall the gem
bundle pristine rmagick
```
</Accordion>
### Node.js Issues
<Accordion title="pnpm install fails">
```bash
# Clear cache and reinstall
pnpm store prune
rm -rf node_modules
pnpm install
```
</Accordion>
<Accordion title="Webpack compilation errors">
```bash
# Clear webpack cache
rm -rf tmp/cache/webpacker
pnpm run dev
```
</Accordion>
### Database Issues
<Accordion title="Database connection refused">
```bash
# Check if PostgreSQL is running
sudo systemctl status postgresql
# Start PostgreSQL if not running
sudo systemctl start postgresql
# Check connection
psql -U chatwoot -d chatwoot_development -h localhost
```
</Accordion>
<Accordion title="Permission denied for database">
```bash
# Reset PostgreSQL user password
sudo -u postgres psql
postgres=# ALTER USER chatwoot PASSWORD 'password';
postgres=# \q
```
</Accordion>
## Performance Optimization
### Development Performance Tips
```bash
# Use spring for faster Rails commands
bundle exec spring binstub --all
# Use bootsnap for faster boot times (already included)
# Ensure tmp/cache directory exists
mkdir -p tmp/cache
# Use parallel testing
bundle exec rspec --parallel
# Optimize database queries
# Add to config/environments/development.rb
config.active_record.verbose_query_logs = true
```
### Memory Usage Optimization
```bash
# Monitor memory usage
ps aux | grep ruby
ps aux | grep node
# Use jemalloc for better memory management
export MALLOC_ARENA_MAX=2
bundle exec rails server
```
## Next Steps
Once you have your development environment set up:
1. **Read the Contributing Guidelines**: Check out the [contributing guide](../introduction) for code standards and workflow
2. **Explore the Codebase**: Familiarize yourself with the project structure
3. **Pick an Issue**: Look for "good first issue" labels on GitHub
4. **Join the Community**: Connect with other contributors on Discord or GitHub Discussions
## Getting Help
If you encounter issues during setup:
- **GitHub Issues**: Search existing issues or create a new one
- **Discord Community**: Join the Chatwoot Discord server
- **Documentation**: Check the official documentation
- **Stack Overflow**: Search for Chatwoot-related questions
---
You're now ready to start contributing to Chatwoot! The development environment should be fully functional and ready for coding.
developer-docs/contributing/introduction.mdx
-322
View File
@@ -1,322 +0,0 @@
---
title: Contributing to Chatwoot
description: Complete guide to contributing to Chatwoot - from setting up your development environment to submitting pull requests.
sidebarTitle: Introduction
---
Thank you for your interest in contributing to Chatwoot! This guide will help you get started with contributing to our open-source customer support platform. Whether you're fixing bugs, adding features, or improving documentation, your contributions are valuable to the community.
## Why Contribute to Chatwoot?
Contributing to Chatwoot offers many benefits:
- **Learn and Grow**: Work with modern technologies like Ruby on Rails, Vue.js, and PostgreSQL
- **Make an Impact**: Help thousands of businesses improve their customer support
- **Build Your Portfolio**: Showcase your contributions to a popular open-source project
- **Join the Community**: Connect with developers and users from around the world
- **Give Back**: Support the open-source ecosystem
## Ways to Contribute
There are many ways to contribute to Chatwoot:
### 🐛 Bug Reports and Fixes
- Report bugs you encounter
- Fix existing bugs in the codebase
- Improve error handling and edge cases
### ✨ Feature Development
- Implement new features
- Enhance existing functionality
- Improve user experience
### 📚 Documentation
- Improve existing documentation
- Write new guides and tutorials
- Translate documentation to other languages
### 🧪 Testing
- Write unit and integration tests
- Perform manual testing
- Improve test coverage
### 🎨 Design and UX
- Improve user interface design
- Enhance user experience
- Create mockups and prototypes
### 🌍 Localization
- Translate Chatwoot to new languages
- Improve existing translations
- Help with internationalization
## Getting Started
### Prerequisites
Before you start contributing, make sure you have:
- **Git**: Version control system
- **GitHub Account**: For submitting pull requests
- **Development Environment**: See our environment setup guides
- **Basic Knowledge**: Familiarity with Ruby, JavaScript, or the technology you want to work with
### Development Workflow
Our development workflow follows these steps:
1. **Find an Issue**: Look for issues tagged with "Good first issue" or create a new one
2. **Fork the Repository**: Create your own copy of the Chatwoot repository
3. **Create a Branch**: Make a feature branch for your changes
4. **Make Changes**: Implement your fix or feature
5. **Test Your Changes**: Ensure everything works correctly
6. **Submit a Pull Request**: Open a PR with a clear description
7. **Code Review**: Collaborate with maintainers to refine your changes
8. **Merge**: Your contribution becomes part of Chatwoot!
## Before You Start
### 1. Check Existing Issues
Before starting work, check if someone else is already working on the same issue:
- Browse [open issues](https://github.com/chatwoot/chatwoot/issues)
- Look for issues labeled "Good first issue" for beginners
- Check if there's an existing pull request for the same feature
### 2. Create or Comment on an Issue
- **For new features**: Create an issue to discuss the feature before implementing
- **For existing issues**: Comment that you'd like to work on it
- **Wait for assignment**: This helps avoid duplicate work
### 3. Understand the Codebase
Familiarize yourself with:
- **Architecture**: How Chatwoot is structured
- **Coding Standards**: Our style guides and conventions
- **Testing Practices**: How we write and run tests
## Pull Request Guidelines
### Branch Naming
Use descriptive branch names that follow our conventions:
```bash
# Feature branches
feature/issue-id-short-description
feature/235-contact-panel
# Bug fix branches
fix/issue-id-short-description
fix/123-email-validation
# Chore branches
chore/update-dependencies
chore/improve-documentation
```
### Commit Messages
Write clear, descriptive commit messages:
```bash
# Good commit messages
feat: Add contact search functionality (#235)
fix: Resolve email validation issue (#123)
docs: Update installation guide
test: Add unit tests for contact model
# Avoid
Update stuff
Fix bug
WIP
```
### Pull Request Template
When creating a pull request, include:
**Description:**
- Clear description of what the PR does
- Link to related issues
- Screenshots for UI changes
**Testing:**
- How you tested the changes
- Test cases covered
- Any manual testing performed
**Checklist:**
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes (or clearly documented)
### Example Pull Request
```markdown
## Description
Adds a new contact search feature that allows agents to quickly find contacts by name, email, or phone number.
Fixes #235
## Changes Made
- Added search input to contact panel
- Implemented backend search API
- Added debounced search functionality
- Updated contact list component
## Testing
- Added unit tests for search API
- Tested search with various input types
- Verified performance with large contact lists
- Manual testing on different browsers
## Screenshots
[Include screenshots of the new feature]
## Checklist
- [x] Code follows style guidelines
- [x] Self-review completed
- [x] Tests added
- [x] Documentation updated
- [x] No breaking changes
```
## Code Standards
### Ruby/Rails Standards
- Follow [Ruby Style Guide](https://rubystyle.guide/)
- Use [RuboCop](https://github.com/rubocop/rubocop) for linting
- Write descriptive method and variable names
- Add comments for complex logic
- Follow Rails conventions
### JavaScript/Vue.js Standards
- Follow [JavaScript Standard Style](https://standardjs.com/)
- Use [ESLint](https://eslint.org/) for linting
- Write modular, reusable components
- Use meaningful component and variable names
- Follow Vue.js best practices
### Testing Standards
- Write tests for new features
- Maintain or improve test coverage
- Use descriptive test names
- Test both happy path and edge cases
- Mock external dependencies
## Development Environment
Choose your preferred development environment:
<CardGroup cols={2}>
<Card title="macOS Setup" icon="apple" href="/contributing/environment-setup/macos">
Set up development environment on macOS
</Card>
<Card title="Ubuntu Setup" icon="ubuntu" href="/contributing/environment-setup/ubuntu">
Set up development environment on Ubuntu Linux
</Card>
<Card title="Windows Setup" icon="windows" href="/contributing/environment-setup/windows">
Set up development environment on Windows
</Card>
<Card title="Docker Setup" icon="docker" href="/contributing/environment-setup/docker">
Use Docker for consistent development environment
</Card>
</CardGroup>
## Issue Labels
Understanding our issue labels helps you find the right issues to work on:
| Label | Description |
|-------|-------------|
| `good first issue` | Perfect for new contributors |
| `help wanted` | Community help needed |
| `bug` | Something isn't working |
| `enhancement` | New feature or improvement |
| `documentation` | Documentation improvements |
| `question` | Further information requested |
| `wontfix` | This will not be worked on |
| `duplicate` | This issue already exists |
## Community Guidelines
### Be Respectful
- Treat everyone with respect and kindness
- Be patient with new contributors
- Provide constructive feedback
- Help others learn and grow
### Communication
- Use clear, concise language
- Ask questions when unsure
- Share knowledge and resources
- Be responsive to feedback
### Collaboration
- Work together towards common goals
- Share credit for collaborative work
- Help review others' contributions
- Mentor new contributors
## Getting Help
If you need help while contributing:
### Documentation
- Read our comprehensive guides
- Check the API documentation
- Review existing code examples
### Community Support
- **Discord**: [Join our community chat](https://discord.gg/cJXdrwS)
- **GitHub Discussions**: [Ask questions and share ideas](https://github.com/chatwoot/chatwoot/discussions)
- **Issues**: Create an issue for bugs or feature requests
### Maintainer Support
- Tag maintainers in issues or PRs when needed
- Be patient - maintainers are volunteers
- Provide detailed information when asking for help
## Recognition
We value all contributions and recognize contributors in several ways:
- **Contributors Page**: Listed on our website and README
- **Release Notes**: Mentioned in release announcements
- **Social Media**: Highlighted on our social channels
- **Swag**: Occasional contributor swag for significant contributions
## Code of Conduct
All contributors must follow our [Code of Conduct](https://github.com/chatwoot/chatwoot/blob/develop/CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for everyone.
## Next Steps
Ready to start contributing? Here's what to do next:
1. **Set up your development environment** using one of our setup guides
2. **Find a good first issue** to work on
3. **Fork the repository** and create a feature branch
4. **Make your changes** following our guidelines
5. **Submit a pull request** with a clear description
---
<Note>
Remember, contributing to open source is a learning process. Don't be afraid to ask questions, make mistakes, and learn from the community. Every contribution, no matter how small, makes a difference!
</Note>
<Tip>
Start small with documentation improvements or bug fixes to get familiar with the codebase and contribution process before tackling larger features.
</Tip>
developer-docs/contributing/project-setup/common-errors.mdx
-1004
View File
File diff suppressed because it is too large Load Diff
developer-docs/contributing/project-setup/environment-variables.mdx
-658
View File
@@ -1,658 +0,0 @@
---
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.
developer-docs/contributing/project-setup/setup-guide.mdx
-589
View File
@@ -1,589 +0,0 @@
---
title: Project Setup Guide
description: Complete guide to setting up Chatwoot for development and contribution
sidebarTitle: Setup Guide
---
# Project Setup Guide
This comprehensive guide will walk you through setting up Chatwoot for development, from initial repository setup to running your first successful build.
## Prerequisites Check
Before starting, ensure you have completed the [Local Development Setup](../environment-setup/local-development) guide and have all required dependencies installed.
### Quick Prerequisites Verification
```bash
# Check Ruby version (should be 3.3.3)
ruby --version
# Check Node.js version (should be 20+)
node --version
# Check PostgreSQL
psql --version
# Check Redis
redis-cli --version
# Check Git
git --version
```
## Repository Setup
### 1. Fork and Clone
```bash
# Fork the repository on GitHub first
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/chatwoot.git
cd chatwoot
# Add upstream remote for syncing
git remote add upstream https://github.com/chatwoot/chatwoot.git
# Verify remotes
git remote -v
# Should show:
# origin https://github.com/YOUR_USERNAME/chatwoot.git (fetch)
# origin https://github.com/YOUR_USERNAME/chatwoot.git (push)
# upstream https://github.com/chatwoot/chatwoot.git (fetch)
# upstream https://github.com/chatwoot/chatwoot.git (push)
```
### 2. Branch Strategy
```bash
# Create a development branch
git checkout -b develop
# For feature work, create feature branches
git checkout -b feature/your-feature-name
# Keep your fork synced
git fetch upstream
git checkout develop
git merge upstream/develop
git push origin develop
```
## Environment Configuration
### 1. Environment File Setup
```bash
# Copy the example environment file
cp .env.example .env
# Open the file for editing
nano .env
```
### 2. Basic Configuration
Update your `.env` file with the following essential settings:
```bash
# Rails Environment
RAILS_ENV=development
NODE_ENV=development
# Application URLs
FRONTEND_URL=http://localhost:3000
FORCE_SSL=false
# Database Configuration
DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
REDIS_URL=redis://localhost:6379/0
# Email Configuration (for development)
MAILER_SENDER_EMAIL=dev@chatwoot.local
SMTP_ADDRESS=localhost
SMTP_PORT=1025
# File Storage
ACTIVE_STORAGE_SERVICE=local
# Development Features
ENABLE_DEVELOPMENT_FEATURES=true
LOG_LEVEL=debug
RAILS_LOG_LEVEL=debug
# Disable SSL in development
SMTP_ENABLE_STARTTLS_AUTO=false
SMTP_TLS=false
```
### 3. Generate Secret Keys
```bash
# Generate secret key base
bundle exec rails secret
# Add to your .env file
echo "SECRET_KEY_BASE=your-generated-secret" >> .env
```
## Database Setup
### 1. Database Creation
```bash
# Create development and test databases
bundle exec rails db:create
# Expected output:
# Created database 'chatwoot_development'
# Created database 'chatwoot_test'
```
### 2. Database Migration
```bash
# Run database migrations
bundle exec rails db:migrate
# Check migration status
bundle exec rails db:migrate:status
```
### 3. Database Seeding
```bash
# Seed the database with sample data
bundle exec rails db:seed
# This creates:
# - Sample account
# - Admin user
# - Sample conversations
# - Test data for development
```
### 4. Test Database Setup
```bash
# Prepare test database
RAILS_ENV=test bundle exec rails db:create
RAILS_ENV=test bundle exec rails db:migrate
```
## Dependency Installation
### 1. Ruby Dependencies
```bash
# Install Ruby gems
bundle install
# If you encounter issues, try:
bundle install --retry=3
# For development and test gems
bundle install --with development test
```
### 2. Node.js Dependencies
```bash
# Install Node.js packages
pnpm install
# If pnpm is not available, install it first:
npm install -g pnpm
# Clear cache if needed
pnpm store prune
```
### 3. Additional Tools
```bash
# Install Foreman for process management
gem install foreman
# Install MailHog for email testing (optional)
# macOS
brew install mailhog
# Ubuntu/Debian
sudo apt-get install mailhog
# Or download binary from GitHub releases
```
## Application Startup
### 1. Using Foreman (Recommended)
```bash
# Start all services with Foreman
foreman start -f Procfile.dev
# This starts:
# - Rails server (port 3000)
# - Webpack dev server
# - Sidekiq worker
```
### 2. Manual Startup
If you prefer to run services separately:
```bash
# Terminal 1: Rails server
bundle exec rails server -p 3000
# Terminal 2: Webpack dev server
pnpm run dev
# Terminal 3: Sidekiq worker
bundle exec sidekiq
# Terminal 4: MailHog (optional)
mailhog
```
### 3. Verify Installation
Once all services are running, verify your setup:
- **Web Application**: http://localhost:3000
- **API Health Check**: http://localhost:3000/api
- **Sidekiq Web UI**: http://localhost:3000/sidekiq
- **MailHog**: http://localhost:8025 (if running)
## Initial Login
### Default Credentials
After seeding the database, you can log in with:
```
Email: john@acme.inc
Password: Password1!
```
### Creating Additional Users
```bash
# Access Rails console
bundle exec rails console
# Create a new user
user = User.create!(
name: "Your Name",
email: "your.email@example.com",
password: "Password123!",
password_confirmation: "Password123!"
)
# Make user an administrator
user.account_users.first.update!(role: 'administrator')
```
## Development Workflow
### 1. Code Quality Setup
```bash
# Install pre-commit hooks (optional but recommended)
# Create .git/hooks/pre-commit
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
# Run RuboCop
bundle exec rubocop --parallel
# Run ESLint
pnpm run lint
# Run tests
bundle exec rspec --fail-fast
EOF
chmod +x .git/hooks/pre-commit
```
### 2. Running Tests
```bash
# Run Ruby tests
bundle exec rspec
# Run specific test file
bundle exec rspec spec/models/user_spec.rb
# Run JavaScript tests
pnpm run test
# Run E2E tests (requires Playwright)
pnpm exec playwright install
pnpm run test:e2e
# Run tests with coverage
COVERAGE=true bundle exec rspec
```
### 3. Code Linting and Formatting
```bash
# Ruby linting with RuboCop
bundle exec rubocop
# Auto-fix Ruby issues
bundle exec rubocop -a
# JavaScript linting
pnpm run lint
# Auto-fix JavaScript issues
pnpm run lint:fix
# Format code with Prettier
pnpm run format
```
## IDE Configuration
### VS Code Setup
Create `.vscode/settings.json`:
```json
{
"ruby.intellisense": "rubyLocate",
"ruby.codeCompletion": "rcodetools",
"ruby.format": "rubocop",
"editor.formatOnSave": true,
"editor.rulers": [120],
"files.trimTrailingWhitespace": true,
"files.insertFinalNewline": true,
"eslint.autoFixOnSave": true,
"prettier.requireConfig": true,
"ruby.rubocop.executePath": "./bin/",
"ruby.rubocop.onSave": true
}
```
Create `.vscode/extensions.json`:
```json
{
"recommendations": [
"rebornix.ruby",
"wingrunr21.vscode-ruby",
"bradlc.vscode-tailwindcss",
"esbenp.prettier-vscode",
"dbaeumer.vscode-eslint",
"ms-vscode.vscode-typescript-next",
"shopify.ruby-lsp"
]
}
```
### RubyMine Setup
1. **Open Project**: File → Open → Select chatwoot directory
2. **Configure Ruby SDK**: File → Project Structure → SDKs → Add Ruby SDK
3. **Database Connection**: Database tool window → Add PostgreSQL connection
4. **Code Style**: File → Settings → Editor → Code Style → Import scheme
## Debugging Setup
### Rails Debugging
Add to your code for debugging:
```ruby
# Using Pry (recommended)
binding.pry
# Using built-in debugger
debugger
# Using byebug
byebug
```
### JavaScript Debugging
```javascript
// Browser debugging
console.log('Debug info:', variable);
debugger;
// Node.js debugging
console.log('Debug info:', variable);
```
### Database Debugging
```bash
# Rails console
bundle exec rails console
# Database console
bundle exec rails dbconsole
# Check queries in development log
tail -f log/development.log | grep -E "(SELECT|INSERT|UPDATE|DELETE)"
```
## Performance Optimization
### Development Performance
```bash
# Use Spring for faster Rails commands
bundle exec spring binstub --all
# Precompile assets for faster loading
bundle exec rails assets:precompile
# Use parallel testing
bundle exec rspec --parallel
# Monitor memory usage
ps aux | grep -E "(ruby|node)" | head -10
```
### Database Performance
```ruby
# Add to config/environments/development.rb for query analysis
config.active_record.verbose_query_logs = true
# Enable query plan logging
config.active_record.dump_schema_after_migration = false
```
## Troubleshooting Setup Issues
### Common Setup Problems
<Accordion title="Bundle install fails">
**Error**: `An error occurred while installing pg`
**Solution**:
```bash
# macOS
brew install postgresql
bundle config build.pg --with-pg-config=/usr/local/bin/pg_config
# Ubuntu/Debian
sudo apt-get install libpq-dev
bundle install
```
</Accordion>
<Accordion title="Database connection refused">
**Error**: `could not connect to server: Connection refused`
**Solution**:
```bash
# Check if PostgreSQL is running
sudo systemctl status postgresql
# Start PostgreSQL
sudo systemctl start postgresql
# macOS with Homebrew
brew services start postgresql
```
</Accordion>
<Accordion title="Redis connection refused">
**Error**: `Redis::CannotConnectError`
**Solution**:
```bash
# Check if Redis is running
redis-cli ping
# Start Redis
sudo systemctl start redis
# macOS with Homebrew
brew services start redis
```
</Accordion>
<Accordion title="Webpack compilation fails">
**Error**: `Module not found` or compilation errors
**Solution**:
```bash
# Clear webpack cache
rm -rf tmp/cache/webpacker
# Reinstall node modules
rm -rf node_modules
pnpm install
# Restart webpack dev server
pnpm run dev
```
</Accordion>
### Verification Commands
```bash
# Check all services are running
ps aux | grep -E "(rails|sidekiq|webpack|mailhog)"
# Test database connection
bundle exec rails runner "puts ActiveRecord::Base.connection.execute('SELECT 1').first"
# Test Redis connection
bundle exec rails runner "puts Redis.new.ping"
# Check application health
curl http://localhost:3000/api
```
## Next Steps
After successful setup:
1. **Explore the Codebase**: Familiarize yourself with the project structure
2. **Read Contributing Guidelines**: Review code standards and workflow
3. **Pick Your First Issue**: Look for "good first issue" labels
4. **Join the Community**: Connect with other contributors
### Useful Development Commands
```bash
# Generate new migration
bundle exec rails generate migration AddColumnToTable column:type
# Generate new model
bundle exec rails generate model ModelName attribute:type
# Generate new controller
bundle exec rails generate controller ControllerName
# Run specific migration
bundle exec rails db:migrate:up VERSION=20231201000000
# Rollback migration
bundle exec rails db:rollback STEP=1
# Reset database (careful!)
bundle exec rails db:drop db:create db:migrate db:seed
```
## Getting Help
If you encounter issues during setup:
- **Check Common Errors**: See [Common Errors](./common-errors) guide
- **Environment Variables**: Review [Environment Variables](./environment-variables) guide
- **GitHub Issues**: Search existing issues or create a new one
- **Discord Community**: Join the Chatwoot Discord server
- **Documentation**: Check the official documentation
---
You're now ready to start developing with Chatwoot! Your development environment should be fully functional and ready for contribution.
developer-docs/docs.json
+1 -54
View File
@@ -30,64 +30,11 @@
"navigation": {
"groups": [
{
"group": "Getting Started",
"group": "API Reference",
"pages": [
"introduction"
]
},
{
"group": "Self-Hosted Installation",
"pages": [
"self-hosted/introduction",
"self-hosted/architecture",
{
"group": "Deployment",
"pages": [
"self-hosted/deployment/linux-vm",
"self-hosted/deployment/docker",
"self-hosted/deployment/kubernetes",
"self-hosted/deployment/chatwoot-ctl"
]
},
{
"group": "Cloud Providers",
"pages": [
"self-hosted/cloud/aws",
"self-hosted/cloud/azure",
"self-hosted/cloud/digitalocean",
"self-hosted/cloud/gcp",
"self-hosted/cloud/heroku"
]
},
{
"group": "Configuration",
"pages": [
"self-hosted/configuration/environment-variables"
]
}
]
},
{
"group": "Contributing Guide",
"pages": [
"contributing/introduction",
{
"group": "Project Setup",
"pages": [
"contributing/project-setup/setup-guide",
"contributing/project-setup/environment-variables",
"contributing/project-setup/common-errors"
]
},
"contributing/testing",
"contributing/guidelines",
"contributing/code-of-conduct"
]
},
{
"group": "API Reference",
"pages": []
},
{
"group": "Application API",
"description": "APIs for managing application aspects of Chatwoot",
developer-docs/self-hosted/architecture.mdx
-342
View File
@@ -1,342 +0,0 @@
---
title: Chatwoot Architecture
description: Understanding Chatwoot's system architecture, components, and how they work together.
sidebarTitle: Architecture
---
Understanding Chatwoot's architecture is crucial for successful deployment, scaling, and maintenance. This guide explains the core components and how they interact.
## High-Level Architecture
Chatwoot follows a modern, scalable web application architecture with clear separation of concerns:
```mermaid
graph TB
subgraph "Client Layer"
A[Web Dashboard]
B[Mobile Apps]
C[Website Widget]
D[API Clients]
end
subgraph "Load Balancer"
E[Nginx/ALB]
end
subgraph "Application Layer"
F[Rails Web Server]
G[Sidekiq Workers]
H[WebSocket Server]
end
subgraph "Data Layer"
I[PostgreSQL]
J[Redis]
K[File Storage]
end
subgraph "External Services"
L[SMTP Server]
M[Third-party APIs]
N[CDN]
end
A --> E
B --> E
C --> E
D --> E
E --> F
E --> H
F --> G
F --> I
F --> J
G --> I
G --> J
F --> K
F --> L
F --> M
K --> N
```
## Core Components
### 1. Web Application (Rails)
The main application server built with Ruby on Rails handles:
- **HTTP API endpoints** for all client interactions
- **Authentication and authorization** for users and agents
- **Business logic** for conversations, contacts, and workflows
- **Real-time features** via ActionCable WebSockets
- **File uploads and processing**
**Key characteristics:**
- Stateless design for horizontal scaling
- RESTful API architecture
- WebSocket support for real-time updates
- Multi-tenant architecture support
### 2. Background Workers (Sidekiq)
Sidekiq handles asynchronous processing:
- **Email notifications** and delivery
- **Webhook processing** for integrations
- **File processing** and optimization
- **Report generation** and analytics
- **Third-party API calls** (Facebook, WhatsApp, etc.)
**Key characteristics:**
- Redis-backed job queue
- Retry mechanisms for failed jobs
- Horizontal scaling support
- Job prioritization and scheduling
### 3. Database (PostgreSQL)
PostgreSQL stores all application data:
- **User accounts and authentication**
- **Conversations and messages**
- **Contact information and profiles**
- **Configuration and settings**
- **Analytics and reporting data**
**Key characteristics:**
- ACID compliance for data integrity
- JSON support for flexible schemas
- Full-text search capabilities
- Horizontal scaling with read replicas
### 4. Cache and Session Store (Redis)
Redis provides high-performance caching and session management:
- **Session storage** for user authentication
- **Cache layer** for frequently accessed data
- **Job queue** for background processing
- **Real-time data** for WebSocket connections
- **Rate limiting** and throttling
**Key characteristics:**
- In-memory performance
- Persistence options available
- Pub/Sub for real-time features
- Clustering support for high availability
### 5. File Storage
Chatwoot supports multiple storage backends:
- **Local filesystem** (development/small deployments)
- **AWS S3** (recommended for production)
- **Google Cloud Storage**
- **Azure Blob Storage**
- **MinIO** (self-hosted S3-compatible)
**Stored content:**
- User avatars and profile images
- Message attachments and files
- Email templates and assets
- Exported reports and backups
### 6. Reverse Proxy (Nginx)
Nginx serves as the front-end proxy:
- **SSL termination** and certificate management
- **Static file serving** for assets
- **Load balancing** across application instances
- **Request routing** and filtering
- **Compression** and caching headers
## Data Flow
### 1. Incoming Messages
```mermaid
sequenceDiagram
participant C as Customer
participant W as Widget/Channel
participant N as Nginx
participant R as Rails App
participant D as Database
participant Q as Redis Queue
participant S as Sidekiq
participant A as Agent Dashboard
C->>W: Sends message
W->>N: HTTP/WebSocket request
N->>R: Forward request
R->>D: Store message
R->>Q: Queue notification job
R->>A: Real-time update (WebSocket)
Q->>S: Process notification
S->>D: Update delivery status
```
### 2. Agent Responses
```mermaid
sequenceDiagram
participant A as Agent
participant D as Dashboard
participant R as Rails App
participant DB as Database
participant Q as Redis Queue
participant S as Sidekiq
participant C as Customer
A->>D: Types response
D->>R: Send message API
R->>DB: Store message
R->>Q: Queue delivery job
R->>D: Real-time update
Q->>S: Process delivery
S->>C: Deliver via channel
S->>DB: Update status
```
## Scaling Considerations
### Horizontal Scaling
Chatwoot is designed for horizontal scaling:
**Web Servers:**
- Stateless design allows multiple instances
- Load balancer distributes traffic
- Session data stored in Redis
**Background Workers:**
- Multiple Sidekiq processes can run
- Jobs distributed across workers
- Queue-based processing prevents overload
**Database:**
- Read replicas for query scaling
- Connection pooling for efficiency
- Partitioning for large datasets
### Vertical Scaling
For smaller deployments, vertical scaling is often sufficient:
**CPU:** Background processing and real-time features
**Memory:** Caching and session storage
**Storage:** Database and file storage growth
**Network:** WebSocket connections and API traffic
## Security Architecture
### Authentication Flow
```mermaid
graph LR
A[User Login] --> B[Rails Auth]
B --> C[JWT Token]
C --> D[API Requests]
D --> E[Token Validation]
E --> F[Authorized Access]
```
### Data Protection
- **Encryption at rest** for sensitive data
- **TLS encryption** for data in transit
- **Input validation** and sanitization
- **SQL injection** protection via ORM
- **XSS protection** with content security policies
### Access Control
- **Role-based permissions** (Admin, Agent, etc.)
- **Account-level isolation** in multi-tenant setup
- **API rate limiting** to prevent abuse
- **Audit logging** for compliance
## Monitoring and Observability
### Application Metrics
- **Response times** and throughput
- **Error rates** and exceptions
- **Background job** processing times
- **WebSocket connection** counts
### Infrastructure Metrics
- **CPU and memory** utilization
- **Database performance** and connections
- **Redis memory** usage and hit rates
- **Storage usage** and I/O patterns
### Logging Strategy
- **Structured logging** with JSON format
- **Centralized collection** (ELK, Fluentd)
- **Log levels** for different environments
- **Sensitive data** filtering
## Deployment Patterns
### Single Server
Suitable for small teams and development:
- All components on one server
- SQLite or PostgreSQL database
- Local file storage
- Simple backup strategy
### Multi-Server
For production environments:
- Separate database server
- Dedicated Redis instance
- Load-balanced web servers
- Shared file storage (S3/NFS)
### Containerized
Using Docker and orchestration:
- Container images for each component
- Kubernetes or Docker Swarm
- Service discovery and networking
- Rolling updates and health checks
### Cloud-Native
Leveraging cloud services:
- Managed databases (RDS, Cloud SQL)
- Managed Redis (ElastiCache, MemoryStore)
- Object storage (S3, GCS)
- Load balancers and CDN
## Performance Optimization
### Database Optimization
- **Indexing strategy** for common queries
- **Connection pooling** to reduce overhead
- **Query optimization** and monitoring
- **Read replicas** for scaling reads
### Caching Strategy
- **Application-level caching** for expensive operations
- **HTTP caching** for static assets
- **Database query caching** with Redis
- **CDN caching** for global distribution
### Background Processing
- **Job prioritization** for critical tasks
- **Batch processing** for bulk operations
- **Queue monitoring** and alerting
- **Resource allocation** per job type
---
<Note>
Understanding this architecture helps you make informed decisions about deployment, scaling, and maintenance of your Chatwoot instance.
</Note>
developer-docs/self-hosted/cloud/aws.mdx
-501
View File
@@ -1,501 +0,0 @@
---
title: AWS Deployment
description: Deploy Chatwoot on Amazon Web Services with manual installation or marketplace AMI
sidebarTitle: AWS
---
# AWS Deployment Guide
Deploy Chatwoot on Amazon Web Services (AWS) using either manual installation or the AWS Marketplace AMI for a scalable, production-ready setup.
## Deployment Options
<CardGroup cols={2}>
<Card title="Manual Installation" icon="code" href="#manual-installation">
Full control over the deployment with custom architecture
</Card>
<Card title="AWS Marketplace AMI" icon="aws" href="#aws-marketplace-ami">
Quick deployment using pre-configured AMI
</Card>
</CardGroup>
## Manual Installation
### Architecture Overview
This guide follows a standard 3-tier architecture on AWS for high availability:
```
Internet Gateway
|
Application Load Balancer (Public Subnets)
|
Chatwoot Instances (Private Subnets)
|
RDS PostgreSQL + ElastiCache Redis (Private Subnets)
```
### Prerequisites
- AWS account with appropriate permissions
- Domain name for your Chatwoot installation
- Basic knowledge of AWS services (VPC, EC2, RDS, etc.)
### Step 1: Network Setup
#### Create VPC
1. Navigate to the VPC console in your chosen AWS region
2. Create a new VPC:
- **Name**: `chatwoot-vpc`
- **CIDR block**: `10.0.0.0/16`
- Leave other options as default
#### Create Subnets
Create subnets across two availability zones:
| Name | Type | AZ | CIDR Block |
|------|------|----|-----------|
| chatwoot-public-1 | Public | us-east-1a | 10.0.0.0/24 |
| chatwoot-public-2 | Public | us-east-1b | 10.0.1.0/24 |
| chatwoot-private-1 | Private | us-east-1a | 10.0.2.0/24 |
| chatwoot-private-2 | Private | us-east-1b | 10.0.3.0/24 |
<Note>
Enable "Auto-assign public IPv4 address" for public subnets under Actions > Subnet Settings.
</Note>
#### Internet Gateway
1. Create Internet Gateway named `chatwoot-igw`
2. Attach it to `chatwoot-vpc`
#### NAT Gateways
Create NAT gateways in each public subnet:
1. **chatwoot-nat-1** in `chatwoot-public-1`
2. **chatwoot-nat-2** in `chatwoot-public-2`
Allocate Elastic IPs for each NAT gateway.
#### Route Tables
**Public Route Table** (`chatwoot-public-rt`):
- Route: `0.0.0.0/0` → `chatwoot-igw`
- Associate with public subnets
**Private Route Tables**:
- `chatwoot-private-a`: Route `0.0.0.0/0` → `chatwoot-nat-1`
- `chatwoot-private-b`: Route `0.0.0.0/0` → `chatwoot-nat-2`
### Step 2: Application Load Balancer
1. Navigate to EC2 > Load Balancers
2. Create Application Load Balancer:
- **Name**: `chatwoot-loadbalancer`
- **Scheme**: Internet-facing
- **IP address type**: IPv4
- **VPC**: `chatwoot-vpc`
- **Subnets**: Select both public subnets
#### Security Group for ALB
Create `chatwoot-loadbalancer-sg` with rules:
- HTTP (80) from `0.0.0.0/0`
- HTTPS (443) from `0.0.0.0/0`
- TCP (3000) from `0.0.0.0/0` (for health checks)
#### Target Group
Create `chatwoot-tg` target group:
- **Target type**: Instances
- **Protocol**: HTTP
- **Port**: 3000
- **Health check path**: `/api`
### Step 3: Database Setup (RDS)
#### RDS Security Group
Create `chatwoot-rds-sg`:
- PostgreSQL (5432) from `chatwoot-loadbalancer-sg`
#### RDS Subnet Group
Create `chatwoot-rds-group`:
- **VPC**: `chatwoot-vpc`
- **Subnets**: Both private subnets
#### Create RDS Instance
1. Navigate to RDS > Databases
2. Create database:
- **Engine**: PostgreSQL
- **Template**: Production
- **DB instance identifier**: `chatwoot-db`
- **Master username**: `chatwoot`
- **Master password**: Generate secure password
- **DB instance class**: `db.t3.medium` (minimum)
- **Storage**: 100 GB GP2 (minimum)
- **Multi-AZ**: Yes
- **VPC**: `chatwoot-vpc`
- **Subnet group**: `chatwoot-rds-group`
- **Security group**: `chatwoot-rds-sg`
<Warning>
Note down the RDS endpoint, username, and password for later configuration.
</Warning>
### Step 4: Redis Setup (ElastiCache)
#### ElastiCache Security Group
Create `chatwoot-redis-sg`:
- Redis (6379) from `chatwoot-loadbalancer-sg`
#### ElastiCache Subnet Group
Create `chatwoot-redis-group`:
- **VPC**: `chatwoot-vpc`
- **Subnets**: Both private subnets
#### Create Redis Cluster
1. Navigate to ElastiCache > Redis clusters
2. Create cluster:
- **Name**: `chatwoot-redis`
- **Engine version**: 7.0+
- **Node type**: `cache.t3.micro` (minimum)
- **Multi-AZ**: Yes
- **Subnet group**: `chatwoot-redis-group`
- **Security group**: `chatwoot-redis-sg`
### Step 5: Bastion Host
Create bastion servers for secure access to private instances:
1. Launch EC2 instance:
- **AMI**: Ubuntu 20.04 LTS
- **Instance type**: `t3.micro`
- **VPC**: `chatwoot-vpc`
- **Subnet**: `chatwoot-public-1`
- **Auto-assign public IP**: Yes
- **Security group**: Create `chatwoot-bastion-sg` (SSH from your IP)
### Step 6: Chatwoot Application Servers
#### Launch Chatwoot Instance
1. Launch EC2 instance:
- **AMI**: Ubuntu 20.04 LTS
- **Instance type**: `c5.xlarge` (minimum for production)
- **VPC**: `chatwoot-vpc`
- **Subnet**: `chatwoot-private-1`
- **Auto-assign public IP**: No
- **Storage**: 60 GB GP2
- **Security group**: `chatwoot-loadbalancer-sg`
#### Install Chatwoot
1. SSH to bastion host, then to Chatwoot instance
2. Switch to root user and download installation script:
```bash
sudo su -
wget https://get.chatwoot.app/linux/install.sh
chmod +x install.sh
./install.sh --install
```
#### Configure Chatwoot
1. Switch to chatwoot user and edit environment:
```bash
sudo -i -u chatwoot
cd chatwoot
nano .env
```
2. Update database and Redis configuration:
```bash
# Database
DATABASE_URL="postgresql://chatwoot:password@your-rds-endpoint:5432/chatwoot_production"
# Redis
REDIS_URL="redis://your-elasticache-endpoint:6379/0"
# Frontend URL
FRONTEND_URL="https://chatwoot.yourdomain.com"
# Force SSL
FORCE_SSL=true
# Email configuration (example with SES)
MAILER_SENDER_EMAIL="noreply@yourdomain.com"
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
# Storage (S3)
ACTIVE_STORAGE_SERVICE="amazon"
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"
```
3. Run database preparation:
```bash
RAILS_ENV=production bundle exec rake db:chatwoot_prepare
```
4. Restart services:
```bash
sudo cwctl --restart
```
### Step 7: SSL Certificate (ACM)
1. Navigate to Certificate Manager
2. Request public certificate for your domain
3. Validate domain ownership
4. Attach certificate to ALB HTTPS listener
### Step 8: Auto Scaling
#### Create AMI
1. Stop the Chatwoot instance
2. Create AMI named `chatwoot-base-ami`
3. Terminate the original instance
#### Launch Template
Create launch template with:
- **AMI**: `chatwoot-base-ami`
- **Instance type**: `c5.xlarge`
- **Security group**: `chatwoot-loadbalancer-sg`
- **User data** (optional):
```bash
#!/bin/bash
sudo cwctl --restart
```
#### Auto Scaling Group
Create ASG with:
- **Launch template**: Use created template
- **VPC**: `chatwoot-vpc`
- **Subnets**: Both private subnets
- **Target group**: `chatwoot-tg`
- **Desired capacity**: 2
- **Minimum**: 2
- **Maximum**: 4
#### Scaling Policies
Create scaling policies based on:
- CPU utilization (scale out at 70%, scale in at 30%)
- Memory utilization
- Request count per target
## AWS Marketplace AMI
### Quick Deployment
1. Navigate to AWS Marketplace
2. Search for "Chatwoot"
3. Subscribe to Chatwoot AMI
4. Launch instance with recommended settings:
- **Instance type**: `t3.medium` or larger
- **Storage**: 20 GB minimum
- **Security group**: Allow HTTP, HTTPS, and SSH
### Post-Launch Configuration
1. SSH to the instance
2. Complete initial setup:
```bash
sudo /opt/chatwoot/setup.sh
```
3. Configure domain and SSL:
```bash
sudo /opt/chatwoot/configure-domain.sh yourdomain.com
```
## Production Optimizations
### Performance Tuning
```bash
# Optimize Rails configuration
export RAILS_MAX_THREADS=20
export WEB_CONCURRENCY=4
export SIDEKIQ_CONCURRENCY=25
# Database connection pooling
export DATABASE_POOL_SIZE=25
```
### Monitoring Setup
#### CloudWatch Metrics
Enable detailed monitoring for:
- EC2 instances
- RDS database
- ElastiCache cluster
- Application Load Balancer
#### Custom Metrics
```bash
# Install CloudWatch agent
wget https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm
sudo rpm -U ./amazon-cloudwatch-agent.rpm
# Configure custom metrics
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard
```
### Backup Strategy
#### RDS Automated Backups
- Enable automated backups with 7-day retention
- Configure backup window during low-traffic hours
- Enable point-in-time recovery
#### Application Data Backup
```bash
#!/bin/bash
# Backup script for application data
DATE=$(date +%Y%m%d_%H%M%S)
# Database backup
pg_dump $DATABASE_URL | gzip > "s3://your-backup-bucket/db/chatwoot_$DATE.sql.gz"
# File uploads backup (if using local storage)
aws s3 sync /home/chatwoot/chatwoot/storage s3://your-backup-bucket/storage/
```
### Security Hardening
#### IAM Roles
Create IAM roles with minimal permissions:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::your-chatwoot-bucket/*"
},
{
"Effect": "Allow",
"Action": [
"ses:SendEmail",
"ses:SendRawEmail"
],
"Resource": "*"
}
]
}
```
#### Security Groups
Implement least-privilege access:
- ALB: Only HTTP/HTTPS from internet
- App servers: Only from ALB and bastion
- Database: Only from app servers
- Redis: Only from app servers
## Cost Optimization
### Reserved Instances
Purchase Reserved Instances for:
- RDS database instances
- ElastiCache clusters
- Predictable EC2 workloads
### Spot Instances
Use Spot Instances for:
- Development environments
- Non-critical worker processes
- Batch processing tasks
### Storage Optimization
- Use GP3 volumes for better price/performance
- Implement S3 lifecycle policies for old backups
- Use S3 Intelligent Tiering for file storage
## Troubleshooting
### Common Issues
<Accordion title="Application not accessible">
Check:
- Security group rules
- Target group health
- Route table configuration
- DNS resolution
</Accordion>
<Accordion title="Database connection errors">
Verify:
- RDS security group allows connections
- Database credentials in .env file
- Network connectivity from app servers
</Accordion>
<Accordion title="High memory usage">
Solutions:
- Increase instance size
- Optimize Sidekiq concurrency
- Enable swap memory
- Monitor for memory leaks
</Accordion>
### Monitoring Commands
```bash
# Check application health
curl -I http://localhost:3000/api
# Monitor system resources
htop
iostat -x 1
free -h
# Check service status
sudo systemctl status chatwoot.target
```
---
This AWS deployment guide provides a comprehensive approach to hosting Chatwoot on AWS infrastructure. Choose the deployment method that best fits your requirements and scale as needed.
developer-docs/self-hosted/cloud/azure.mdx
-663
View File
@@ -1,663 +0,0 @@
---
title: Azure Deployment
description: Deploy Chatwoot on Microsoft Azure with various deployment options
sidebarTitle: Azure
---
# Azure Deployment Guide
Deploy Chatwoot on Microsoft Azure using various deployment options including Virtual Machines, Container Instances, or App Service for a scalable, production-ready setup.
## Deployment Options
<CardGroup cols={3}>
<Card title="Virtual Machines" icon="server" href="#virtual-machines">
Full control with custom VM deployment
</Card>
<Card title="Container Instances" icon="docker" href="#container-instances">
Serverless container deployment
</Card>
<Card title="App Service" icon="cloud" href="#app-service">
Platform-as-a-Service deployment
</Card>
</CardGroup>
## Virtual Machines Deployment
### Architecture Overview
```
Azure Load Balancer
|
Virtual Machines (Availability Set)
|
Azure Database for PostgreSQL + Azure Cache for Redis
```
### Prerequisites
- Azure subscription with appropriate permissions
- Azure CLI installed and configured
- Domain name for your Chatwoot installation
### Step 1: Resource Group and Network
#### Create Resource Group
```bash
# Create resource group
az group create \
--name chatwoot-rg \
--location eastus
```
#### Create Virtual Network
```bash
# Create virtual network
az network vnet create \
--resource-group chatwoot-rg \
--name chatwoot-vnet \
--address-prefix 10.0.0.0/16 \
--subnet-name chatwoot-subnet \
--subnet-prefix 10.0.1.0/24
```
#### Create Network Security Group
```bash
# Create NSG
az network nsg create \
--resource-group chatwoot-rg \
--name chatwoot-nsg
# Add rules
az network nsg rule create \
--resource-group chatwoot-rg \
--nsg-name chatwoot-nsg \
--name AllowHTTP \
--protocol tcp \
--priority 1000 \
--destination-port-range 80
az network nsg rule create \
--resource-group chatwoot-rg \
--nsg-name chatwoot-nsg \
--name AllowHTTPS \
--protocol tcp \
--priority 1001 \
--destination-port-range 443
az network nsg rule create \
--resource-group chatwoot-rg \
--nsg-name chatwoot-nsg \
--name AllowSSH \
--protocol tcp \
--priority 1002 \
--destination-port-range 22 \
--source-address-prefix "YOUR_IP_ADDRESS"
```
### Step 2: Database Setup
#### Create PostgreSQL Server
```bash
# Create PostgreSQL server
az postgres server create \
--resource-group chatwoot-rg \
--name chatwoot-postgres \
--location eastus \
--admin-user chatwoot \
--admin-password "YourSecurePassword123!" \
--sku-name GP_Gen5_2 \
--version 13
# Create database
az postgres db create \
--resource-group chatwoot-rg \
--server-name chatwoot-postgres \
--name chatwoot_production
# Configure firewall
az postgres server firewall-rule create \
--resource-group chatwoot-rg \
--server chatwoot-postgres \
--name AllowAzureServices \
--start-ip-address 0.0.0.0 \
--end-ip-address 0.0.0.0
```
#### Create Redis Cache
```bash
# Create Redis cache
az redis create \
--resource-group chatwoot-rg \
--name chatwoot-redis \
--location eastus \
--sku Basic \
--vm-size c0
```
### Step 3: Storage Account
```bash
# Create storage account
az storage account create \
--resource-group chatwoot-rg \
--name chatwootstorage \
--location eastus \
--sku Standard_LRS
# Create container for file uploads
az storage container create \
--account-name chatwootstorage \
--name uploads \
--public-access blob
```
### Step 4: Virtual Machine
#### Create Availability Set
```bash
# Create availability set
az vm availability-set create \
--resource-group chatwoot-rg \
--name chatwoot-avset \
--platform-fault-domain-count 2 \
--platform-update-domain-count 2
```
#### Create Virtual Machine
```bash
# Create VM
az vm create \
--resource-group chatwoot-rg \
--name chatwoot-vm \
--image UbuntuLTS \
--size Standard_D2s_v3 \
--availability-set chatwoot-avset \
--vnet-name chatwoot-vnet \
--subnet chatwoot-subnet \
--nsg chatwoot-nsg \
--admin-username azureuser \
--generate-ssh-keys \
--custom-data cloud-init.txt
```
#### Cloud-Init Configuration
Create `cloud-init.txt`:
```yaml
#cloud-config
package_upgrade: true
packages:
- curl
- wget
- git
runcmd:
- wget https://get.chatwoot.app/linux/install.sh
- chmod +x install.sh
- ./install.sh --install
```
### Step 5: Load Balancer
```bash
# Create public IP
az network public-ip create \
--resource-group chatwoot-rg \
--name chatwoot-lb-ip \
--sku Standard
# Create load balancer
az network lb create \
--resource-group chatwoot-rg \
--name chatwoot-lb \
--public-ip-address chatwoot-lb-ip \
--frontend-ip-name chatwoot-frontend \
--backend-pool-name chatwoot-backend
# Create health probe
az network lb probe create \
--resource-group chatwoot-rg \
--lb-name chatwoot-lb \
--name chatwoot-health \
--protocol http \
--port 3000 \
--path /api
# Create load balancing rule
az network lb rule create \
--resource-group chatwoot-rg \
--lb-name chatwoot-lb \
--name chatwoot-rule \
--protocol tcp \
--frontend-port 80 \
--backend-port 3000 \
--frontend-ip-name chatwoot-frontend \
--backend-pool-name chatwoot-backend \
--probe-name chatwoot-health
```
### Step 6: Configuration
SSH to the VM and configure Chatwoot:
```bash
# SSH to VM
ssh azureuser@<VM_PUBLIC_IP>
# Switch to chatwoot user
sudo -i -u chatwoot
cd chatwoot
# Edit environment variables
nano .env
```
Update `.env` with Azure services:
```bash
# Database
DATABASE_URL="postgresql://chatwoot:YourSecurePassword123!@chatwoot-postgres.postgres.database.azure.com:5432/chatwoot_production"
# Redis
REDIS_URL="redis://:PRIMARY_ACCESS_KEY@chatwoot-redis.redis.cache.windows.net:6380/0?ssl=true"
# Storage (Azure Blob)
ACTIVE_STORAGE_SERVICE="azure"
AZURE_STORAGE_ACCOUNT_NAME="chatwootstorage"
AZURE_STORAGE_ACCESS_KEY="your-access-key"
AZURE_STORAGE_CONTAINER="uploads"
# Frontend URL
FRONTEND_URL="https://chatwoot.yourdomain.com"
FORCE_SSL=true
```
## Container Instances Deployment
### Docker Compose for Azure
Create `docker-compose.azure.yml`:
```yaml
version: '3.8'
services:
chatwoot-web:
image: chatwoot/chatwoot:latest
environment:
- RAILS_ENV=production
- DATABASE_URL=postgresql://chatwoot:password@postgres:5432/chatwoot_production
- REDIS_URL=redis://redis:6379/0
- FRONTEND_URL=https://chatwoot.yourdomain.com
- FORCE_SSL=true
ports:
- "3000:3000"
depends_on:
- postgres
- redis
chatwoot-worker:
image: chatwoot/chatwoot:latest
environment:
- RAILS_ENV=production
- DATABASE_URL=postgresql://chatwoot:password@postgres:5432/chatwoot_production
- REDIS_URL=redis://redis:6379/0
command: bundle exec sidekiq -C config/sidekiq.yml
depends_on:
- postgres
- redis
postgres:
image: postgres:13
environment:
- POSTGRES_DB=chatwoot_production
- POSTGRES_USER=chatwoot
- POSTGRES_PASSWORD=password
volumes:
- postgres_data:/var/lib/postgresql/data
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
volumes:
postgres_data:
redis_data:
```
### Deploy with Azure Container Instances
```bash
# Create container group
az container create \
--resource-group chatwoot-rg \
--file docker-compose.azure.yml \
--dns-name-label chatwoot-app \
--ports 3000
```
## App Service Deployment
### Create App Service Plan
```bash
# Create App Service plan
az appservice plan create \
--resource-group chatwoot-rg \
--name chatwoot-plan \
--sku P1V2 \
--is-linux
# Create web app
az webapp create \
--resource-group chatwoot-rg \
--plan chatwoot-plan \
--name chatwoot-app \
--deployment-container-image-name chatwoot/chatwoot:latest
```
### Configure App Settings
```bash
# Set environment variables
az webapp config appsettings set \
--resource-group chatwoot-rg \
--name chatwoot-app \
--settings \
RAILS_ENV=production \
DATABASE_URL="postgresql://chatwoot:password@chatwoot-postgres.postgres.database.azure.com:5432/chatwoot_production" \
REDIS_URL="redis://:key@chatwoot-redis.redis.cache.windows.net:6380/0?ssl=true" \
FRONTEND_URL="https://chatwoot-app.azurewebsites.net" \
FORCE_SSL=true
```
## Monitoring and Logging
### Application Insights
```bash
# Create Application Insights
az monitor app-insights component create \
--resource-group chatwoot-rg \
--app chatwoot-insights \
--location eastus \
--kind web
# Get instrumentation key
az monitor app-insights component show \
--resource-group chatwoot-rg \
--app chatwoot-insights \
--query instrumentationKey
```
### Log Analytics Workspace
```bash
# Create Log Analytics workspace
az monitor log-analytics workspace create \
--resource-group chatwoot-rg \
--workspace-name chatwoot-logs \
--location eastus
```
## Security Configuration
### Key Vault for Secrets
```bash
# Create Key Vault
az keyvault create \
--resource-group chatwoot-rg \
--name chatwoot-vault \
--location eastus
# Store secrets
az keyvault secret set \
--vault-name chatwoot-vault \
--name database-password \
--value "YourSecurePassword123!"
az keyvault secret set \
--vault-name chatwoot-vault \
--name redis-key \
--value "your-redis-access-key"
```
### Managed Identity
```bash
# Enable managed identity for VM
az vm identity assign \
--resource-group chatwoot-rg \
--name chatwoot-vm
# Grant access to Key Vault
az keyvault set-policy \
--name chatwoot-vault \
--object-id <MANAGED_IDENTITY_PRINCIPAL_ID> \
--secret-permissions get list
```
## Backup and Disaster Recovery
### Database Backup
```bash
# Enable automated backup for PostgreSQL
az postgres server configuration set \
--resource-group chatwoot-rg \
--server-name chatwoot-postgres \
--name backup_retention_days \
--value 7
# Create manual backup
az postgres server backup create \
--resource-group chatwoot-rg \
--server-name chatwoot-postgres \
--backup-name manual-backup-$(date +%Y%m%d)
```
### VM Backup
```bash
# Create Recovery Services vault
az backup vault create \
--resource-group chatwoot-rg \
--name chatwoot-vault \
--location eastus
# Enable backup for VM
az backup protection enable-for-vm \
--resource-group chatwoot-rg \
--vault-name chatwoot-vault \
--vm chatwoot-vm \
--policy-name DefaultPolicy
```
## Scaling and Performance
### VM Scale Sets
```bash
# Create VM scale set
az vmss create \
--resource-group chatwoot-rg \
--name chatwoot-vmss \
--image UbuntuLTS \
--vm-sku Standard_D2s_v3 \
--instance-count 2 \
--vnet-name chatwoot-vnet \
--subnet chatwoot-subnet \
--lb chatwoot-lb \
--backend-pool-name chatwoot-backend \
--custom-data cloud-init.txt
# Configure autoscaling
az monitor autoscale create \
--resource-group chatwoot-rg \
--resource chatwoot-vmss \
--resource-type Microsoft.Compute/virtualMachineScaleSets \
--name chatwoot-autoscale \
--min-count 2 \
--max-count 5 \
--count 2
# Add scale-out rule
az monitor autoscale rule create \
--resource-group chatwoot-rg \
--autoscale-name chatwoot-autoscale \
--condition "Percentage CPU > 70 avg 5m" \
--scale out 1
# Add scale-in rule
az monitor autoscale rule create \
--resource-group chatwoot-rg \
--autoscale-name chatwoot-autoscale \
--condition "Percentage CPU < 30 avg 5m" \
--scale in 1
```
## SSL Certificate
### App Service Certificate
```bash
# Create App Service certificate
az webapp config ssl upload \
--resource-group chatwoot-rg \
--name chatwoot-app \
--certificate-file certificate.pfx \
--certificate-password "certificate-password"
# Bind certificate to domain
az webapp config ssl bind \
--resource-group chatwoot-rg \
--name chatwoot-app \
--certificate-thumbprint <THUMBPRINT> \
--ssl-type SNI
```
### Let's Encrypt with VM
```bash
# Install Certbot on VM
sudo apt update
sudo apt install certbot python3-certbot-nginx
# Obtain certificate
sudo certbot --nginx -d chatwoot.yourdomain.com
# Auto-renewal
sudo crontab -e
# Add: 0 12 * * * /usr/bin/certbot renew --quiet
```
## Cost Optimization
### Reserved Instances
```bash
# Purchase reserved capacity for VMs
az reservations reservation-order purchase \
--reservation-order-id <ORDER_ID> \
--sku Standard_D2s_v3 \
--location eastus \
--quantity 2 \
--term P1Y
```
### Azure Advisor
```bash
# Get cost recommendations
az advisor recommendation list \
--category Cost \
--resource-group chatwoot-rg
```
## Troubleshooting
### Common Issues
<Accordion title="Database connection timeout">
Check:
- PostgreSQL firewall rules
- Network security group rules
- Connection string format
- SSL requirements for Azure Database
</Accordion>
<Accordion title="Redis connection issues">
Verify:
- Redis access keys
- SSL configuration (required for Azure Cache)
- Network connectivity
- Port 6380 (SSL) vs 6379 (non-SSL)
</Accordion>
<Accordion title="Storage upload failures">
Solutions:
- Verify storage account access keys
- Check container permissions
- Ensure CORS settings if needed
- Validate Azure Storage configuration
</Accordion>
### Diagnostic Commands
```bash
# Check VM status
az vm get-instance-view \
--resource-group chatwoot-rg \
--name chatwoot-vm
# View application logs
az webapp log tail \
--resource-group chatwoot-rg \
--name chatwoot-app
# Check database connectivity
az postgres server show \
--resource-group chatwoot-rg \
--name chatwoot-postgres
```
## Best Practices
### Security
- Use Azure Key Vault for secrets management
- Enable managed identities for Azure resources
- Implement network security groups with least privilege
- Enable Azure Security Center recommendations
### Performance
- Use Azure CDN for static assets
- Implement Redis caching strategies
- Monitor with Application Insights
- Use proximity placement groups for low latency
### Cost Management
- Use Azure Cost Management for monitoring
- Implement auto-shutdown for development VMs
- Consider spot instances for non-critical workloads
- Use reserved instances for predictable workloads
### Backup and Recovery
- Enable automated backups for all data services
- Test backup restoration procedures regularly
- Implement geo-redundant storage for critical data
- Document disaster recovery procedures
---
This Azure deployment guide provides multiple options for hosting Chatwoot on Microsoft Azure. Choose the deployment method that best fits your requirements, budget, and operational preferences.
developer-docs/self-hosted/cloud/digitalocean.mdx
-670
View File
@@ -1,670 +0,0 @@
---
title: DigitalOcean Deployment
description: Deploy Chatwoot on DigitalOcean with Droplets, App Platform, or Kubernetes
sidebarTitle: DigitalOcean
---
# DigitalOcean Deployment Guide
Deploy Chatwoot on DigitalOcean using Droplets, App Platform, or DigitalOcean Kubernetes for a scalable, cost-effective solution.
## Deployment Options
<CardGroup cols={3}>
<Card title="Droplets" icon="server" href="#droplets-deployment">
Traditional VPS deployment with full control
</Card>
<Card title="App Platform" icon="cloud" href="#app-platform">
Platform-as-a-Service deployment
</Card>
<Card title="Kubernetes" icon="kubernetes" href="#kubernetes-deployment">
Container orchestration with DOKS
</Card>
</CardGroup>
## Droplets Deployment
### Quick Start with One-Click Install
DigitalOcean offers a one-click Chatwoot installation from the Marketplace:
1. **Navigate to DigitalOcean Marketplace**
2. **Search for "Chatwoot"**
3. **Click "Create Chatwoot Droplet"**
4. **Configure your Droplet:**
- **Plan**: Basic ($12/month minimum recommended)
- **CPU options**: Regular Intel
- **Region**: Choose closest to your users
- **Authentication**: SSH keys (recommended)
- **Hostname**: chatwoot-production
5. **Access your installation:**
```bash
ssh root@your-droplet-ip
```
### Manual Installation
#### Create Droplet
```bash
# Using doctl CLI
doctl compute droplet create chatwoot-prod \
--image ubuntu-20-04-x64 \
--size s-2vcpu-4gb \
--region nyc3 \
--ssh-keys your-ssh-key-id \
--enable-monitoring \
--enable-ipv6
```
#### Install Chatwoot
```bash
# SSH to droplet
ssh root@your-droplet-ip
# Download and run installation script
wget https://get.chatwoot.app/linux/install.sh
chmod +x install.sh
./install.sh --install
```
### Database Setup
#### Managed PostgreSQL
```bash
# Create managed database cluster
doctl databases create chatwoot-db \
--engine postgres \
--version 13 \
--size db-s-1vcpu-1gb \
--region nyc3 \
--num-nodes 1
# Create database
doctl databases db create chatwoot-db-id chatwoot_production
# Create user
doctl databases user create chatwoot-db-id chatwoot
```
#### Managed Redis
```bash
# Create managed Redis cluster
doctl databases create chatwoot-redis \
--engine redis \
--version 6 \
--size db-s-1vcpu-1gb \
--region nyc3 \
--num-nodes 1
```
### Configuration
Update Chatwoot configuration to use managed services:
```bash
# Switch to chatwoot user
sudo -i -u chatwoot
cd chatwoot
# Edit environment file
nano .env
```
Add managed database configuration:
```bash
# Database (from DigitalOcean dashboard)
DATABASE_URL="postgresql://chatwoot:password@chatwoot-db-do-user-123456-0.b.db.ondigitalocean.com:25060/chatwoot_production?sslmode=require"
# Redis (from DigitalOcean dashboard)
REDIS_URL="rediss://default:password@chatwoot-redis-do-user-123456-0.b.db.ondigitalocean.com:25061"
# Frontend URL
FRONTEND_URL="https://chatwoot.yourdomain.com"
FORCE_SSL=true
# Storage (DigitalOcean Spaces)
ACTIVE_STORAGE_SERVICE="amazon"
S3_BUCKET_NAME="your-chatwoot-space"
AWS_ACCESS_KEY_ID="your-spaces-key"
AWS_SECRET_ACCESS_KEY="your-spaces-secret"
AWS_REGION="nyc3"
S3_ENDPOINT="https://nyc3.digitaloceanspaces.com"
```
### Load Balancer Setup
```bash
# Create load balancer
doctl compute load-balancer create \
--name chatwoot-lb \
--forwarding-rules entry_protocol:https,entry_port:443,target_protocol:http,target_port:3000,certificate_id:your-cert-id \
--forwarding-rules entry_protocol:http,entry_port:80,target_protocol:http,target_port:3000 \
--health-check protocol:http,port:3000,path:/api,check_interval_seconds:10,response_timeout_seconds:5,healthy_threshold:3,unhealthy_threshold:3 \
--region nyc3 \
--droplet-ids droplet-id-1,droplet-id-2
```
## App Platform Deployment
### App Spec Configuration
Create `app.yaml`:
```yaml
name: chatwoot-app
services:
- name: web
source_dir: /
github:
repo: your-username/chatwoot-fork
branch: main
run_command: bundle exec rails server -b 0.0.0.0 -p $PORT
environment_slug: ruby
instance_count: 1
instance_size_slug: basic-xxs
envs:
- key: RAILS_ENV
value: production
- key: DATABASE_URL
value: ${chatwoot-db.DATABASE_URL}
- key: REDIS_URL
value: ${chatwoot-redis.REDIS_URL}
- key: FRONTEND_URL
value: ${APP_URL}
- key: FORCE_SSL
value: "true"
http_port: 8080
- name: worker
source_dir: /
github:
repo: your-username/chatwoot-fork
branch: main
run_command: bundle exec sidekiq -C config/sidekiq.yml
environment_slug: ruby
instance_count: 1
instance_size_slug: basic-xxs
envs:
- key: RAILS_ENV
value: production
- key: DATABASE_URL
value: ${chatwoot-db.DATABASE_URL}
- key: REDIS_URL
value: ${chatwoot-redis.REDIS_URL}
databases:
- name: chatwoot-db
engine: PG
version: "13"
size: db-s-dev-database
- name: chatwoot-redis
engine: REDIS
version: "6"
size: db-s-dev-database
static_sites:
- name: assets
source_dir: /public
github:
repo: your-username/chatwoot-fork
branch: main
build_command: bundle exec rails assets:precompile
```
### Deploy with App Platform
```bash
# Deploy using doctl
doctl apps create --spec app.yaml
# Or deploy via DigitalOcean Control Panel
# 1. Go to App Platform
# 2. Create App
# 3. Connect your GitHub repository
# 4. Configure build and run commands
# 5. Add environment variables
# 6. Deploy
```
## Kubernetes Deployment
### Create DOKS Cluster
```bash
# Create Kubernetes cluster
doctl kubernetes cluster create chatwoot-k8s \
--region nyc3 \
--version 1.24.4-do.0 \
--count 3 \
--size s-2vcpu-4gb \
--auto-upgrade=true \
--maintenance-window="saturday=06:00"
# Get kubeconfig
doctl kubernetes cluster kubeconfig save chatwoot-k8s
```
### Helm Deployment
```bash
# Add Chatwoot Helm repository
helm repo add chatwoot https://chatwoot.github.io/charts
helm repo update
# Create namespace
kubectl create namespace chatwoot
# Install with DigitalOcean-specific values
helm install chatwoot chatwoot/chatwoot \
--namespace chatwoot \
--set ingress.enabled=true \
--set ingress.className=nginx \
--set ingress.hosts[0].host=chatwoot.yourdomain.com \
--set postgresql.enabled=false \
--set redis.enabled=false \
--set env.DATABASE_URL="postgresql://..." \
--set env.REDIS_URL="redis://..."
```
### DigitalOcean-Specific Values
Create `do-values.yaml`:
```yaml
# DigitalOcean Kubernetes values
ingress:
enabled: true
className: nginx
annotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
kubernetes.digitalocean.com/load-balancer-id: "your-lb-id"
hosts:
- host: chatwoot.yourdomain.com
paths:
- path: /
pathType: Prefix
# Use DigitalOcean managed databases
postgresql:
enabled: false
redis:
enabled: false
# DigitalOcean Spaces for storage
env:
ACTIVE_STORAGE_SERVICE: "amazon"
S3_BUCKET_NAME: "your-chatwoot-space"
AWS_ACCESS_KEY_ID: "your-spaces-key"
AWS_SECRET_ACCESS_KEY: "your-spaces-secret"
AWS_REGION: "nyc3"
S3_ENDPOINT: "https://nyc3.digitaloceanspaces.com"
# Resource limits for DigitalOcean
resources:
limits:
cpu: 1000m
memory: 2Gi
requests:
cpu: 500m
memory: 1Gi
# Storage class for DigitalOcean Block Storage
persistence:
enabled: true
storageClass: "do-block-storage"
size: 20Gi
```
## Storage Configuration
### DigitalOcean Spaces
```bash
# Create Spaces bucket
doctl compute cdn create \
--origin nyc3.digitaloceanspaces.com/your-chatwoot-space \
--ttl 3600
# Configure CORS for Spaces
# Create cors.json:
{
"CORSRules": [
{
"AllowedOrigins": ["https://chatwoot.yourdomain.com"],
"AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
"AllowedHeaders": ["*"],
"MaxAgeSeconds": 3000
}
]
}
# Apply CORS configuration
s3cmd setcors cors.json s3://your-chatwoot-space
```
### Block Storage for Droplets
```bash
# Create and attach block storage
doctl compute volume create chatwoot-storage \
--size 100GiB \
--region nyc3
doctl compute volume-action attach chatwoot-storage \
--droplet-id your-droplet-id
# Mount the volume
sudo mkdir /mnt/chatwoot-storage
sudo mount -o discard,defaults /dev/disk/by-id/scsi-0DO_Volume_chatwoot-storage /mnt/chatwoot-storage
echo '/dev/disk/by-id/scsi-0DO_Volume_chatwoot-storage /mnt/chatwoot-storage ext4 defaults,nofail,discard 0 0' | sudo tee -a /etc/fstab
```
## SSL Certificate
### Let's Encrypt with Certbot
```bash
# Install Certbot
sudo apt update
sudo apt install certbot python3-certbot-nginx
# Obtain certificate
sudo certbot --nginx -d chatwoot.yourdomain.com
# Auto-renewal
sudo crontab -e
# Add: 0 12 * * * /usr/bin/certbot renew --quiet
```
### DigitalOcean Load Balancer SSL
```bash
# Upload certificate to DigitalOcean
doctl compute certificate create \
--name chatwoot-cert \
--private-key-path private.key \
--leaf-certificate-path certificate.crt \
--certificate-chain-path ca_bundle.crt
# Update load balancer with certificate
doctl compute load-balancer update your-lb-id \
--forwarding-rules entry_protocol:https,entry_port:443,target_protocol:http,target_port:3000,certificate_id:your-cert-id
```
## Monitoring and Alerting
### DigitalOcean Monitoring
```bash
# Enable monitoring for droplets
doctl compute droplet create chatwoot-prod \
--enable-monitoring \
--enable-ipv6
# Create alert policies
doctl monitoring alert-policy create \
--type v1/insights/droplet/cpu \
--description "High CPU usage" \
--compare GreaterThan \
--value 80 \
--window 5m \
--entities droplet:your-droplet-id
```
### Custom Metrics with Prometheus
```yaml
# prometheus-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: prometheus-config
namespace: monitoring
data:
prometheus.yml: |
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'chatwoot'
static_configs:
- targets: ['chatwoot-service:3000']
metrics_path: /metrics
```
## Backup Strategy
### Database Backups
```bash
# Automated backups for managed databases are enabled by default
# Manual backup
doctl databases backups list chatwoot-db-id
# Restore from backup
doctl databases backups restore chatwoot-db-id backup-id
```
### Droplet Snapshots
```bash
# Create snapshot
doctl compute droplet-action snapshot your-droplet-id \
--snapshot-name "chatwoot-backup-$(date +%Y%m%d)"
# Schedule automated snapshots
doctl compute droplet-action enable-backups your-droplet-id
```
### Application Data Backup
```bash
#!/bin/bash
# backup-script.sh
DATE=$(date +%Y%m%d_%H%M%S)
# Database backup (if using managed database)
pg_dump $DATABASE_URL | gzip > "/tmp/chatwoot_db_$DATE.sql.gz"
# Upload to Spaces
s3cmd put "/tmp/chatwoot_db_$DATE.sql.gz" s3://your-backup-space/db/
# File uploads backup
s3cmd sync s3://your-chatwoot-space/ s3://your-backup-space/files/
# Cleanup local backup
rm "/tmp/chatwoot_db_$DATE.sql.gz"
```
## Scaling and Performance
### Horizontal Scaling with Load Balancer
```bash
# Create additional droplets
for i in {2..3}; do
doctl compute droplet create chatwoot-prod-$i \
--image ubuntu-20-04-x64 \
--size s-2vcpu-4gb \
--region nyc3 \
--ssh-keys your-ssh-key-id \
--user-data-file cloud-init.yaml
done
# Add droplets to load balancer
doctl compute load-balancer add-droplets your-lb-id \
--droplet-ids droplet-id-2,droplet-id-3
```
### Vertical Scaling
```bash
# Resize droplet
doctl compute droplet-action resize your-droplet-id \
--size s-4vcpu-8gb \
--resize-disk
```
### Auto-scaling with Kubernetes
```yaml
# hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: chatwoot-hpa
namespace: chatwoot
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: chatwoot
minReplicas: 2
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
- type: Resource
resource:
name: memory
target:
type: Utilization
averageUtilization: 80
```
## Cost Optimization
### Reserved Instances
```bash
# DigitalOcean doesn't offer reserved instances
# But you can optimize costs by:
# 1. Right-sizing droplets
doctl compute size list
# 2. Using appropriate database sizes
doctl databases options sizes
# 3. Implementing auto-scaling to scale down during low usage
```
### Cost Monitoring
```bash
# Check current usage and costs
doctl account get
# Monitor resource usage
doctl monitoring metrics bandwidth droplet:your-droplet-id
doctl monitoring metrics cpu droplet:your-droplet-id
doctl monitoring metrics memory droplet:your-droplet-id
```
## Troubleshooting
### Common Issues
<Accordion title="Droplet connection issues">
Check:
- Firewall rules (ufw status)
- DigitalOcean Cloud Firewalls
- SSH key configuration
- Network connectivity
</Accordion>
<Accordion title="Database connection problems">
Verify:
- Database cluster status
- Connection string format
- SSL requirements for managed databases
- Firewall rules for database access
</Accordion>
<Accordion title="Load balancer health check failures">
Solutions:
- Verify health check path (/api)
- Check application startup time
- Ensure proper port configuration
- Review application logs
</Accordion>
### Diagnostic Commands
```bash
# Check droplet status
doctl compute droplet get your-droplet-id
# View load balancer status
doctl compute load-balancer get your-lb-id
# Check database status
doctl databases get chatwoot-db-id
# Monitor application logs
sudo journalctl -u chatwoot-web.1.service -f
sudo journalctl -u chatwoot-worker.1.service -f
```
### Performance Monitoring
```bash
# System resources
htop
iostat -x 1
free -h
df -h
# Network monitoring
iftop
netstat -tulpn
# Application metrics
curl http://localhost:3000/api
curl http://localhost:3000/metrics
```
## Best Practices
### Security
- Enable DigitalOcean Cloud Firewalls
- Use SSH keys instead of passwords
- Enable automatic security updates
- Implement fail2ban for SSH protection
- Use managed databases for better security
### Performance
- Use DigitalOcean Spaces CDN for static assets
- Implement Redis caching
- Monitor with DigitalOcean Monitoring
- Use SSD-backed droplets
- Place resources in the same region
### Reliability
- Use multiple availability zones
- Implement automated backups
- Set up monitoring and alerting
- Use load balancers for high availability
- Test disaster recovery procedures
### Cost Management
- Right-size your resources
- Use managed services to reduce operational overhead
- Implement monitoring to track usage
- Clean up unused resources regularly
- Consider using Kubernetes for better resource utilization
---
This DigitalOcean deployment guide provides multiple options for hosting Chatwoot on DigitalOcean's infrastructure. Choose the deployment method that best fits your technical requirements and budget constraints.
developer-docs/self-hosted/cloud/gcp.mdx
-745
View File
@@ -1,745 +0,0 @@
---
title: Google Cloud Platform (GCP) Deployment
description: Deploy Chatwoot on Google Cloud Platform with Compute Engine, Cloud Run, or GKE
sidebarTitle: GCP
---
# Google Cloud Platform Deployment Guide
Deploy Chatwoot on Google Cloud Platform using Compute Engine, Cloud Run, or Google Kubernetes Engine for a scalable, enterprise-ready solution.
## Deployment Options
<CardGroup cols={3}>
<Card title="Compute Engine" icon="server" href="#compute-engine">
Traditional VM deployment with full control
</Card>
<Card title="Cloud Run" icon="cloud" href="#cloud-run">
Serverless container deployment
</Card>
<Card title="GKE" icon="kubernetes" href="#google-kubernetes-engine">
Managed Kubernetes deployment
</Card>
</CardGroup>
## Compute Engine Deployment
### Prerequisites
```bash
# Install and configure gcloud CLI
curl https://sdk.cloud.google.com | bash
exec -l $SHELL
gcloud init
# Set project and region
gcloud config set project your-project-id
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a
```
### Network Setup
```bash
# Create VPC network
gcloud compute networks create chatwoot-vpc --subnet-mode=custom
# Create subnet
gcloud compute networks subnets create chatwoot-subnet \
--network=chatwoot-vpc \
--range=10.0.1.0/24 \
--region=us-central1
# Create firewall rules
gcloud compute firewall-rules create chatwoot-allow-http \
--network=chatwoot-vpc \
--allow=tcp:80,tcp:443,tcp:3000 \
--source-ranges=0.0.0.0/0 \
--target-tags=chatwoot-server
gcloud compute firewall-rules create chatwoot-allow-ssh \
--network=chatwoot-vpc \
--allow=tcp:22 \
--source-ranges=0.0.0.0/0 \
--target-tags=chatwoot-server
```
### Database Setup
#### Cloud SQL PostgreSQL
```bash
# Create Cloud SQL instance
gcloud sql instances create chatwoot-db \
--database-version=POSTGRES_13 \
--tier=db-g1-small \
--region=us-central1 \
--storage-type=SSD \
--storage-size=100GB \
--storage-auto-increase \
--backup-start-time=03:00 \
--enable-bin-log \
--maintenance-window-day=SUN \
--maintenance-window-hour=04
# Create database
gcloud sql databases create chatwoot_production --instance=chatwoot-db
# Create user
gcloud sql users create chatwoot \
--instance=chatwoot-db \
--password=your-secure-password
# Get connection name
gcloud sql instances describe chatwoot-db --format="value(connectionName)"
```
#### Memorystore Redis
```bash
# Create Redis instance
gcloud redis instances create chatwoot-redis \
--size=1 \
--region=us-central1 \
--redis-version=redis_6_x \
--network=chatwoot-vpc
```
### Storage Setup
```bash
# Create Cloud Storage bucket
gsutil mb -p your-project-id -c STANDARD -l us-central1 gs://your-chatwoot-bucket
# Set bucket permissions
gsutil iam ch allUsers:objectViewer gs://your-chatwoot-bucket
# Enable CORS
cat > cors.json << EOF
[
{
"origin": ["https://chatwoot.yourdomain.com"],
"method": ["GET", "PUT", "POST", "DELETE"],
"responseHeader": ["Content-Type"],
"maxAgeSeconds": 3600
}
]
EOF
gsutil cors set cors.json gs://your-chatwoot-bucket
```
### Compute Instance
#### Create Instance Template
```bash
# Create startup script
cat > startup-script.sh << 'EOF'
#!/bin/bash
apt-get update
apt-get install -y wget curl
# Download and install Chatwoot
wget https://get.chatwoot.app/linux/install.sh
chmod +x install.sh
./install.sh --install
# Configure environment
sudo -u chatwoot bash << 'INNER_EOF'
cd /home/chatwoot/chatwoot
cat > .env << 'ENV_EOF'
RAILS_ENV=production
NODE_ENV=production
FRONTEND_URL=https://chatwoot.yourdomain.com
FORCE_SSL=true
# Database
DATABASE_URL=postgresql://chatwoot:password@/chatwoot_production?host=/cloudsql/your-project:us-central1:chatwoot-db
# Redis
REDIS_URL=redis://10.0.0.3:6379/0
# Storage
ACTIVE_STORAGE_SERVICE=google
GCS_PROJECT=your-project-id
GCS_BUCKET=your-chatwoot-bucket
# Email (using SendGrid)
MAILER_SENDER_EMAIL=noreply@yourdomain.com
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
ENV_EOF
# Prepare database
RAILS_ENV=production bundle exec rake db:chatwoot_prepare
INNER_EOF
# Restart services
systemctl restart chatwoot.target
EOF
# Create instance template
gcloud compute instance-templates create chatwoot-template \
--machine-type=e2-standard-2 \
--network-interface=network=chatwoot-vpc,subnet=chatwoot-subnet \
--boot-disk-size=50GB \
--boot-disk-type=pd-ssd \
--image-family=ubuntu-2004-lts \
--image-project=ubuntu-os-cloud \
--tags=chatwoot-server \
--metadata-from-file startup-script=startup-script.sh \
--service-account=chatwoot-sa@your-project-id.iam.gserviceaccount.com \
--scopes=https://www.googleapis.com/auth/cloud-platform
```
#### Create Managed Instance Group
```bash
# Create instance group
gcloud compute instance-groups managed create chatwoot-ig \
--template=chatwoot-template \
--size=2 \
--zone=us-central1-a
# Configure autoscaling
gcloud compute instance-groups managed set-autoscaling chatwoot-ig \
--max-num-replicas=5 \
--min-num-replicas=2 \
--target-cpu-utilization=0.7 \
--zone=us-central1-a
```
### Load Balancer
```bash
# Create health check
gcloud compute health-checks create http chatwoot-health-check \
--port=3000 \
--request-path=/api
# Create backend service
gcloud compute backend-services create chatwoot-backend \
--protocol=HTTP \
--health-checks=chatwoot-health-check \
--global
# Add instance group to backend service
gcloud compute backend-services add-backend chatwoot-backend \
--instance-group=chatwoot-ig \
--instance-group-zone=us-central1-a \
--global
# Create URL map
gcloud compute url-maps create chatwoot-map \
--default-service=chatwoot-backend
# Create SSL certificate
gcloud compute ssl-certificates create chatwoot-ssl \
--domains=chatwoot.yourdomain.com
# Create HTTPS proxy
gcloud compute target-https-proxies create chatwoot-https-proxy \
--url-map=chatwoot-map \
--ssl-certificates=chatwoot-ssl
# Create global forwarding rule
gcloud compute forwarding-rules create chatwoot-https-rule \
--global \
--target-https-proxy=chatwoot-https-proxy \
--ports=443
# Create HTTP to HTTPS redirect
gcloud compute url-maps create chatwoot-redirect \
--default-url-redirect-response-code=301 \
--default-url-redirect-https-redirect
gcloud compute target-http-proxies create chatwoot-http-proxy \
--url-map=chatwoot-redirect
gcloud compute forwarding-rules create chatwoot-http-rule \
--global \
--target-http-proxy=chatwoot-http-proxy \
--ports=80
```
## Cloud Run Deployment
### Containerize Chatwoot
Create `Dockerfile`:
```dockerfile
FROM chatwoot/chatwoot:latest
# Set environment variables
ENV RAILS_ENV=production
ENV NODE_ENV=production
ENV PORT=8080
# Expose port
EXPOSE 8080
# Start command
CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "8080"]
```
### Build and Deploy
```bash
# Build container image
gcloud builds submit --tag gcr.io/your-project-id/chatwoot
# Deploy to Cloud Run
gcloud run deploy chatwoot \
--image gcr.io/your-project-id/chatwoot \
--platform managed \
--region us-central1 \
--allow-unauthenticated \
--memory 2Gi \
--cpu 2 \
--max-instances 10 \
--set-env-vars RAILS_ENV=production \
--set-env-vars DATABASE_URL="postgresql://..." \
--set-env-vars REDIS_URL="redis://..." \
--set-env-vars FRONTEND_URL="https://chatwoot.yourdomain.com"
# Deploy worker service
gcloud run deploy chatwoot-worker \
--image gcr.io/your-project-id/chatwoot \
--platform managed \
--region us-central1 \
--no-allow-unauthenticated \
--memory 1Gi \
--cpu 1 \
--max-instances 5 \
--command "bundle,exec,sidekiq,-C,config/sidekiq.yml" \
--set-env-vars RAILS_ENV=production \
--set-env-vars DATABASE_URL="postgresql://..." \
--set-env-vars REDIS_URL="redis://..."
```
### Custom Domain
```bash
# Map custom domain
gcloud run domain-mappings create \
--service chatwoot \
--domain chatwoot.yourdomain.com \
--region us-central1
```
## Google Kubernetes Engine (GKE)
### Create GKE Cluster
```bash
# Create GKE cluster
gcloud container clusters create chatwoot-cluster \
--zone us-central1-a \
--num-nodes 3 \
--machine-type e2-standard-2 \
--disk-size 50GB \
--disk-type pd-ssd \
--enable-autoscaling \
--min-nodes 1 \
--max-nodes 5 \
--enable-autorepair \
--enable-autoupgrade \
--network chatwoot-vpc \
--subnetwork chatwoot-subnet
# Get credentials
gcloud container clusters get-credentials chatwoot-cluster --zone us-central1-a
```
### Helm Deployment
```bash
# Add Chatwoot Helm repository
helm repo add chatwoot https://chatwoot.github.io/charts
helm repo update
# Create namespace
kubectl create namespace chatwoot
# Create values file for GCP
cat > gcp-values.yaml << EOF
# GCP-specific values
ingress:
enabled: true
className: gce
annotations:
kubernetes.io/ingress.global-static-ip-name: "chatwoot-ip"
networking.gke.io/managed-certificates: "chatwoot-ssl"
kubernetes.io/ingress.allow-http: "false"
hosts:
- host: chatwoot.yourdomain.com
paths:
- path: /
pathType: Prefix
# Use Cloud SQL and Memorystore
postgresql:
enabled: false
redis:
enabled: false
env:
DATABASE_URL: "postgresql://chatwoot:password@/chatwoot_production?host=/cloudsql/your-project:us-central1:chatwoot-db"
REDIS_URL: "redis://10.0.0.3:6379/0"
ACTIVE_STORAGE_SERVICE: "google"
GCS_PROJECT: "your-project-id"
GCS_BUCKET: "your-chatwoot-bucket"
# Resource limits
resources:
limits:
cpu: 1000m
memory: 2Gi
requests:
cpu: 500m
memory: 1Gi
# Workload Identity
serviceAccount:
create: true
annotations:
iam.gke.io/gcp-service-account: chatwoot-sa@your-project-id.iam.gserviceaccount.com
EOF
# Install Chatwoot
helm install chatwoot chatwoot/chatwoot \
--namespace chatwoot \
--values gcp-values.yaml
```
### SSL Certificate
```yaml
# managed-cert.yaml
apiVersion: networking.gke.io/v1
kind: ManagedCertificate
metadata:
name: chatwoot-ssl
namespace: chatwoot
spec:
domains:
- chatwoot.yourdomain.com
```
```bash
kubectl apply -f managed-cert.yaml
```
## Service Account and IAM
### Create Service Account
```bash
# Create service account
gcloud iam service-accounts create chatwoot-sa \
--display-name="Chatwoot Service Account"
# Grant necessary permissions
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:chatwoot-sa@your-project-id.iam.gserviceaccount.com" \
--role="roles/cloudsql.client"
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:chatwoot-sa@your-project-id.iam.gserviceaccount.com" \
--role="roles/storage.objectAdmin"
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:chatwoot-sa@your-project-id.iam.gserviceaccount.com" \
--role="roles/redis.editor"
# Create and download key
gcloud iam service-accounts keys create chatwoot-key.json \
--iam-account=chatwoot-sa@your-project-id.iam.gserviceaccount.com
```
## Monitoring and Logging
### Cloud Monitoring
```bash
# Enable APIs
gcloud services enable monitoring.googleapis.com
gcloud services enable logging.googleapis.com
# Create notification channel
gcloud alpha monitoring channels create \
--display-name="Email Alerts" \
--type=email \
--channel-labels=email_address=admin@yourdomain.com
```
### Custom Metrics
```yaml
# monitoring.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: prometheus-config
namespace: chatwoot
data:
prometheus.yml: |
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'chatwoot'
static_configs:
- targets: ['chatwoot-service:3000']
metrics_path: /metrics
```
### Alerting Policies
```bash
# Create alerting policy for high CPU
gcloud alpha monitoring policies create \
--policy-from-file=cpu-alert-policy.yaml
# cpu-alert-policy.yaml
cat > cpu-alert-policy.yaml << EOF
displayName: "High CPU Usage"
conditions:
- displayName: "CPU usage above 80%"
conditionThreshold:
filter: 'resource.type="gce_instance"'
comparison: COMPARISON_GREATER_THAN
thresholdValue: 0.8
duration: 300s
combiner: OR
enabled: true
notificationChannels:
- projects/your-project-id/notificationChannels/CHANNEL_ID
EOF
```
## Backup and Disaster Recovery
### Database Backups
```bash
# Cloud SQL automatic backups are enabled by default
# Create on-demand backup
gcloud sql backups create --instance=chatwoot-db
# List backups
gcloud sql backups list --instance=chatwoot-db
# Restore from backup
gcloud sql backups restore BACKUP_ID --restore-instance=chatwoot-db-restore
```
### Application Backups
```bash
#!/bin/bash
# backup-script.sh
DATE=$(date +%Y%m%d_%H%M%S)
# Database backup
gcloud sql export sql chatwoot-db gs://your-backup-bucket/db/chatwoot_$DATE.sql
# File storage backup
gsutil -m rsync -r -d gs://your-chatwoot-bucket gs://your-backup-bucket/files/
# Kubernetes configuration backup
kubectl get all -n chatwoot -o yaml > k8s-backup-$DATE.yaml
gsutil cp k8s-backup-$DATE.yaml gs://your-backup-bucket/k8s/
```
## Security Best Practices
### Network Security
```bash
# Create private cluster
gcloud container clusters create chatwoot-private \
--enable-private-nodes \
--master-ipv4-cidr-block 172.16.0.0/28 \
--enable-ip-alias \
--enable-network-policy
# Create firewall rules for private access
gcloud compute firewall-rules create allow-chatwoot-private \
--network chatwoot-vpc \
--allow tcp:443,tcp:80 \
--source-ranges 10.0.0.0/8
```
### Secret Management
```bash
# Create secrets in Secret Manager
gcloud secrets create database-password --data-file=db-password.txt
gcloud secrets create redis-password --data-file=redis-password.txt
# Grant access to service account
gcloud secrets add-iam-policy-binding database-password \
--member="serviceAccount:chatwoot-sa@your-project-id.iam.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
```
### Binary Authorization
```bash
# Enable Binary Authorization
gcloud container binauthz policy import policy.yaml
# policy.yaml
cat > policy.yaml << EOF
defaultAdmissionRule:
requireAttestationsBy:
- projects/your-project-id/attestors/prod-attestor
enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
globalPolicyEvaluationMode: ENABLE
EOF
```
## Cost Optimization
### Preemptible Instances
```bash
# Create preemptible node pool
gcloud container node-pools create preemptible-pool \
--cluster=chatwoot-cluster \
--zone=us-central1-a \
--machine-type=e2-standard-2 \
--preemptible \
--num-nodes=2 \
--enable-autoscaling \
--min-nodes=0 \
--max-nodes=5
```
### Committed Use Discounts
```bash
# Purchase committed use discount
gcloud compute commitments create chatwoot-commitment \
--plan=12-month \
--region=us-central1 \
--resources=type=VCPU,amount=4 \
--resources=type=MEMORY,amount=16
```
### Resource Optimization
```yaml
# resource-quota.yaml
apiVersion: v1
kind: ResourceQuota
metadata:
name: chatwoot-quota
namespace: chatwoot
spec:
hard:
requests.cpu: "4"
requests.memory: 8Gi
limits.cpu: "8"
limits.memory: 16Gi
persistentvolumeclaims: "4"
```
## Troubleshooting
### Common Issues
<Accordion title="Cloud SQL connection issues">
Check:
- Cloud SQL Proxy configuration
- Service account permissions
- Network connectivity
- SSL requirements
</Accordion>
<Accordion title="GKE pod startup failures">
Verify:
- Resource quotas and limits
- Image pull permissions
- Service account configuration
- Network policies
</Accordion>
<Accordion title="Load balancer health check failures">
Solutions:
- Verify health check path (/api)
- Check firewall rules
- Ensure proper backend configuration
- Review application startup time
</Accordion>
### Diagnostic Commands
```bash
# Check Compute Engine instances
gcloud compute instances list
# View Cloud Run services
gcloud run services list
# Check GKE cluster status
gcloud container clusters describe chatwoot-cluster --zone us-central1-a
# View logs
gcloud logging read "resource.type=gce_instance" --limit 50
gcloud logging read "resource.type=cloud_run_revision" --limit 50
# Check Cloud SQL status
gcloud sql instances describe chatwoot-db
```
### Performance Monitoring
```bash
# View metrics
gcloud monitoring metrics list --filter="metric.type:compute"
# Create dashboard
gcloud monitoring dashboards create --config-from-file=dashboard.json
```
## Best Practices
### Security
- Use private GKE clusters
- Enable Workload Identity
- Implement Binary Authorization
- Use Secret Manager for sensitive data
- Enable audit logging
### Performance
- Use Cloud CDN for static assets
- Implement Cloud Memorystore for caching
- Use SSD persistent disks
- Enable HTTP/2 and gRPC
- Optimize container images
### Reliability
- Deploy across multiple zones
- Use managed services (Cloud SQL, Memorystore)
- Implement proper health checks
- Set up monitoring and alerting
- Test disaster recovery procedures
### Cost Management
- Use preemptible instances for non-critical workloads
- Implement resource quotas
- Purchase committed use discounts
- Monitor usage with Cloud Billing
- Use Cloud Functions for event-driven tasks
---
This GCP deployment guide provides comprehensive options for hosting Chatwoot on Google Cloud Platform. Choose the deployment method that best aligns with your scalability, security, and operational requirements.
developer-docs/self-hosted/cloud/heroku.mdx
-505
View File
@@ -1,505 +0,0 @@
---
title: Heroku Deployment
description: Deploy Chatwoot on Heroku with one-click deployment and managed services
sidebarTitle: Heroku
---
# Heroku Deployment Guide
Deploy Chatwoot on Heroku using the one-click deployment option for a quick and managed hosting solution. This guide covers deployment, configuration, and maintenance on Heroku's platform.
<Note>
Heroku has discontinued free dynos, postgres and redis. [Chatwoot will use basic/mini plans](https://blog.heroku.com/new-low-cost-plans) for all new Heroku deployments going forward.
</Note>
## Quick Deployment
### One-Click Deploy
The fastest way to get Chatwoot running on Heroku is using the one-click deploy button:
<Card title="Deploy to Heroku" icon="heroku" href="https://heroku.com/deploy?template=https://github.com/chatwoot/chatwoot">
Click here to deploy Chatwoot to Heroku with one click
</Card>
### Deployment Steps
1. **Click the Deploy Button**: Use the one-click deploy button above
2. **Configure App Settings**:
- Choose an app name (or let Heroku generate one)
- Select your region (US or Europe)
- Review the default configuration
3. **Deploy the Application**: Click "Deploy app" and wait for the build to complete
4. **Enable Worker Dynos**:
- Go to the **Resources** tab in your Heroku app dashboard
- Ensure the **worker** dynos are turned on
- This is crucial for background job processing
5. **Configure Environment Variables**:
- Go to **Settings** tab in Heroku app dashboard
- Click **Reveal Config Vars**
- Configure additional variables as needed
6. **Access Your Installation**: Navigate to `yourapp.herokuapp.com`
## Configuration
### Required Environment Variables
Heroku automatically sets up basic configuration, but you'll need to configure additional variables:
#### Email Configuration
```bash
# SMTP Settings (required for notifications)
MAILER_SENDER_EMAIL=noreply@yourdomain.com
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
```
#### File Storage Configuration
<Warning>
Heroku has an "ephemeral" hard disk. Files uploaded to Chatwoot will not persist after application restarts. You must configure cloud storage.
</Warning>
**Amazon S3 Configuration:**
```bash
ACTIVE_STORAGE_SERVICE=amazon
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
```
**Google Cloud Storage Configuration:**
```bash
ACTIVE_STORAGE_SERVICE=google
GCS_PROJECT=your-project-id
GCS_BUCKET=your-chatwoot-bucket
GOOGLE_APPLICATION_CREDENTIALS={"type":"service_account",...}
```
#### Frontend URL
```bash
FRONTEND_URL=https://yourapp.herokuapp.com
FORCE_SSL=true
```
### Setting Environment Variables
#### Via Heroku Dashboard
1. Go to your app's **Settings** tab
2. Click **Reveal Config Vars**
3. Add each variable name and value
4. Click **Add** for each variable
#### Via Heroku CLI
```bash
# Install Heroku CLI
npm install -g heroku
# Login to Heroku
heroku login
# Set environment variables
heroku config:set MAILER_SENDER_EMAIL=noreply@yourdomain.com -a your-app-name
heroku config:set SMTP_ADDRESS=smtp.sendgrid.net -a your-app-name
heroku config:set SMTP_PORT=587 -a your-app-name
# Set storage configuration
heroku config:set ACTIVE_STORAGE_SERVICE=amazon -a your-app-name
heroku config:set S3_BUCKET_NAME=your-bucket -a your-app-name
heroku config:set AWS_ACCESS_KEY_ID=your-key -a your-app-name
heroku config:set AWS_SECRET_ACCESS_KEY=your-secret -a your-app-name
```
## Add-ons and Services
### Database (PostgreSQL)
Heroku automatically provisions a PostgreSQL database:
```bash
# Check database info
heroku pg:info -a your-app-name
# Access database console
heroku pg:psql -a your-app-name
# Create database backup
heroku pg:backups:capture -a your-app-name
# Download backup
heroku pg:backups:download -a your-app-name
```
### Redis
Heroku automatically provisions Redis for caching and background jobs:
```bash
# Check Redis info
heroku redis:info -a your-app-name
# Access Redis CLI
heroku redis:cli -a your-app-name
# Monitor Redis
heroku redis:monitor -a your-app-name
```
### Email Service (SendGrid)
Add SendGrid for email delivery:
```bash
# Add SendGrid add-on
heroku addons:create sendgrid:starter -a your-app-name
# Get SendGrid credentials
heroku config:get SENDGRID_USERNAME -a your-app-name
heroku config:get SENDGRID_PASSWORD -a your-app-name
```
## Updating Your Deployment
### Method 1: GitHub Integration (Recommended)
1. **Connect GitHub Repository**:
- Go to the **Deploy** tab in your Heroku app dashboard
- Choose **GitHub** as the deployment method
- Connect the `chatwoot/chatwoot` repository
2. **Enable Automatic Deploys** (Optional):
- Enable automatic deploys from the `master` branch
- This will automatically deploy when new releases are available
3. **Manual Deploy**:
- Go to **Manual deploy** section
- Choose `master` branch
- Click **Deploy Branch**
### Method 2: Heroku CLI
```bash
# Clone the Chatwoot repository
git clone https://github.com/chatwoot/chatwoot.git
cd chatwoot
# Add Heroku remote
heroku git:remote -a your-app-name
# Deploy latest version
git push heroku master
```
### Method 3: Docker Deployment
```bash
# Login to Heroku Container Registry
heroku container:login
# Build and push Docker image
heroku container:push web -a your-app-name
# Release the image
heroku container:release web -a your-app-name
```
## Scaling and Performance
### Dyno Management
```bash
# Scale web dynos
heroku ps:scale web=2 -a your-app-name
# Scale worker dynos
heroku ps:scale worker=1 -a your-app-name
# Check dyno status
heroku ps -a your-app-name
```
### Performance Monitoring
```bash
# View application metrics
heroku logs --tail -a your-app-name
# Monitor dyno performance
heroku ps:exec -a your-app-name
# Check memory usage
heroku logs --source app --tail -a your-app-name | grep "Memory usage"
```
## Monitoring and Logging
### Application Logs
```bash
# View recent logs
heroku logs -a your-app-name
# Tail logs in real-time
heroku logs --tail -a your-app-name
# Filter logs by source
heroku logs --source app -a your-app-name
heroku logs --source heroku -a your-app-name
```
### Add Monitoring Services
#### Papertrail (Log Management)
```bash
# Add Papertrail
heroku addons:create papertrail:choklad -a your-app-name
# View logs in Papertrail
heroku addons:open papertrail -a your-app-name
```
#### New Relic (Application Monitoring)
```bash
# Add New Relic
heroku addons:create newrelic:wayne -a your-app-name
# Configure New Relic
heroku config:set NEW_RELIC_APP_NAME="Chatwoot Production" -a your-app-name
# Open New Relic dashboard
heroku addons:open newrelic -a your-app-name
```
## Security Configuration
### SSL/TLS
Heroku automatically provides SSL certificates for custom domains:
```bash
# Add custom domain
heroku domains:add chatwoot.yourdomain.com -a your-app-name
# Check SSL certificate status
heroku certs -a your-app-name
# Enable Automated Certificate Management
heroku certs:auto:enable -a your-app-name
```
### Environment Security
```bash
# Rotate database credentials
heroku pg:credentials:rotate -a your-app-name
# Rotate Redis credentials
heroku redis:credentials:rotate -a your-app-name
# Review security settings
heroku config -a your-app-name
```
## Backup and Recovery
### Database Backups
```bash
# Schedule automatic backups
heroku pg:backups:schedule DATABASE_URL --at '02:00 America/Los_Angeles' -a your-app-name
# Create manual backup
heroku pg:backups:capture -a your-app-name
# List all backups
heroku pg:backups -a your-app-name
# Restore from backup
heroku pg:backups:restore b001 DATABASE_URL -a your-app-name
```
### File Storage Backups
Since Heroku has ephemeral storage, ensure your cloud storage has backup policies:
**For S3:**
```bash
# Enable versioning on S3 bucket
aws s3api put-bucket-versioning \
--bucket your-chatwoot-bucket \
--versioning-configuration Status=Enabled
# Set up lifecycle policy for old versions
aws s3api put-bucket-lifecycle-configuration \
--bucket your-chatwoot-bucket \
--lifecycle-configuration file://lifecycle.json
```
## Troubleshooting
### Common Issues
<Accordion title="Application not starting">
**Symptoms**: App crashes on startup, H10 errors
**Solutions**:
- Check that worker dynos are enabled in Resources tab
- Verify all required environment variables are set
- Check application logs: `heroku logs --tail -a your-app-name`
- Ensure database migrations have run: `heroku run rails db:migrate -a your-app-name`
</Accordion>
<Accordion title="File uploads not working">
**Symptoms**: Files upload but disappear after app restart
**Solutions**:
- Configure cloud storage (S3, GCS, etc.)
- Verify storage credentials are correct
- Check CORS settings on your storage bucket
- Test storage configuration: `heroku run rails console -a your-app-name`
</Accordion>
<Accordion title="Email notifications not sending">
**Symptoms**: Users not receiving email notifications
**Solutions**:
- Verify SMTP configuration in config vars
- Check SendGrid add-on status
- Test email configuration: `heroku run rails console -a your-app-name`
- Review email logs in SendGrid dashboard
</Accordion>
<Accordion title="Build version shows as unknown">
**Symptoms**: Settings page shows "unknown" build version
**Solution**:
Enable runtime dyno metadata:
```bash
heroku labs:enable runtime-dyno-metadata -a your-app-name
```
</Accordion>
### Performance Issues
<Accordion title="Slow response times">
**Solutions**:
- Scale up web dynos: `heroku ps:scale web=2 -a your-app-name`
- Upgrade to higher performance dynos
- Monitor database performance with `heroku pg:diagnose -a your-app-name`
- Check Redis performance with `heroku redis:info -a your-app-name`
</Accordion>
<Accordion title="Background jobs not processing">
**Solutions**:
- Ensure worker dynos are running: `heroku ps -a your-app-name`
- Scale worker dynos if needed: `heroku ps:scale worker=1 -a your-app-name`
- Check Sidekiq logs: `heroku logs --source app --tail -a your-app-name | grep sidekiq`
</Accordion>
### Diagnostic Commands
```bash
# Check app status
heroku ps -a your-app-name
# View configuration
heroku config -a your-app-name
# Check add-ons
heroku addons -a your-app-name
# Run Rails console
heroku run rails console -a your-app-name
# Run database migrations
heroku run rails db:migrate -a your-app-name
# Check database status
heroku pg:info -a your-app-name
# Check Redis status
heroku redis:info -a your-app-name
```
## Known Limitations
### Platform Limitations
1. **Ephemeral File System**: Files uploaded to local storage will be lost on dyno restart
2. **Dyno Sleep**: Free tier dynos sleep after 30 minutes of inactivity (upgrade to paid tier to avoid)
3. **Request Timeout**: Heroku has a 30-second request timeout limit
4. **Memory Limits**: Dynos have memory limits based on the plan selected
### Workarounds
1. **File Storage**: Use cloud storage (S3, GCS) instead of local storage
2. **Dyno Sleep**: Upgrade to paid dynos or use external monitoring to keep app awake
3. **Long Requests**: Implement background job processing for long-running tasks
4. **Memory Usage**: Monitor and optimize application memory usage
## Cost Optimization
### Dyno Sizing
```bash
# Check current dyno usage
heroku ps -a your-app-name
# Optimize dyno allocation
heroku ps:scale web=1:standard-1x worker=1:standard-1x -a your-app-name
```
### Add-on Optimization
- Use appropriate add-on tiers based on usage
- Monitor add-on usage and costs in Heroku dashboard
- Consider consolidating services where possible
## Best Practices
### Security
- Use environment variables for all sensitive configuration
- Enable Automated Certificate Management for SSL
- Regularly rotate database and Redis credentials
- Monitor access logs and set up alerts
### Performance
- Use appropriate dyno types for your workload
- Monitor application performance with New Relic or similar
- Implement caching strategies
- Optimize database queries
### Reliability
- Set up automatic database backups
- Monitor application health with external services
- Implement proper error handling and logging
- Use multiple dynos for high availability
### Cost Management
- Monitor dyno usage and scale appropriately
- Use scheduler add-on for periodic tasks instead of always-on workers
- Review and optimize add-on usage regularly
- Consider reserved capacity for predictable workloads
---
This Heroku deployment guide provides a complete solution for hosting Chatwoot on Heroku's platform. The managed infrastructure and add-on ecosystem make it an excellent choice for teams who want to focus on using Chatwoot rather than managing infrastructure.
For more information, visit the [official Chatwoot Heroku documentation](https://www.chatwoot.com/docs/self-hosted/deployment/heroku).
developer-docs/self-hosted/configuration/environment-variables.mdx
-748
View File
@@ -1,748 +0,0 @@
---
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.
developer-docs/self-hosted/deployment/chatwoot-ctl.mdx
-416
View File
@@ -1,416 +0,0 @@
---
title: Chatwoot CTL (cwctl)
description: Command-line tool for managing Chatwoot installations with ease
sidebarTitle: Chatwoot CTL
---
# Chatwoot CTL (cwctl)
Chatwoot CTL (`cwctl`) is a command-line tool that simplifies the management of your Chatwoot installation. It provides convenient commands for common administrative tasks like upgrades, restarts, console access, and log viewing.
## Installation
### Automatic Installation
`cwctl` is automatically installed when you use the Linux installation script (v2.7.0+):
```bash
wget https://get.chatwoot.app/linux/install.sh
chmod +x install.sh
./install.sh --install
```
### Manual Installation
If you have an older installation or need to install `cwctl` separately:
```bash
# Download and install cwctl
wget https://get.chatwoot.app/linux/install.sh -O /usr/local/bin/cwctl
chmod +x /usr/local/bin/cwctl
# Verify installation
cwctl --help
```
<Note>
The manual installation requires root access to install `cwctl` to `/usr/local/bin`.
</Note>
## Available Commands
### Help and Version
```bash
# Display help information
cwctl --help
cwctl -h
# Show version information
cwctl --version
cwctl -v
```
### Installation Management
```bash
# Install Chatwoot (same as running install.sh --install)
cwctl --install
# Upgrade to the latest version
cwctl --upgrade
# Restart Chatwoot services
cwctl --restart
cwctl -r
```
### Console and Debugging
```bash
# Access Rails console
cwctl --console
cwctl -c
# View web server logs
cwctl --logs web
cwctl -l web
# View worker logs
cwctl --logs worker
cwctl -l worker
# View all logs
cwctl --logs
cwctl -l
```
### Service Management
```bash
# Check service status
cwctl --status
cwctl -s
# Stop Chatwoot services
cwctl --stop
# Start Chatwoot services
cwctl --start
```
## Detailed Command Usage
### Upgrading Chatwoot
The upgrade command handles the complete upgrade process:
```bash
cwctl --upgrade
```
This command performs the following steps:
1. Switches to the chatwoot user
2. Navigates to the Chatwoot directory
3. Pulls the latest code from the master branch
4. Updates Ruby version if needed
5. Installs/updates dependencies (bundle, pnpm)
6. Precompiles assets
7. Runs database migrations
8. Updates systemd service files
9. Restarts services
<Warning>
Always backup your database before upgrading:
```bash
# Create a backup before upgrading
sudo -u postgres pg_dump chatwoot_production > chatwoot_backup_$(date +%Y%m%d).sql
```
</Warning>
### Console Access
Access the Rails console for debugging and administration:
```bash
cwctl --console
```
This opens an interactive Ruby console where you can:
```ruby
# Check application version
Rails.application.config.version
# List all accounts
Account.all
# Find a specific user
User.find_by(email: 'admin@example.com')
# Check system statistics
Account.count
User.count
Conversation.count
# Clear cache
Rails.cache.clear
```
### Log Management
View real-time logs for troubleshooting:
```bash
# Web server logs (Rails application)
cwctl -l web
# Worker logs (Sidekiq background jobs)
cwctl -l worker
# All logs (both web and worker)
cwctl -l
```
### Service Management
Control Chatwoot services:
```bash
# Check if services are running
cwctl --status
# Restart all services (web + worker)
cwctl --restart
# Stop all services
cwctl --stop
# Start all services
cwctl --start
```
## Configuration
### Environment Variables
`cwctl` respects the same environment variables as your Chatwoot installation. Key variables include:
```bash
# Chatwoot installation directory
CHATWOOT_DIR="/home/chatwoot/chatwoot"
# Rails environment
RAILS_ENV="production"
# Database configuration
DATABASE_URL="postgresql://..."
# Redis configuration
REDIS_URL="redis://..."
```
### Custom Installation Paths
If Chatwoot is installed in a non-standard location, you can specify the path:
```bash
# Set custom Chatwoot directory
export CHATWOOT_DIR="/opt/chatwoot"
cwctl --restart
```
## Troubleshooting
### Common Issues
<Accordion title="cwctl command not found">
If `cwctl` is not found, ensure it's installed and in your PATH:
```bash
# Check if cwctl exists
which cwctl
# If not found, install it
wget https://get.chatwoot.app/linux/install.sh -O /usr/local/bin/cwctl
chmod +x /usr/local/bin/cwctl
# Add to PATH if needed
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
</Accordion>
<Accordion title="Permission denied errors">
Ensure you have the necessary permissions:
```bash
# Run with sudo if needed
sudo cwctl --restart
# Or ensure your user is in the chatwoot group
sudo usermod -a -G chatwoot $USER
```
</Accordion>
<Accordion title="Service restart failures">
If services fail to restart, check the logs:
```bash
# Check systemd status
sudo systemctl status chatwoot.target
sudo systemctl status chatwoot-web.1.service
sudo systemctl status chatwoot-worker.1.service
# View detailed logs
sudo journalctl -u chatwoot-web.1.service -f
sudo journalctl -u chatwoot-worker.1.service -f
```
</Accordion>
### Debug Mode
For verbose output during operations:
```bash
# Enable debug mode
export CWCTL_DEBUG=1
cwctl --upgrade
```
### Manual Operations
If `cwctl` fails, you can perform operations manually:
```bash
# Manual upgrade process
sudo -i -u chatwoot
cd chatwoot
git checkout master && git pull
rvm use 3.3.3 --default
bundle install
pnpm install
RAILS_ENV=production bundle exec rake assets:precompile
RAILS_ENV=production bundle exec rake db:migrate
exit
# Restart services manually
sudo systemctl restart chatwoot.target
```
## Best Practices
### Regular Maintenance
```bash
# Weekly upgrade check
cwctl --upgrade
# Daily log monitoring
cwctl -l | grep ERROR
# Monthly service restart
cwctl --restart
```
### Backup Before Operations
```bash
# Create backup script
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
sudo -u postgres pg_dump chatwoot_production > "/backup/chatwoot_$DATE.sql"
cwctl --upgrade
```
### Monitoring
```bash
# Check service health
cwctl --status
# Monitor logs for errors
cwctl -l | grep -E "(ERROR|FATAL|Exception)"
# Check disk space before upgrades
df -h /home/chatwoot
```
## Integration with System Tools
### Systemd Integration
`cwctl` works seamlessly with systemd:
```bash
# These commands are equivalent
cwctl --restart
sudo systemctl restart chatwoot.target
cwctl --status
sudo systemctl status chatwoot.target
```
### Cron Jobs
Automate maintenance tasks:
```bash
# Add to crontab
# Weekly upgrade (Sundays at 2 AM)
0 2 * * 0 /usr/local/bin/cwctl --upgrade
# Daily restart (to clear memory leaks)
0 3 * * * /usr/local/bin/cwctl --restart
```
### Monitoring Scripts
```bash
#!/bin/bash
# Health check script
if ! cwctl --status > /dev/null 2>&1; then
echo "Chatwoot services are down, attempting restart..."
cwctl --restart
# Send alert notification
fi
```
## Advanced Usage
### Custom Commands
You can extend `cwctl` functionality by creating wrapper scripts:
```bash
#!/bin/bash
# custom-cwctl.sh - Extended cwctl with additional features
case "$1" in
--backup)
echo "Creating backup..."
sudo -u postgres pg_dump chatwoot_production > "backup_$(date +%Y%m%d).sql"
;;
--health-check)
echo "Performing health check..."
curl -f http://localhost:3000/api || echo "Health check failed"
;;
*)
cwctl "$@"
;;
esac
```
### Environment-Specific Operations
```bash
# Development environment
RAILS_ENV=development cwctl --console
# Staging environment
RAILS_ENV=staging cwctl --restart
```
---
`cwctl` simplifies Chatwoot administration by providing a unified interface for common tasks. Use it regularly to maintain your installation and troubleshoot issues efficiently.
developer-docs/self-hosted/deployment/docker.mdx
-572
View File
@@ -1,572 +0,0 @@
---
title: Docker Deployment Guide
description: Complete guide to deploy Chatwoot using Docker containers for production environments.
sidebarTitle: Docker
---
Docker provides a consistent, portable way to deploy Chatwoot across different environments. This guide covers production deployment using Docker Compose with best practices for security, performance, and maintenance.
## Prerequisites
Before starting, ensure you have:
- Docker 20.10+ installed
- Docker Compose 2.0+ installed
- At least 4GB RAM and 2 CPU cores
- Domain name with DNS configured (recommended)
- Basic understanding of Docker concepts
### Version Check
Verify your Docker installation:
```bash
$ docker --version
Docker version 25.0.4, build 1a576c5
$ docker compose version
Docker Compose version v2.24.7
```
<Note>
Container names use dashes instead of underscores by default with newer Docker Compose versions. If using an older version, replace `-` with `_` and use `docker-compose` instead of `docker compose`.
</Note>
## Quick Start
### 1. Install Docker
**Ubuntu/Debian:**
```bash
# Update package index
apt-get update && apt-get upgrade -y
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Install Docker Compose plugin
apt install docker-compose-plugin
# Add user to docker group (optional)
sudo usermod -aG docker $USER
```
**CentOS/RHEL:**
```bash
# Install Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin
# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker
```
### 2. Download Configuration Files
```bash
# Create project directory
mkdir chatwoot && cd chatwoot
# Download environment template
wget -O .env https://raw.githubusercontent.com/chatwoot/chatwoot/develop/.env.example
# Download Docker Compose configuration
wget -O docker-compose.yaml https://raw.githubusercontent.com/chatwoot/chatwoot/develop/docker-compose.production.yaml
```
### 3. Configure Environment
Edit the `.env` file with your settings:
```bash
nano .env
```
**Essential configurations:**
```env
# Database Configuration
POSTGRES_PASSWORD=your_secure_postgres_password
REDIS_PASSWORD=your_secure_redis_password
# Application Configuration
SECRET_KEY_BASE=your_secret_key_base_64_chars_long
FRONTEND_URL=https://your-domain.com
# Email Configuration (required for notifications)
MAILER_SENDER_EMAIL=noreply@your-domain.com
SMTP_ADDRESS=smtp.your-provider.com
SMTP_PORT=587
SMTP_USERNAME=your-smtp-username
SMTP_PASSWORD=your-smtp-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
# File Storage (optional - defaults to local)
ACTIVE_STORAGE_SERVICE=local
# For S3: 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=your-bucket-name
```
### 4. Update Docker Compose
Edit `docker-compose.yaml` to match your `.env` passwords:
```yaml
services:
postgres:
environment:
- POSTGRES_PASSWORD=your_secure_postgres_password # Match .env
redis:
command: ["sh", "-c", "redis-server --requirepass your_secure_redis_password"]
```
### 5. Initialize Database
```bash
# Prepare the database
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
```
### 6. Start Services
```bash
# Start all services in background
docker compose up -d
# Check service status
docker compose ps
```
### 7. Verify Installation
```bash
# Check if Chatwoot is responding
curl -I localhost:3000/api
# Should return: HTTP/1.1 200 OK
```
## Production Configuration
### Docker Compose Setup
Here's a complete production-ready `docker-compose.yaml`:
```yaml
version: '3.8'
services:
base: &base
image: chatwoot/chatwoot:latest
env_file: .env
volumes:
- ./data/storage:/app/storage
depends_on:
- postgres
- redis
rails:
<<: *base
container_name: chatwoot-rails
command: ["sh", "-c", "bundle exec rails s -b 0.0.0.0 -p 3000"]
ports:
- "127.0.0.1:3000:3000"
environment:
- NODE_ENV=production
- RAILS_ENV=production
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/api"]
interval: 30s
timeout: 10s
retries: 3
sidekiq:
<<: *base
container_name: chatwoot-sidekiq
command: ["sh", "-c", "bundle exec sidekiq -C config/sidekiq.yml"]
restart: unless-stopped
healthcheck:
test: ["CMD", "pgrep", "-f", "sidekiq"]
interval: 30s
timeout: 10s
retries: 3
postgres:
image: postgres:14-alpine
container_name: chatwoot-postgres
restart: unless-stopped
ports:
- "127.0.0.1:5432:5432"
volumes:
- ./data/postgres:/var/lib/postgresql/data
environment:
- POSTGRES_DB=chatwoot
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=your_secure_postgres_password
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 30s
timeout: 10s
retries: 3
redis:
image: redis:7-alpine
container_name: chatwoot-redis
restart: unless-stopped
command: ["sh", "-c", "redis-server --requirepass your_secure_redis_password"]
ports:
- "127.0.0.1:6379:6379"
volumes:
- ./data/redis:/data
healthcheck:
test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
interval: 30s
timeout: 10s
retries: 3
volumes:
postgres_data:
redis_data:
storage_data:
```
### Nginx Reverse Proxy
Create `/etc/nginx/sites-available/chatwoot.conf`:
```nginx
server {
server_name your-domain.com;
# Point upstream to Chatwoot App Server
set $upstream 127.0.0.1:3000;
# Nginx strips out underscore in headers by default
# Chatwoot relies on underscore in headers for API
underscores_in_headers on;
# Increase client max body size for file uploads
client_max_body_size 50M;
location /.well-known {
alias /var/www/ssl-proof/chatwoot/.well-known;
}
location / {
proxy_pass_header Authorization;
proxy_pass http://$upstream;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Ssl on;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_http_version 1.1;
proxy_buffering off;
proxy_read_timeout 36000s;
proxy_redirect off;
}
listen 80;
}
```
Enable the site and configure SSL:
```bash
# Enable site
sudo ln -s /etc/nginx/sites-available/chatwoot.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
# Install Certbot and get SSL certificate
sudo apt install certbot python3-certbot-nginx
sudo mkdir -p /var/www/ssl-proof/chatwoot/.well-known
sudo certbot --webroot -w /var/www/ssl-proof/chatwoot/ -d your-domain.com -i nginx
```
## Advanced Configuration
### Environment Variables
Key environment variables for production:
```env
# Application
RAILS_ENV=production
NODE_ENV=production
SECRET_KEY_BASE=generate_64_character_secret
FRONTEND_URL=https://your-domain.com
# Database
DATABASE_URL=postgresql://postgres:password@postgres:5432/chatwoot
REDIS_URL=redis://redis:6379/0
REDIS_PASSWORD=your_redis_password
# Email
MAILER_SENDER_EMAIL=noreply@your-domain.com
SMTP_ADDRESS=smtp.your-provider.com
SMTP_PORT=587
SMTP_USERNAME=your_username
SMTP_PASSWORD=your_password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
# File Storage
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=your-bucket-name
# Security
FORCE_SSL=true
RAILS_LOG_TO_STDOUT=true
# Performance
RAILS_MAX_THREADS=5
WEB_CONCURRENCY=2
```
### Resource Limits
Add resource limits to your `docker-compose.yaml`:
```yaml
services:
rails:
deploy:
resources:
limits:
cpus: '2.0'
memory: 2G
reservations:
cpus: '1.0'
memory: 1G
sidekiq:
deploy:
resources:
limits:
cpus: '1.0'
memory: 1G
reservations:
cpus: '0.5'
memory: 512M
postgres:
deploy:
resources:
limits:
cpus: '1.0'
memory: 1G
reservations:
cpus: '0.5'
memory: 512M
redis:
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
reservations:
cpus: '0.25'
memory: 256M
```
### Logging Configuration
Configure centralized logging:
```yaml
services:
rails:
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
sidekiq:
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
```
## Maintenance Operations
### Upgrading Chatwoot
```bash
# Pull latest images
docker compose pull
# Stop services
docker compose down
# Start with new images
docker compose up -d
# Run database migrations
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
```
### Backup and Restore
**Database Backup:**
```bash
# Create backup
docker compose exec postgres pg_dump -U postgres chatwoot > backup_$(date +%Y%m%d_%H%M%S).sql
# Restore backup
docker compose exec -T postgres psql -U postgres chatwoot < backup_file.sql
```
**File Storage Backup:**
```bash
# Backup storage directory
tar -czf storage_backup_$(date +%Y%m%d_%H%M%S).tar.gz ./data/storage/
```
### Monitoring and Logs
**View logs:**
```bash
# All services
docker compose logs -f
# Specific service
docker compose logs -f rails
docker compose logs -f sidekiq
# Last 100 lines
docker compose logs --tail=100 rails
```
**Monitor resources:**
```bash
# Container stats
docker stats
# Service health
docker compose ps
```
### Rails Console Access
```bash
# Access Rails console
docker compose exec rails bundle exec rails console
# Run one-off commands
docker compose run --rm rails bundle exec rails runner "puts User.count"
```
## Troubleshooting
### Common Issues
**1. Permission Issues:**
```bash
# Fix file permissions
sudo chown -R 1000:1000 ./data/
```
**2. Database Connection Issues:**
```bash
# Check database connectivity
docker compose exec rails bundle exec rails db:version
```
**3. Memory Issues:**
```bash
# Check memory usage
docker stats --no-stream
```
**4. SSL Certificate Issues:**
```bash
# Renew certificates
sudo certbot renew --dry-run
```
### Performance Optimization
**1. Database Optimization:**
```sql
-- Connect to database
docker compose exec postgres psql -U postgres chatwoot
-- Check slow queries
SELECT query, mean_time, calls
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;
```
**2. Redis Optimization:**
```bash
# Check Redis memory usage
docker compose exec redis redis-cli info memory
```
### Security Hardening
**1. Network Security:**
```yaml
# Add to docker-compose.yaml
networks:
chatwoot:
driver: bridge
internal: true
services:
rails:
networks:
- chatwoot
- default # Only rails needs external access
```
**2. Secrets Management:**
```bash
# Use Docker secrets for sensitive data
echo "your_secret_password" | docker secret create postgres_password -
```
## Community Edition vs Enterprise
This guide covers Chatwoot Community Edition (CE). For Enterprise features:
**CE Docker Tags:**
- `chatwoot/chatwoot:latest-ce` (latest CE)
- `chatwoot/chatwoot:v2.3.2-ce` (specific version CE)
**Enterprise Features:**
- Advanced reporting and analytics
- SAML SSO integration
- Advanced automation rules
- Priority support
---
<Warning>
Always test upgrades in a staging environment before applying to production. Keep regular backups of your database and file storage.
</Warning>
<Note>
For high-availability deployments, consider using Docker Swarm or Kubernetes instead of Docker Compose.
</Note>
developer-docs/self-hosted/deployment/kubernetes.mdx
-537
View File
@@ -1,537 +0,0 @@
---
title: Kubernetes Deployment
description: Deploy Chatwoot on Kubernetes using Helm charts for scalable, production-ready installations
sidebarTitle: Kubernetes
---
# Kubernetes Deployment Guide
Deploy Chatwoot on Kubernetes using our official Helm charts for a scalable, production-ready installation.
## Prerequisites
Before deploying Chatwoot on Kubernetes, ensure you have:
- **Kubernetes cluster** (v1.19+) with sufficient resources
- **Helm 3.x** installed and configured
- **kubectl** configured to access your cluster
- **Ingress controller** (nginx, traefik, etc.) for external access
- **Cert-manager** (optional, for automatic SSL certificates)
### Minimum Resource Requirements
- **CPU**: 2 cores minimum (4+ cores recommended)
- **Memory**: 4GB RAM minimum (8GB+ recommended)
- **Storage**: 20GB persistent storage for PostgreSQL
- **Nodes**: 3+ nodes for high availability
## Quick Start
### 1. Add Chatwoot Helm Repository
```bash
helm repo add chatwoot https://chatwoot.github.io/charts
helm repo update
```
### 2. Create Namespace
```bash
kubectl create namespace chatwoot
```
### 3. Install with Default Values
```bash
helm install chatwoot chatwoot/chatwoot \
--namespace chatwoot \
--set ingress.enabled=true \
--set ingress.hosts[0].host=chatwoot.yourdomain.com \
--set ingress.hosts[0].paths[0].path=/ \
--set ingress.hosts[0].paths[0].pathType=Prefix
```
## Production Configuration
### Custom Values File
Create a `values.yaml` file for production deployment:
```yaml
# values.yaml
replicaCount: 3
image:
repository: chatwoot/chatwoot
tag: "latest"
pullPolicy: IfNotPresent
env:
RAILS_ENV: production
NODE_ENV: production
FRONTEND_URL: "https://chatwoot.yourdomain.com"
FORCE_SSL: "true"
# Database Configuration
postgresql:
enabled: true
auth:
postgresPassword: "your-secure-password"
database: "chatwoot_production"
primary:
persistence:
enabled: true
size: 50Gi
storageClass: "fast-ssd"
metrics:
enabled: true
# Redis Configuration
redis:
enabled: true
auth:
enabled: true
password: "your-redis-password"
master:
persistence:
enabled: true
size: 10Gi
metrics:
enabled: true
# Ingress Configuration
ingress:
enabled: true
className: "nginx"
annotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
nginx.ingress.kubernetes.io/proxy-body-size: "50m"
nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
hosts:
- host: chatwoot.yourdomain.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: chatwoot-tls
hosts:
- chatwoot.yourdomain.com
# Resource Limits
resources:
limits:
cpu: 2000m
memory: 4Gi
requests:
cpu: 1000m
memory: 2Gi
# Horizontal Pod Autoscaler
autoscaling:
enabled: true
minReplicas: 3
maxReplicas: 10
targetCPUUtilizationPercentage: 70
targetMemoryUtilizationPercentage: 80
# Storage Configuration
persistence:
enabled: true
storageClass: "fast-ssd"
size: 20Gi
# Service Configuration
service:
type: ClusterIP
port: 3000
# Worker Configuration
worker:
enabled: true
replicaCount: 2
resources:
limits:
cpu: 1000m
memory: 2Gi
requests:
cpu: 500m
memory: 1Gi
# Monitoring
serviceMonitor:
enabled: true
namespace: monitoring
```
### Deploy with Custom Configuration
```bash
helm install chatwoot chatwoot/chatwoot \
--namespace chatwoot \
--values values.yaml
```
## External Dependencies
### Using External PostgreSQL
```yaml
postgresql:
enabled: false
env:
DATABASE_URL: "postgresql://username:password@postgres-host:5432/chatwoot_production"
```
### Using External Redis
```yaml
redis:
enabled: false
env:
REDIS_URL: "redis://redis-host:6379/0"
```
### Using Cloud Storage
```yaml
env:
# AWS S3
ACTIVE_STORAGE_SERVICE: "amazon"
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"
# Google Cloud Storage
# ACTIVE_STORAGE_SERVICE: "google"
# GCS_PROJECT: "your-project"
# GCS_BUCKET: "your-bucket"
```
## High Availability Setup
### Multi-Zone Deployment
```yaml
# Spread pods across availability zones
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchExpressions:
- key: app.kubernetes.io/name
operator: In
values:
- chatwoot
topologyKey: topology.kubernetes.io/zone
# Node selection
nodeSelector:
node-type: "application"
# Tolerations for dedicated nodes
tolerations:
- key: "dedicated"
operator: "Equal"
value: "chatwoot"
effect: "NoSchedule"
```
### Database High Availability
```yaml
postgresql:
enabled: true
architecture: replication
auth:
replicationPassword: "replication-password"
primary:
persistence:
enabled: true
size: 100Gi
readReplicas:
replicaCount: 2
persistence:
enabled: true
size: 100Gi
```
## Security Configuration
### Network Policies
```yaml
# network-policy.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: chatwoot-network-policy
namespace: chatwoot
spec:
podSelector:
matchLabels:
app.kubernetes.io/name: chatwoot
policyTypes:
- Ingress
- Egress
ingress:
- from:
- namespaceSelector:
matchLabels:
name: ingress-nginx
ports:
- protocol: TCP
port: 3000
egress:
- to:
- podSelector:
matchLabels:
app.kubernetes.io/name: postgresql
ports:
- protocol: TCP
port: 5432
- to:
- podSelector:
matchLabels:
app.kubernetes.io/name: redis
ports:
- protocol: TCP
port: 6379
```
### Pod Security Standards
```yaml
securityContext:
runAsNonRoot: true
runAsUser: 1001
fsGroup: 1001
seccompProfile:
type: RuntimeDefault
containerSecurityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
runAsNonRoot: true
runAsUser: 1001
capabilities:
drop:
- ALL
```
## Monitoring and Observability
### Prometheus Monitoring
```yaml
serviceMonitor:
enabled: true
labels:
app: chatwoot
interval: 30s
scrapeTimeout: 10s
path: /metrics
# Custom metrics
env:
PROMETHEUS_EXPORTER: "true"
PROMETHEUS_EXPORTER_PORT: "9394"
```
### Logging Configuration
```yaml
# Structured logging
env:
LOG_LEVEL: "info"
LOG_FORMAT: "json"
# Log aggregation with Fluentd/Fluent Bit
annotations:
fluentbit.io/parser: "json"
fluentbit.io/exclude: "false"
```
### Health Checks
```yaml
livenessProbe:
httpGet:
path: /api
port: 3000
initialDelaySeconds: 60
periodSeconds: 30
timeoutSeconds: 10
failureThreshold: 3
readinessProbe:
httpGet:
path: /api
port: 3000
initialDelaySeconds: 30
periodSeconds: 10
timeoutSeconds: 5
failureThreshold: 3
```
## Backup and Disaster Recovery
### Database Backup
```yaml
# CronJob for database backup
apiVersion: batch/v1
kind: CronJob
metadata:
name: chatwoot-db-backup
namespace: chatwoot
spec:
schedule: "0 2 * * *" # Daily at 2 AM
jobTemplate:
spec:
template:
spec:
containers:
- name: postgres-backup
image: postgres:15
command:
- /bin/bash
- -c
- |
pg_dump $DATABASE_URL | gzip > /backup/chatwoot-$(date +%Y%m%d-%H%M%S).sql.gz
# Upload to S3 or other storage
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: chatwoot-secrets
key: database-url
volumeMounts:
- name: backup-storage
mountPath: /backup
volumes:
- name: backup-storage
persistentVolumeClaim:
claimName: backup-pvc
restartPolicy: OnFailure
```
## Upgrading Chatwoot
### Rolling Update
```bash
# Update to latest version
helm upgrade chatwoot chatwoot/chatwoot \
--namespace chatwoot \
--values values.yaml
# Update to specific version
helm upgrade chatwoot chatwoot/chatwoot \
--namespace chatwoot \
--values values.yaml \
--set image.tag="v2.15.0"
```
### Database Migration
```bash
# Run migrations after upgrade
kubectl exec -it deployment/chatwoot -n chatwoot -- \
bundle exec rails db:migrate RAILS_ENV=production
```
## Troubleshooting
### Common Issues
<Tip>
**Pod Startup Issues**: Check resource limits and node capacity
```bash
kubectl describe pod <pod-name> -n chatwoot
kubectl top nodes
```
</Tip>
<Warning>
**Database Connection Issues**: Verify database credentials and network policies
```bash
kubectl logs deployment/chatwoot -n chatwoot
kubectl exec -it deployment/chatwoot -n chatwoot -- nc -zv postgres-host 5432
```
</Warning>
### Debug Commands
```bash
# Check pod status
kubectl get pods -n chatwoot
# View logs
kubectl logs -f deployment/chatwoot -n chatwoot
# Access pod shell
kubectl exec -it deployment/chatwoot -n chatwoot -- /bin/bash
# Check service endpoints
kubectl get endpoints -n chatwoot
# Describe ingress
kubectl describe ingress chatwoot -n chatwoot
```
### Performance Tuning
```yaml
# Optimize for high traffic
env:
RAILS_MAX_THREADS: "20"
WEB_CONCURRENCY: "4"
SIDEKIQ_CONCURRENCY: "25"
resources:
limits:
cpu: 4000m
memory: 8Gi
requests:
cpu: 2000m
memory: 4Gi
# Database connection pooling
env:
DATABASE_POOL_SIZE: "25"
```
## Best Practices
### Resource Management
- Set appropriate resource requests and limits
- Use horizontal pod autoscaling for dynamic scaling
- Monitor resource usage and adjust as needed
### Security
- Use network policies to restrict traffic
- Enable pod security standards
- Regularly update container images
- Use secrets for sensitive configuration
### Monitoring
- Enable Prometheus metrics collection
- Set up alerting for critical metrics
- Monitor application and infrastructure health
- Use distributed tracing for complex issues
### Backup
- Implement automated database backups
- Test backup restoration procedures
- Store backups in multiple locations
- Document recovery procedures
---
This Kubernetes deployment guide provides a solid foundation for running Chatwoot in production. Customize the configuration based on your specific requirements and infrastructure setup.
developer-docs/self-hosted/deployment/linux-vm.mdx
-675
View File
@@ -1,675 +0,0 @@
---
title: Linux VM Deployment Guide
description: Complete guide to deploy Chatwoot on Linux virtual machines using the automated installation script.
sidebarTitle: Linux VM
---
This guide covers deploying Chatwoot on Linux virtual machines using our automated installation script. This method is ideal for traditional server environments and provides full control over the installation process.
## Prerequisites
Before starting, ensure you have:
- Ubuntu 20.04 LTS or later (recommended)
- At least 4GB RAM and 2 CPU cores
- 50GB+ available disk space
- Root or sudo access
- Domain name with DNS configured (optional but recommended)
- SMTP server for email notifications
### Supported Operating Systems
| OS | Version | Status |
|---|---|---|
| **Ubuntu** | 20.04 LTS, 22.04 LTS, 24.04 LTS | ✅ Recommended |
| **Debian** | 10, 11, 12 | ✅ Supported |
| **CentOS** | 8, 9 | ✅ Supported |
| **RHEL** | 8, 9 | ✅ Supported |
| **Amazon Linux** | 2 | ✅ Supported |
## Quick Installation
### 1. Download Installation Script
```bash
# Download the installation script
wget https://get.chatwoot.app/linux/install.sh
# Make it executable
chmod +x install.sh
```
### 2. Run Installation
```bash
# Run the installation script
./install.sh --install
```
The script will:
- Install all required dependencies
- Set up PostgreSQL and Redis
- Install Ruby, Node.js, and other runtime dependencies
- Clone and configure Chatwoot
- Set up systemd services
- Configure Nginx (if domain is provided)
- Set up SSL with Let's Encrypt (if domain is provided)
### 3. Domain Configuration (Optional)
If you have a domain name:
1. **Create DNS A Record**: Point your domain to your server's IP address
2. **During installation**: Enter `yes` when prompted about domain setup
3. **Enter your domain**: The script will configure Nginx and SSL automatically
### 4. Access Your Installation
- **With domain**: `https://your-domain.com`
- **Without domain**: `http://your-server-ip:3000`
**Default login credentials:**
```
URL: https://your-domain.com
Email: john@acme.inc
Password: Password1!
```
## Manual Installation
For more control over the installation process, you can install manually:
### 1. System Preparation
```bash
# Update system packages
sudo apt update && sudo apt upgrade -y
# Install essential packages
sudo apt install -y curl wget gnupg2 software-properties-common apt-transport-https ca-certificates lsb-release
```
### 2. Install Dependencies
**PostgreSQL:**
```bash
# Install PostgreSQL
sudo apt install -y postgresql postgresql-contrib
# Start and enable PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql
# Create database and user
sudo -u postgres psql << EOF
CREATE DATABASE chatwoot;
CREATE USER chatwoot WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE chatwoot TO chatwoot;
ALTER USER chatwoot CREATEDB;
\q
EOF
```
**Redis:**
```bash
# Install Redis
sudo apt install -y redis-server
# Configure Redis
sudo sed -i 's/^# requirepass foobared/requirepass your_redis_password/' /etc/redis/redis.conf
# Start and enable Redis
sudo systemctl start redis-server
sudo systemctl enable redis-server
```
**Ruby (using RVM):**
```bash
# Install RVM
curl -sSL https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm
# Install Ruby
rvm install 3.3.3
rvm use 3.3.3 --default
```
**Node.js:**
```bash
# Install Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Install pnpm
npm install -g pnpm
```
**Additional Dependencies:**
```bash
# Install build tools and libraries
sudo apt install -y git build-essential libssl-dev libreadline-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev libyaml-dev libsqlite3-dev libgdbm-compat-dev libncurses5-dev libreadline6-dev
# Install ImageMagick for image processing
sudo apt install -y imagemagick libmagickwand-dev
# Install FFmpeg for media processing
sudo apt install -y ffmpeg
```
### 3. Install Chatwoot
```bash
# Create chatwoot user
sudo adduser --disabled-login --gecos "" chatwoot
# Switch to chatwoot user
sudo -i -u chatwoot
# Clone Chatwoot repository
git clone https://github.com/chatwoot/chatwoot.git
cd chatwoot
# Checkout latest stable version
git checkout master
# Install Ruby dependencies
bundle install
# Install Node.js dependencies
pnpm install
# Copy environment file
cp .env.example .env
```
### 4. Configure Environment
Edit the `.env` file:
```bash
nano .env
```
**Essential configurations:**
```env
# Database Configuration
DATABASE_URL=postgresql://chatwoot:your_secure_password@localhost:5432/chatwoot
# Redis Configuration
REDIS_URL=redis://localhost:6379/0
REDIS_PASSWORD=your_redis_password
# Application Configuration
SECRET_KEY_BASE=generate_a_64_character_secret_key
FRONTEND_URL=https://your-domain.com
# Email Configuration
MAILER_SENDER_EMAIL=noreply@your-domain.com
SMTP_ADDRESS=smtp.your-provider.com
SMTP_PORT=587
SMTP_USERNAME=your-smtp-username
SMTP_PASSWORD=your-smtp-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
# File Storage (optional)
ACTIVE_STORAGE_SERVICE=local
# For S3: 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=your-bucket-name
# Security
FORCE_SSL=true
RAILS_ENV=production
NODE_ENV=production
```
### 5. Setup Database
```bash
# Prepare the database
RAILS_ENV=production bundle exec rails db:chatwoot_prepare
# Precompile assets
RAILS_ENV=production bundle exec rails assets:precompile
```
### 6. Configure Systemd Services
Create systemd service files:
**Web Service (`/etc/systemd/system/chatwoot-web.1.service`):**
```ini
[Unit]
Description=Chatwoot web server
After=network.target
[Service]
Type=simple
User=chatwoot
WorkingDirectory=/home/chatwoot/chatwoot
Environment=RAILS_ENV=production
Environment=BUNDLE_GEMFILE=/home/chatwoot/chatwoot/Gemfile
ExecStart=/home/chatwoot/.rvm/bin/rvm default do bundle exec rails server -b 0.0.0.0 -p 3000 -e production
Restart=always
RestartSec=1
[Install]
WantedBy=multi-user.target
```
**Worker Service (`/etc/systemd/system/chatwoot-worker.1.service`):**
```ini
[Unit]
Description=Chatwoot sidekiq worker
After=network.target
[Service]
Type=simple
User=chatwoot
WorkingDirectory=/home/chatwoot/chatwoot
Environment=RAILS_ENV=production
Environment=BUNDLE_GEMFILE=/home/chatwoot/chatwoot/Gemfile
ExecStart=/home/chatwoot/.rvm/bin/rvm default do bundle exec sidekiq -C config/sidekiq.yml
Restart=always
RestartSec=1
[Install]
WantedBy=multi-user.target
```
**Target Service (`/etc/systemd/system/chatwoot.target`):**
```ini
[Unit]
Description=Chatwoot services
Wants=chatwoot-web.1.service chatwoot-worker.1.service
[Install]
WantedBy=multi-user.target
```
Enable and start services:
```bash
# Reload systemd
sudo systemctl daemon-reload
# Enable and start Chatwoot services
sudo systemctl enable chatwoot.target
sudo systemctl start chatwoot.target
# Check status
sudo systemctl status chatwoot.target
```
### 7. Configure Nginx
Install and configure Nginx:
```bash
# Install Nginx
sudo apt install -y nginx
# Create Nginx configuration
sudo nano /etc/nginx/sites-available/chatwoot
```
**Nginx configuration:**
```nginx
server {
server_name your-domain.com;
# Point upstream to Chatwoot App Server
set $upstream 127.0.0.1:3000;
# Nginx strips out underscore in headers by default
# Chatwoot relies on underscore in headers for API
underscores_in_headers on;
# Increase client max body size for file uploads
client_max_body_size 50M;
location /.well-known {
alias /var/www/ssl-proof/chatwoot/.well-known;
}
location / {
proxy_pass_header Authorization;
proxy_pass http://$upstream;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Ssl on;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_http_version 1.1;
proxy_buffering off;
proxy_read_timeout 36000s;
proxy_redirect off;
}
listen 80;
}
```
Enable the site:
```bash
# Enable site
sudo ln -s /etc/nginx/sites-available/chatwoot /etc/nginx/sites-enabled/
# Test configuration
sudo nginx -t
# Restart Nginx
sudo systemctl restart nginx
```
### 8. Setup SSL with Let's Encrypt
```bash
# Install Certbot
sudo apt install -y certbot python3-certbot-nginx
# Create directory for SSL verification
sudo mkdir -p /var/www/ssl-proof/chatwoot/.well-known
# Get SSL certificate
sudo certbot --webroot -w /var/www/ssl-proof/chatwoot/ -d your-domain.com -i nginx
# Test automatic renewal
sudo certbot renew --dry-run
```
## Chatwoot CLI (cwctl)
Starting with Chatwoot v2.7.0, the installation includes the Chatwoot CLI for easier management:
### Installation
If you don't have `cwctl` installed:
```bash
# Download and install cwctl
sudo wget https://get.chatwoot.app/linux/install.sh -O /usr/local/bin/cwctl
sudo chmod +x /usr/local/bin/cwctl
# Verify installation
cwctl --help
```
### Usage
```bash
# Restart Chatwoot services
cwctl -r
# Upgrade Chatwoot
cwctl --upgrade
# Access Rails console
cwctl -c
# View logs
cwctl -l web # Web server logs
cwctl -l worker # Worker logs
# Get help
cwctl --help
```
## Maintenance Operations
### Upgrading Chatwoot
**Using cwctl (recommended):**
```bash
cwctl --upgrade
```
**Manual upgrade:**
```bash
# Switch to chatwoot user
sudo -i -u chatwoot
cd chatwoot
# Pull latest changes
git checkout master && git pull
# Update Ruby version if needed
rvm install "ruby-3.3.3"
rvm use 3.3.3 --default
# Update dependencies
bundle install
pnpm install
# Precompile assets
RAILS_ENV=production bundle exec rails assets:precompile
# Run database migrations
RAILS_ENV=production bundle exec rails db:migrate
# Exit to root user
exit
# Update systemd service files
sudo cp /home/chatwoot/chatwoot/deployment/chatwoot-web.1.service /etc/systemd/system/
sudo cp /home/chatwoot/chatwoot/deployment/chatwoot-worker.1.service /etc/systemd/system/
sudo cp /home/chatwoot/chatwoot/deployment/chatwoot.target /etc/systemd/system/
# Reload and restart services
sudo systemctl daemon-reload
sudo systemctl restart chatwoot.target
```
### Backup and Restore
**Database Backup:**
```bash
# Create backup
sudo -u postgres pg_dump chatwoot > chatwoot_backup_$(date +%Y%m%d_%H%M%S).sql
# Restore backup
sudo -u postgres psql chatwoot < chatwoot_backup_file.sql
```
**File Storage Backup:**
```bash
# Backup storage directory
sudo tar -czf chatwoot_storage_$(date +%Y%m%d_%H%M%S).tar.gz /home/chatwoot/chatwoot/storage/
```
**Complete System Backup:**
```bash
# Create backup script
cat > /home/chatwoot/backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/backup/chatwoot/$(date +%Y%m%d_%H%M%S)"
mkdir -p $BACKUP_DIR
# Database backup
sudo -u postgres pg_dump chatwoot > $BACKUP_DIR/database.sql
# Application files
tar -czf $BACKUP_DIR/application.tar.gz /home/chatwoot/chatwoot/
# Storage files
tar -czf $BACKUP_DIR/storage.tar.gz /home/chatwoot/chatwoot/storage/
# Environment file
cp /home/chatwoot/chatwoot/.env $BACKUP_DIR/
echo "Backup completed: $BACKUP_DIR"
EOF
chmod +x /home/chatwoot/backup.sh
```
### Monitoring and Logs
**View logs:**
```bash
# Web server logs
sudo journalctl -u chatwoot-web.1.service -f
# Worker logs
sudo journalctl -u chatwoot-worker.1.service -f
# Nginx logs
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log
# PostgreSQL logs
sudo tail -f /var/log/postgresql/postgresql-*.log
```
**System monitoring:**
```bash
# Check service status
sudo systemctl status chatwoot.target
# Check resource usage
htop
df -h
free -h
# Check database connections
sudo -u postgres psql -c "SELECT count(*) FROM pg_stat_activity;"
```
### Rails Console Access
```bash
# Using cwctl
cwctl -c
# Manual access
sudo -i -u chatwoot
cd chatwoot
RAILS_ENV=production bundle exec rails console
```
## Troubleshooting
### Common Issues
**1. Asset Precompilation Fails:**
```bash
# Clear and rebuild assets
sudo -i -u chatwoot
cd chatwoot
RAILS_ENV=production bundle exec rails assets:clean assets:clobber assets:precompile
```
**2. Database Connection Issues:**
```bash
# Check PostgreSQL status
sudo systemctl status postgresql
# Test database connection
sudo -u postgres psql -c "SELECT version();"
# Check database configuration
sudo -i -u chatwoot
cd chatwoot
RAILS_ENV=production bundle exec rails db:version
```
**3. Permission Issues:**
```bash
# Fix file permissions
sudo chown -R chatwoot:chatwoot /home/chatwoot/chatwoot/
```
**4. Service Won't Start:**
```bash
# Check service logs
sudo journalctl -u chatwoot-web.1.service --no-pager
sudo journalctl -u chatwoot-worker.1.service --no-pager
# Check configuration
sudo systemctl status chatwoot.target
```
### Performance Optimization
**1. Database Optimization:**
```sql
-- Connect to database
sudo -u postgres psql chatwoot
-- Check database size
SELECT pg_size_pretty(pg_database_size('chatwoot'));
-- Check slow queries (if pg_stat_statements is enabled)
SELECT query, mean_time, calls
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;
```
**2. System Optimization:**
```bash
# Increase file limits for chatwoot user
echo "chatwoot soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "chatwoot hard nofile 65536" | sudo tee -a /etc/security/limits.conf
# Optimize PostgreSQL configuration
sudo nano /etc/postgresql/*/main/postgresql.conf
# Adjust shared_buffers, effective_cache_size, work_mem based on available RAM
```
### Security Hardening
**1. Firewall Configuration:**
```bash
# Install and configure UFW
sudo ufw enable
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
```
**2. Fail2ban Setup:**
```bash
# Install Fail2ban
sudo apt install -y fail2ban
# Configure Fail2ban for SSH
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
```
**3. Regular Updates:**
```bash
# Create update script
cat > /home/chatwoot/update_system.sh << 'EOF'
#!/bin/bash
sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y
sudo apt autoclean
EOF
chmod +x /home/chatwoot/update_system.sh
# Add to crontab for weekly updates
echo "0 2 * * 0 /home/chatwoot/update_system.sh" | sudo crontab -
```
---
<Warning>
Always test upgrades in a staging environment before applying to production. Keep regular backups of your database and application files.
</Warning>
<Note>
For high-availability deployments, consider setting up multiple servers with load balancing and database replication.
</Note>
developer-docs/self-hosted/introduction.mdx
-127
View File
@@ -1,127 +0,0 @@
---
title: Self-Hosted Installation Guide
description: Complete guide to install and setup a production-ready Chatwoot instance on your own infrastructure.
sidebarTitle: Introduction
---
Welcome to the Chatwoot self-hosted installation guide. This comprehensive documentation will help you deploy, configure, and maintain your own Chatwoot instance with full control over your data and infrastructure.
## Why Self-Host Chatwoot?
Self-hosting Chatwoot gives you complete control over your customer support platform:
- **Data Privacy**: Keep all customer data on your own servers
- **Customization**: Modify the platform to fit your specific needs
- **Cost Control**: No per-agent pricing - scale as much as you need
- **Compliance**: Meet specific regulatory requirements
- **Integration**: Deep integration with your existing infrastructure
## Deployment Options
Chatwoot supports multiple deployment methods to fit different infrastructure needs:
### 🐧 Linux VM Deployment
Deploy directly on Ubuntu/Linux virtual machines with our automated installation script.
- **Best for**: Traditional server environments
- **Complexity**: Low to Medium
- **Maintenance**: Manual updates required
### 🐳 Docker Deployment
Use Docker containers for consistent, portable deployments.
- **Best for**: Containerized environments
- **Complexity**: Medium
- **Maintenance**: Easy updates with container pulls
### ☸️ Kubernetes Deployment
Deploy on Kubernetes clusters for enterprise-scale operations.
- **Best for**: Large-scale, high-availability deployments
- **Complexity**: High
- **Maintenance**: Automated with proper CI/CD
### ☁️ Cloud Provider Deployments
One-click deployments on major cloud platforms:
- **AWS**: EC2, ECS, and Marketplace options
- **Azure**: Container Instances and VM deployments
- **DigitalOcean**: Droplets and App Platform
- **Google Cloud**: Compute Engine and Cloud Run
- **Heroku**: Simple one-click deployment
## System Requirements
### Minimum Requirements
- **CPU**: 2 cores
- **RAM**: 4GB
- **Storage**: 20GB SSD
- **OS**: Ubuntu 20.04+ or compatible Linux distribution
### Recommended for Production
- **CPU**: 4+ cores
- **RAM**: 8GB+
- **Storage**: 50GB+ SSD
- **Database**: PostgreSQL 12+
- **Cache**: Redis 6+
- **Reverse Proxy**: Nginx or similar
## What You'll Need
Before starting your Chatwoot installation, ensure you have:
### Technical Requirements
- [ ] Server or cloud instance meeting minimum requirements
- [ ] Domain name (recommended for production)
- [ ] SSL certificate (Let's Encrypt recommended)
- [ ] SMTP server for email notifications
### Access Requirements
- [ ] SSH access to your server
- [ ] Root or sudo privileges
- [ ] Firewall configuration access
### Optional but Recommended
- [ ] Object storage (AWS S3, Google Cloud Storage, etc.)
- [ ] CDN for static assets
- [ ] Monitoring tools (APM, logging)
- [ ] Backup solution
## Security Considerations
When self-hosting Chatwoot, consider these security aspects:
- **Regular Updates**: Keep Chatwoot and system packages updated
- **Firewall Configuration**: Only expose necessary ports
- **SSL/TLS**: Always use HTTPS in production
- **Database Security**: Secure PostgreSQL with strong passwords
- **Backup Encryption**: Encrypt sensitive backup data
- **Access Control**: Implement proper user access controls
## Getting Started
Ready to deploy Chatwoot? Choose your preferred deployment method:
<CardGroup cols={2}>
<Card title="Quick Start with Docker" icon="docker" href="/self-hosted/deployment/docker">
Get up and running quickly with Docker containers
</Card>
<Card title="Linux VM Installation" icon="server" href="/self-hosted/deployment/linux-vm">
Traditional server deployment with our automated script
</Card>
<Card title="Kubernetes Deployment" icon="dharmachakra" href="/self-hosted/deployment/kubernetes">
Enterprise-scale deployment on Kubernetes
</Card>
<Card title="Cloud Providers" icon="cloud" href="/self-hosted/cloud/aws">
One-click deployments on major cloud platforms
</Card>
</CardGroup>
## Community and Support
- **Documentation**: Comprehensive guides and API references
- **GitHub**: [Source code and issue tracking](https://github.com/chatwoot/chatwoot)
- **Discord**: [Community chat and support](https://discord.gg/cJXdrwS)
- **Forum**: [Community discussions and Q&A](https://github.com/chatwoot/chatwoot/discussions)
---
<Note>
This documentation covers Chatwoot Community Edition (CE). For Enterprise features and support, visit [Chatwoot Enterprise](https://www.chatwoot.com/pricing).
</Note>
developer-docs/self-hosted/requirements.mdx
-339
View File
@@ -1,339 +0,0 @@
---
title: System Requirements
description: Hardware, software, and infrastructure requirements for deploying Chatwoot in different environments.
sidebarTitle: Requirements
---
Before deploying Chatwoot, ensure your infrastructure meets the minimum requirements for your expected usage. This guide covers requirements for different deployment scenarios and scales.
## Minimum System Requirements
### Development Environment
For local development and testing:
| Component | Requirement |
|-----------|-------------|
| **CPU** | 2 cores (2.0 GHz+) |
| **RAM** | 4GB |
| **Storage** | 20GB available space |
| **OS** | Ubuntu 20.04+, macOS 10.15+, Windows 10+ |
| **Network** | Broadband internet connection |
### Small Production (1-10 agents)
For small teams and low-volume usage:
| Component | Requirement |
|-----------|-------------|
| **CPU** | 2 cores (2.4 GHz+) |
| **RAM** | 4GB |
| **Storage** | 50GB SSD |
| **Network** | 100 Mbps bandwidth |
| **Concurrent Users** | Up to 100 |
### Medium Production (10-50 agents)
For growing teams with moderate usage:
| Component | Requirement |
|-----------|-------------|
| **CPU** | 4 cores (2.4 GHz+) |
| **RAM** | 8GB |
| **Storage** | 100GB SSD |
| **Network** | 500 Mbps bandwidth |
| **Concurrent Users** | Up to 500 |
### Large Production (50+ agents)
For enterprise deployments with high volume:
| Component | Requirement |
|-----------|-------------|
| **CPU** | 8+ cores (2.4 GHz+) |
| **RAM** | 16GB+ |
| **Storage** | 200GB+ SSD |
| **Network** | 1 Gbps+ bandwidth |
| **Concurrent Users** | 1000+ |
## Software Requirements
### Operating System
**Supported Linux Distributions:**
- Ubuntu 20.04 LTS or later (recommended)
- Ubuntu 22.04 LTS
- Debian 10 or later
- CentOS 8 or later
- RHEL 8 or later
- Amazon Linux 2
**Container Platforms:**
- Docker 20.10+ with Docker Compose 2.0+
- Kubernetes 1.20+
- OpenShift 4.6+
### Runtime Dependencies
| Component | Version | Purpose |
|-----------|---------|---------|
| **Ruby** | 3.3.3+ | Application runtime |
| **Node.js** | 20.x LTS | Frontend build tools |
| **PostgreSQL** | 12+ | Primary database |
| **Redis** | 6.0+ | Cache and job queue |
| **Nginx** | 1.18+ | Reverse proxy |
### Development Dependencies
For building from source:
| Component | Version | Purpose |
|-----------|---------|---------|
| **Git** | 2.25+ | Source code management |
| **Build tools** | Latest | Compiling native extensions |
| **ImageMagick** | 7.0+ | Image processing |
| **FFmpeg** | 4.0+ | Video/audio processing |
## Database Requirements
### PostgreSQL Configuration
**Minimum Version:** PostgreSQL 12+
**Recommended Version:** PostgreSQL 14+
**Required Extensions:**
- `pg_stat_statements` (performance monitoring)
- `uuid-ossp` (UUID generation)
- `pg_trgm` (full-text search)
**Configuration Recommendations:**
```sql
-- Memory settings (adjust based on available RAM)
shared_buffers = 256MB # 25% of RAM for small instances
effective_cache_size = 1GB # 75% of RAM
work_mem = 4MB # Per connection
maintenance_work_mem = 64MB # For maintenance operations
-- Connection settings
max_connections = 100 # Adjust based on expected load
max_prepared_transactions = 100 # For prepared statements
-- Write-ahead logging
wal_buffers = 16MB # WAL buffer size
checkpoint_completion_target = 0.9 # Checkpoint target
```
### Redis Configuration
**Minimum Version:** Redis 6.0+
**Recommended Version:** Redis 7.0+
**Memory Requirements:**
- **Small deployment:** 512MB
- **Medium deployment:** 2GB
- **Large deployment:** 4GB+
**Configuration Recommendations:**
```redis
# Memory management
maxmemory 2gb
maxmemory-policy allkeys-lru
# Persistence (choose one)
save 900 1 # RDB snapshots
# appendonly yes # AOF logging
# Security
requirepass your_secure_password
```
## Network Requirements
### Ports
| Port | Protocol | Purpose | External Access |
|------|----------|---------|-----------------|
| **80** | HTTP | Web traffic (redirect to HTTPS) | Yes |
| **443** | HTTPS | Secure web traffic | Yes |
| **3000** | HTTP | Application server (behind proxy) | No |
| **5432** | TCP | PostgreSQL database | No |
| **6379** | TCP | Redis cache | No |
| **22** | SSH | Server administration | Admin only |
### Firewall Configuration
**Inbound Rules:**
```bash
# Allow HTTP and HTTPS
ufw allow 80/tcp
ufw allow 443/tcp
# Allow SSH (restrict to admin IPs)
ufw allow from YOUR_ADMIN_IP to any port 22
# Deny all other inbound traffic
ufw default deny incoming
```
**Outbound Rules:**
```bash
# Allow all outbound (for updates, integrations)
ufw default allow outgoing
# Or restrict to specific services
ufw allow out 53/udp # DNS
ufw allow out 80/tcp # HTTP
ufw allow out 443/tcp # HTTPS
ufw allow out 587/tcp # SMTP
```
### Bandwidth Estimation
**Per Agent (monthly):**
- **Light usage:** 1-2 GB
- **Medium usage:** 3-5 GB
- **Heavy usage:** 8-10 GB
**Per Customer Conversation:**
- **Text only:** 10-50 KB
- **With images:** 500 KB - 2 MB
- **With files:** 1-10 MB
## Storage Requirements
### Disk Space Planning
**Base Installation:** 5-10 GB
**Database Growth:** 100 MB - 1 GB per 1000 conversations
**File Attachments:** Varies by usage (plan for 10-50 GB)
**Logs:** 1-5 GB per month
**Backups:** 2x database size + file storage
### Storage Performance
| Deployment Size | IOPS | Throughput |
|-----------------|------|------------|
| **Small** | 1,000 IOPS | 50 MB/s |
| **Medium** | 3,000 IOPS | 150 MB/s |
| **Large** | 10,000+ IOPS | 500+ MB/s |
### File Storage Options
**Local Storage:**
- Suitable for small deployments
- Requires backup strategy
- Limited scalability
**Object Storage (Recommended):**
- AWS S3, Google Cloud Storage, Azure Blob
- Unlimited scalability
- Built-in redundancy
- CDN integration
## Security Requirements
### SSL/TLS Certificates
**Required for Production:**
- Valid SSL certificate for your domain
- TLS 1.2 or higher
- Strong cipher suites
**Certificate Options:**
- Let's Encrypt (free, automated)
- Commercial certificates
- Wildcard certificates for subdomains
### Access Control
**Server Access:**
- SSH key-based authentication
- Disable password authentication
- Regular security updates
- Fail2ban or similar intrusion prevention
**Application Security:**
- Strong database passwords
- Redis authentication
- Regular security updates
- Web Application Firewall (optional)
## Cloud Provider Specifications
### AWS EC2 Instance Types
| Use Case | Instance Type | vCPU | RAM | Storage |
|----------|---------------|------|-----|---------|
| **Development** | t3.medium | 2 | 4 GB | 20 GB gp3 |
| **Small Production** | t3.large | 2 | 8 GB | 50 GB gp3 |
| **Medium Production** | m5.xlarge | 4 | 16 GB | 100 GB gp3 |
| **Large Production** | m5.2xlarge | 8 | 32 GB | 200 GB gp3 |
### DigitalOcean Droplets
| Use Case | Droplet Size | vCPU | RAM | Storage |
|----------|--------------|------|-----|---------|
| **Development** | 2 GB | 1 | 2 GB | 50 GB SSD |
| **Small Production** | 4 GB | 2 | 4 GB | 80 GB SSD |
| **Medium Production** | 8 GB | 4 | 8 GB | 160 GB SSD |
| **Large Production** | 16 GB | 6 | 16 GB | 320 GB SSD |
### Google Cloud Compute Engine
| Use Case | Machine Type | vCPU | RAM | Storage |
|----------|--------------|------|-----|---------|
| **Development** | e2-medium | 2 | 4 GB | 50 GB SSD |
| **Small Production** | e2-standard-2 | 2 | 8 GB | 100 GB SSD |
| **Medium Production** | e2-standard-4 | 4 | 16 GB | 200 GB SSD |
| **Large Production** | e2-standard-8 | 8 | 32 GB | 500 GB SSD |
## Performance Benchmarks
### Expected Performance
| Metric | Small | Medium | Large |
|--------|-------|--------|-------|
| **Concurrent Users** | 100 | 500 | 1000+ |
| **Messages/minute** | 1,000 | 5,000 | 20,000+ |
| **Response Time** | <200ms | <300ms | <500ms |
| **Uptime** | 99.5% | 99.9% | 99.95% |
### Load Testing
Before production deployment, consider load testing:
```bash
# Example using Apache Bench
ab -n 1000 -c 10 https://your-chatwoot-domain.com/api/v1/accounts
# Example using wrk
wrk -t12 -c400 -d30s https://your-chatwoot-domain.com/
```
## Monitoring Requirements
### Essential Metrics
- **System:** CPU, memory, disk, network
- **Application:** Response times, error rates
- **Database:** Connection count, query performance
- **Redis:** Memory usage, hit rates
### Recommended Tools
- **System Monitoring:** Prometheus + Grafana, DataDog, New Relic
- **Log Management:** ELK Stack, Fluentd, Splunk
- **Uptime Monitoring:** Pingdom, UptimeRobot
- **APM:** New Relic, DataDog APM, Scout
---
<Warning>
These requirements are guidelines. Your actual needs may vary based on usage patterns, integrations, and performance expectations. Monitor your deployment and adjust resources accordingly.
</Warning>
<Note>
For high-availability deployments, consider redundancy in all components and implement proper backup and disaster recovery procedures.
</Note>