From f429db89b4646a649856b4f875bdbd7d0f2f043b Mon Sep 17 00:00:00 2001 From: Tanmay Deep Sharma Date: Wed, 28 May 2025 23:42:34 +0530 Subject: [PATCH] add mintlify intro docs --- .../environment-setup/local-development.mdx | 588 ++++++++++ developer-docs/contributing/introduction.mdx | 322 ++++++ .../project-setup/common-errors.mdx | 1004 +++++++++++++++++ .../project-setup/environment-variables.mdx | 658 +++++++++++ .../project-setup/setup-guide.mdx | 589 ++++++++++ developer-docs/docs.json | 55 +- developer-docs/self-hosted/architecture.mdx | 342 ++++++ developer-docs/self-hosted/cloud/aws.mdx | 501 ++++++++ developer-docs/self-hosted/cloud/azure.mdx | 663 +++++++++++ .../self-hosted/cloud/digitalocean.mdx | 670 +++++++++++ developer-docs/self-hosted/cloud/gcp.mdx | 745 ++++++++++++ developer-docs/self-hosted/cloud/heroku.mdx | 505 +++++++++ .../configuration/environment-variables.mdx | 748 ++++++++++++ .../self-hosted/deployment/chatwoot-ctl.mdx | 416 +++++++ .../self-hosted/deployment/docker.mdx | 572 ++++++++++ .../self-hosted/deployment/kubernetes.mdx | 537 +++++++++ .../self-hosted/deployment/linux-vm.mdx | 675 +++++++++++ developer-docs/self-hosted/introduction.mdx | 127 +++ developer-docs/self-hosted/requirements.mdx | 339 ++++++ 19 files changed, 10055 insertions(+), 1 deletion(-) create mode 100644 developer-docs/contributing/environment-setup/local-development.mdx create mode 100644 developer-docs/contributing/introduction.mdx create mode 100644 developer-docs/contributing/project-setup/common-errors.mdx create mode 100644 developer-docs/contributing/project-setup/environment-variables.mdx create mode 100644 developer-docs/contributing/project-setup/setup-guide.mdx create mode 100644 developer-docs/self-hosted/architecture.mdx create mode 100644 developer-docs/self-hosted/cloud/aws.mdx create mode 100644 developer-docs/self-hosted/cloud/azure.mdx create mode 100644 developer-docs/self-hosted/cloud/digitalocean.mdx create mode 100644 developer-docs/self-hosted/cloud/gcp.mdx create mode 100644 developer-docs/self-hosted/cloud/heroku.mdx create mode 100644 developer-docs/self-hosted/configuration/environment-variables.mdx create mode 100644 developer-docs/self-hosted/deployment/chatwoot-ctl.mdx create mode 100644 developer-docs/self-hosted/deployment/docker.mdx create mode 100644 developer-docs/self-hosted/deployment/kubernetes.mdx create mode 100644 developer-docs/self-hosted/deployment/linux-vm.mdx create mode 100644 developer-docs/self-hosted/introduction.mdx create mode 100644 developer-docs/self-hosted/requirements.mdx diff --git a/developer-docs/contributing/environment-setup/local-development.mdx b/developer-docs/contributing/environment-setup/local-development.mdx new file mode 100644 index 000000000..ef85cd909 --- /dev/null +++ b/developer-docs/contributing/environment-setup/local-development.mdx @@ -0,0 +1,588 @@ +--- +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 + + + + Ruby 3.3.3 (managed with rbenv or RVM) + + + Node.js 20+ with pnpm package manager + + + PostgreSQL 13+ for the database + + + Redis 6+ for caching and background jobs + + + +### System Dependencies + + + + ```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 + ``` + + + + ```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 + ``` + + + + ```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 + ``` + + + +## 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 + + +```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 +``` + + + +```bash +# macOS +brew install imagemagick pkg-config + +# Ubuntu/Debian +sudo apt-get install libmagickwand-dev + +# Then reinstall the gem +bundle pristine rmagick +``` + + +### Node.js Issues + + +```bash +# Clear cache and reinstall +pnpm store prune +rm -rf node_modules +pnpm install +``` + + + +```bash +# Clear webpack cache +rm -rf tmp/cache/webpacker +pnpm run dev +``` + + +### Database Issues + + +```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 +``` + + + +```bash +# Reset PostgreSQL user password +sudo -u postgres psql +postgres=# ALTER USER chatwoot PASSWORD 'password'; +postgres=# \q +``` + + +## 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. \ No newline at end of file diff --git a/developer-docs/contributing/introduction.mdx b/developer-docs/contributing/introduction.mdx new file mode 100644 index 000000000..cb29911a9 --- /dev/null +++ b/developer-docs/contributing/introduction.mdx @@ -0,0 +1,322 @@ +--- +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: + + + + Set up development environment on macOS + + + Set up development environment on Ubuntu Linux + + + Set up development environment on Windows + + + Use Docker for consistent development environment + + + +## 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 + +--- + + +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! + + + +Start small with documentation improvements or bug fixes to get familiar with the codebase and contribution process before tackling larger features. + \ No newline at end of file diff --git a/developer-docs/contributing/project-setup/common-errors.mdx b/developer-docs/contributing/project-setup/common-errors.mdx new file mode 100644 index 000000000..5f1909188 --- /dev/null +++ b/developer-docs/contributing/project-setup/common-errors.mdx @@ -0,0 +1,1004 @@ +--- +title: Common Errors and Solutions +description: Troubleshooting guide for common errors during Chatwoot development setup +sidebarTitle: Common Errors +--- + +# Common Errors and Solutions + +This guide covers the most common errors encountered during Chatwoot development setup and their solutions. Use this as a quick reference when troubleshooting issues. + +## Installation and Setup Errors + +### Ruby and Bundler Issues + + +**Error Message**: +``` +An error occurred while installing pg (1.5.4), and Bundler cannot continue. +Make sure that `gem install pg -v '1.5.4'` succeeds before bundling. +``` + +**Cause**: Missing PostgreSQL development headers or incorrect pg_config path. + +**Solutions**: + + + +```bash +# Install PostgreSQL with Homebrew +brew install postgresql + +# Configure bundle to use correct pg_config +bundle config build.pg --with-pg-config=/opt/homebrew/bin/pg_config + +# For Intel Macs +bundle config build.pg --with-pg-config=/usr/local/bin/pg_config + +# Retry bundle install +bundle install +``` + + + +```bash +# Install PostgreSQL development headers +sudo apt-get update +sudo apt-get install libpq-dev postgresql-client + +# Install build essentials +sudo apt-get install build-essential + +# Retry bundle install +bundle install +``` + + + +```bash +# Install PostgreSQL development packages +sudo yum install postgresql-devel + +# Install development tools +sudo yum groupinstall "Development Tools" + +# Retry bundle install +bundle install +``` + + + + + +**Error Message**: +``` +Your Ruby version is 3.1.0, but your Gemfile specified 3.3.3 +``` + +**Cause**: Wrong Ruby version installed. + +**Solutions**: + + + +```bash +# Install correct Ruby version +rbenv install 3.3.3 + +# Set as global version +rbenv global 3.3.3 + +# Verify version +ruby --version + +# Rehash to update shims +rbenv rehash +``` + + + +```bash +# Install correct Ruby version +rvm install 3.3.3 + +# Use the version +rvm use 3.3.3 --default + +# Verify version +ruby --version +``` + + + +```bash +# Install correct Ruby version +asdf install ruby 3.3.3 + +# Set as global version +asdf global ruby 3.3.3 + +# Verify version +ruby --version +``` + + + + + +**Error Message**: +``` +Bundler could not find compatible versions for gem "bundler" +``` + +**Cause**: Incompatible Bundler version. + +**Solution**: +```bash +# Check current Bundler version +bundler --version + +# Install specific Bundler version (check Gemfile.lock) +gem install bundler:2.4.22 + +# Update Bundler +gem update bundler + +# Clean bundle cache +bundle clean --force + +# Retry installation +bundle install +``` + + +### Node.js and Package Manager Issues + + +**Error Message**: +``` +error @chatwoot/chatwoot@1.0.0: The engine "node" is incompatible with this module. +``` + +**Cause**: Wrong Node.js version. + +**Solutions**: + + + +```bash +# Install correct Node.js version +nvm install 20 + +# Use the version +nvm use 20 + +# Set as default +nvm alias default 20 + +# Verify version +node --version +``` + + + +```bash +# Install correct Node.js version +n 20 + +# Verify version +node --version +``` + + + +```bash +# Install correct Node.js version +asdf install nodejs 20.10.0 + +# Set as global version +asdf global nodejs 20.10.0 + +# Verify version +node --version +``` + + + + + +**Error Message**: +``` +pnpm: command not found +``` + +**Cause**: pnpm not installed. + +**Solutions**: +```bash +# Install pnpm globally +npm install -g pnpm + +# Or using corepack (Node.js 16.10+) +corepack enable +corepack prepare pnpm@latest --activate + +# Or using Homebrew (macOS) +brew install pnpm + +# Verify installation +pnpm --version +``` + + + +**Error Message**: +``` +ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies +``` + +**Cause**: Peer dependency conflicts or corrupted cache. + +**Solutions**: +```bash +# Clear pnpm cache +pnpm store prune + +# Remove node_modules and lock file +rm -rf node_modules pnpm-lock.yaml + +# Reinstall with legacy peer deps +pnpm install --legacy-peer-deps + +# Or force installation +pnpm install --force + +# Alternative: use npm +npm install +``` + + +## Database Errors + +### PostgreSQL Connection Issues + + +**Error Message**: +``` +PG::ConnectionBad: could not connect to server: Connection refused +``` + +**Cause**: PostgreSQL service not running or incorrect connection parameters. + +**Solutions**: + + + +```bash +# Check if PostgreSQL is running +brew services list | grep postgresql + +# Start PostgreSQL +brew services start postgresql + +# Check connection +psql postgres -c "SELECT 1;" + +# If user doesn't exist, create it +createuser -s chatwoot +``` + + + +```bash +# Check PostgreSQL status +sudo systemctl status postgresql + +# Start PostgreSQL +sudo systemctl start postgresql +sudo systemctl enable postgresql + +# Switch to postgres user and create chatwoot user +sudo -u postgres createuser -s chatwoot + +# Set password for chatwoot user +sudo -u postgres psql -c "ALTER USER chatwoot PASSWORD 'password';" +``` + + + +```bash +# Start PostgreSQL container +docker run --name postgres-chatwoot \ + -e POSTGRES_USER=chatwoot \ + -e POSTGRES_PASSWORD=password \ + -e POSTGRES_DB=chatwoot_development \ + -p 5432:5432 \ + -d postgres:15 + +# Check if container is running +docker ps | grep postgres +``` + + + + + +**Error Message**: +``` +ActiveRecord::NoDatabaseError: FATAL: database "chatwoot_development" does not exist +``` + +**Cause**: Database not created. + +**Solution**: +```bash +# Create databases +bundle exec rails db:create + +# If that fails, create manually +createdb chatwoot_development +createdb chatwoot_test + +# Or using psql +psql postgres -c "CREATE DATABASE chatwoot_development;" +psql postgres -c "CREATE DATABASE chatwoot_test;" +``` + + + +**Error Message**: +``` +ActiveRecord::PendingMigrationError: Migrations are pending +``` + +**Cause**: Database schema is not up to date. + +**Solutions**: +```bash +# Run pending migrations +bundle exec rails db:migrate + +# If migrations fail, check status +bundle exec rails db:migrate:status + +# Reset database (WARNING: destroys data) +bundle exec rails db:drop db:create db:migrate db:seed + +# For specific migration issues +bundle exec rails db:migrate:up VERSION=20231201000000 +``` + + +### Redis Connection Issues + + +**Error Message**: +``` +Redis::CannotConnectError: Error connecting to Redis on localhost:6379 +``` + +**Cause**: Redis service not running. + +**Solutions**: + + + +```bash +# Check if Redis is running +brew services list | grep redis + +# Start Redis +brew services start redis + +# Test connection +redis-cli ping +``` + + + +```bash +# Check Redis status +sudo systemctl status redis + +# Start Redis +sudo systemctl start redis +sudo systemctl enable redis + +# Test connection +redis-cli ping +``` + + + +```bash +# Start Redis container +docker run --name redis-chatwoot \ + -p 6379:6379 \ + -d redis:7-alpine + +# Test connection +docker exec redis-chatwoot redis-cli ping +``` + + + + +## Application Runtime Errors + +### Rails Server Issues + + +**Error Message**: +``` +Address already in use - bind(2) for "127.0.0.1" port 3000 +``` + +**Cause**: Another process is using port 3000. + +**Solutions**: +```bash +# Find process using port 3000 +lsof -ti:3000 + +# Kill the process +kill -9 $(lsof -ti:3000) + +# Or use a different port +bundle exec rails server -p 3001 + +# Check what's running on the port +netstat -tulpn | grep :3000 +``` + + + +**Error Message**: +``` +ArgumentError: Missing `secret_key_base` for 'development' environment +``` + +**Cause**: SECRET_KEY_BASE not set in environment. + +**Solution**: +```bash +# Generate a new secret key +bundle exec rails secret + +# Add to .env file +echo "SECRET_KEY_BASE=$(bundle exec rails secret)" >> .env + +# Or set temporarily +export SECRET_KEY_BASE=$(bundle exec rails secret) +bundle exec rails server +``` + + + +**Error Message**: +``` +Webpacker::Manifest::MissingEntryError: Webpacker can't find application.js +``` + +**Cause**: Webpack assets not compiled or compilation failed. + +**Solutions**: +```bash +# Check if webpack dev server is running +ps aux | grep webpack + +# Start webpack dev server +pnpm run dev + +# Or compile assets manually +bundle exec rails assets:precompile + +# Clear webpack cache +rm -rf tmp/cache/webpacker +rm -rf public/packs + +# Reinstall node modules +rm -rf node_modules +pnpm install +``` + + +### Sidekiq Worker Issues + + +**Error Message**: +``` +Jobs are queued but not being processed +``` + +**Cause**: Sidekiq worker not running. + +**Solutions**: +```bash +# Check if Sidekiq is running +ps aux | grep sidekiq + +# Start Sidekiq +bundle exec sidekiq + +# Check Sidekiq web interface +open http://localhost:3000/sidekiq + +# Clear failed jobs +bundle exec rails runner "Sidekiq::Queue.new.clear" +``` + + + +**Error Message**: +``` +Redis::CommandError: OOM command not allowed when used memory > 'maxmemory' +``` + +**Cause**: Redis running out of memory. + +**Solutions**: +```bash +# Check Redis memory usage +redis-cli info memory + +# Clear Redis cache +redis-cli flushall + +# Increase Redis memory limit (redis.conf) +# maxmemory 256mb + +# Or restart Redis +brew services restart redis # macOS +sudo systemctl restart redis # Linux +``` + + +## Testing Errors + +### RSpec Test Failures + + +**Error Message**: +``` +ActiveRecord::StatementInvalid: PG::UndefinedTable: ERROR: relation "users" does not exist +``` + +**Cause**: Test database not set up properly. + +**Solution**: +```bash +# Prepare test database +RAILS_ENV=test bundle exec rails db:create +RAILS_ENV=test bundle exec rails db:migrate + +# Or use the combined command +bundle exec rails db:test:prepare + +# Reset test database if needed +RAILS_ENV=test bundle exec rails db:drop db:create db:migrate +``` + + + +**Error Message**: +``` +FactoryBot::DuplicateDefinitionError: Factory already registered +``` + +**Cause**: Factory definitions loaded multiple times. + +**Solution**: +```bash +# Clear Spring cache +bundle exec spring stop + +# Restart test suite +bundle exec rspec + +# Check for duplicate factory definitions +grep -r "FactoryBot.define" spec/ +``` + + + +**Error Message**: +``` +Selenium::WebDriver::Error::WebDriverError: unable to connect to chromedriver +``` + +**Cause**: ChromeDriver not installed or incompatible version. + +**Solutions**: +```bash +# Install ChromeDriver +# macOS +brew install chromedriver + +# Ubuntu/Debian +sudo apt-get install chromium-chromedriver + +# Or use webdrivers gem (should be automatic) +bundle exec rails runner "Webdrivers::Chromedriver.update" + +# Run tests in headless mode +HEADLESS=true bundle exec rspec spec/system/ +``` + + +## Development Environment Issues + +### IDE and Editor Problems + + +**Error**: Ruby IntelliSense not working, no syntax highlighting. + +**Solutions**: +```bash +# Install Ruby LSP +gem install ruby-lsp + +# Or add to Gemfile +echo 'gem "ruby-lsp", group: :development' >> Gemfile +bundle install + +# Restart VS Code +# Install recommended extensions: +# - Ruby LSP +# - Ruby Solargraph +# - Ruby Test Explorer +``` + + + +**Error**: Ruby documentation and autocomplete not working. + +**Solutions**: +```bash +# Install Solargraph +gem install solargraph + +# Generate documentation +bundle exec yard gems +bundle exec solargraph bundle + +# Create .solargraph.yml config +solargraph config + +# Restart your editor +``` + + +### Git and Version Control Issues + + +**Error**: Git commit rejected due to linting errors. + +**Solutions**: +```bash +# Fix RuboCop issues +bundle exec rubocop -a + +# Fix ESLint issues +pnpm run lint:fix + +# Format code +pnpm run format + +# Skip hooks temporarily (not recommended) +git commit --no-verify -m "Your commit message" + +# Update pre-commit hooks +pre-commit autoupdate +``` + + + +**Error**: Git LFS or large file warnings. + +**Solutions**: +```bash +# Install Git LFS +git lfs install + +# Track large files +git lfs track "*.png" +git lfs track "*.jpg" +git lfs track "*.pdf" + +# Add .gitattributes +git add .gitattributes + +# Check LFS status +git lfs status +``` + + +## Performance Issues + +### Slow Application Startup + + +**Cause**: Large codebase, slow database, or memory issues. + +**Solutions**: +```bash +# Use Spring for faster Rails commands +bundle exec spring binstub --all + +# Check Spring status +bundle exec spring status + +# Restart Spring if needed +bundle exec spring stop + +# Increase memory if needed +export RUBY_GC_HEAP_INIT_SLOTS=10000 +export RUBY_GC_HEAP_FREE_SLOTS=10000 + +# Profile startup time +time bundle exec rails runner "puts 'Rails loaded'" +``` + + + +**Cause**: Database setup, factory creation, or inefficient tests. + +**Solutions**: +```bash +# Use parallel testing +bundle exec rspec --parallel + +# Profile slow tests +bundle exec rspec --profile + +# Use database cleaner strategies +# Add to spec/rails_helper.rb: +# config.use_transactional_fixtures = true + +# Optimize factories +# Use build_stubbed instead of create when possible +``` + + +## Email and Communication Issues + +### Email Delivery Problems + + +**Cause**: SMTP configuration or email service issues. + +**Solutions**: + + + +```bash +# Install and start MailHog +brew install mailhog # macOS +mailhog + +# Configure .env +MAILER_SENDER_EMAIL=dev@chatwoot.local +SMTP_ADDRESS=localhost +SMTP_PORT=1025 + +# Check web interface +open http://localhost:8025 +``` + + + +```bash +# Add to Gemfile +echo 'gem "letter_opener", group: :development' >> Gemfile +bundle install + +# Configure in development.rb +# config.action_mailer.delivery_method = :letter_opener + +# Emails will open in browser +``` + + + +```bash +# Use app password, not regular password +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 +``` + + + + +### WebSocket Connection Issues + + +**Error**: Real-time features not working, WebSocket connection failed. + +**Solutions**: +```bash +# Check if ActionCable is mounted +grep -r "mount ActionCable" config/routes.rb + +# Check Redis connection +redis-cli ping + +# Configure ActionCable for development +# In config/environments/development.rb: +# config.action_cable.url = "ws://localhost:3000/cable" +# config.action_cable.allowed_request_origins = ["http://localhost:3000"] + +# Test WebSocket connection +# Open browser console and check for WebSocket errors +``` + + +## Debugging and Logging Issues + +### Log File Problems + + +**Cause**: Excessive logging in development. + +**Solutions**: +```bash +# Clear log files +> log/development.log +> log/test.log + +# Configure log rotation in development.rb +# config.logger = ActiveSupport::Logger.new("log/development.log", 5, 10.megabytes) + +# Reduce log level +# config.log_level = :info + +# Use logrotate (Linux) +sudo logrotate -f /etc/logrotate.conf +``` + + +### Debugging Tool Issues + + +**Cause**: Debugger not properly configured or running in wrong context. + +**Solutions**: +```bash +# Make sure gems are in Gemfile +echo 'gem "pry-rails", group: [:development, :test]' >> Gemfile +echo 'gem "pry-byebug", group: [:development, :test]' >> Gemfile +bundle install + +# Use correct debugger syntax +# binding.pry # for Pry +# debugger # for built-in debugger +# byebug # for byebug + +# Check if running in correct environment +puts Rails.env +``` + + +## Quick Diagnostic Commands + +### System Health Check + +```bash +#!/bin/bash +# health_check.sh - Quick system diagnostic + +echo "=== Chatwoot Development Health Check ===" + +# Check Ruby version +echo "Ruby version: $(ruby --version)" + +# Check Node.js version +echo "Node.js version: $(node --version)" + +# Check database connection +if bundle exec rails runner "ActiveRecord::Base.connection.execute('SELECT 1')" > /dev/null 2>&1; then + echo "✅ Database connection: OK" +else + echo "❌ Database connection: FAILED" +fi + +# Check Redis connection +if redis-cli ping > /dev/null 2>&1; then + echo "✅ Redis connection: OK" +else + echo "❌ Redis connection: FAILED" +fi + +# Check if services are running +echo "Running processes:" +ps aux | grep -E "(rails|sidekiq|webpack|mailhog)" | grep -v grep + +# Check ports +echo "Port usage:" +lsof -i :3000,3035,6379,5432,8025 2>/dev/null || echo "No processes found on common ports" + +echo "=== Health Check Complete ===" +``` + +### Environment Validation + +```bash +#!/bin/bash +# validate_env.sh - Validate development environment + +required_vars=( + "RAILS_ENV" + "DATABASE_URL" + "REDIS_URL" + "SECRET_KEY_BASE" + "FRONTEND_URL" +) + +echo "=== Environment Variable Check ===" +for var in "${required_vars[@]}"; do + if [ -z "${!var}" ]; then + echo "❌ Missing: $var" + else + echo "✅ Set: $var" + fi +done + +echo "=== Dependency Check ===" +commands=("ruby" "node" "psql" "redis-cli" "git") +for cmd in "${commands[@]}"; do + if command -v $cmd > /dev/null 2>&1; then + echo "✅ $cmd: $(command -v $cmd)" + else + echo "❌ $cmd: Not found" + fi +done +``` + +## Getting Additional Help + +If you're still experiencing issues after trying these solutions: + +1. **Search GitHub Issues**: Check if others have reported similar problems +2. **Check Logs**: Look at `log/development.log` for detailed error messages +3. **Discord Community**: Join the Chatwoot Discord for real-time help +4. **Documentation**: Review the official documentation +5. **Create an Issue**: If it's a bug, create a detailed GitHub issue + +### Creating a Good Bug Report + +When reporting issues, include: + +```markdown +## Environment +- OS: [e.g., macOS 13.0, Ubuntu 22.04] +- Ruby version: [e.g., 3.3.3] +- Node.js version: [e.g., 20.10.0] +- Database: [e.g., PostgreSQL 15.0] + +## Steps to Reproduce +1. Step one +2. Step two +3. Step three + +## Expected Behavior +What you expected to happen + +## Actual Behavior +What actually happened + +## Error Messages +``` +Full error message and stack trace +``` + +## Additional Context +Any other relevant information +``` + +--- + +This guide covers the most common development issues. For production deployment issues, see the [Self-hosted documentation](../../self-hosted/). \ No newline at end of file diff --git a/developer-docs/contributing/project-setup/environment-variables.mdx b/developer-docs/contributing/project-setup/environment-variables.mdx new file mode 100644 index 000000000..570dcf482 --- /dev/null +++ b/developer-docs/contributing/project-setup/environment-variables.mdx @@ -0,0 +1,658 @@ +--- +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 + + +**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;" +``` + + + +**Problem**: `Redis::CannotConnectError` + +**Check these variables**: +```bash +REDIS_URL=redis://localhost:6379/0 +``` + +**Verify connection**: +```bash +redis-cli -u $REDIS_URL ping +``` + + + +**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 +``` + + + +**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 +``` + + +### 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. \ No newline at end of file diff --git a/developer-docs/contributing/project-setup/setup-guide.mdx b/developer-docs/contributing/project-setup/setup-guide.mdx new file mode 100644 index 000000000..2e06ffffc --- /dev/null +++ b/developer-docs/contributing/project-setup/setup-guide.mdx @@ -0,0 +1,589 @@ +--- +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 + + +**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 +``` + + + +**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 +``` + + + +**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 +``` + + + +**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 +``` + + +### 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. \ No newline at end of file diff --git a/developer-docs/docs.json b/developer-docs/docs.json index a2ff9d1f6..e7e6c55af 100644 --- a/developer-docs/docs.json +++ b/developer-docs/docs.json @@ -30,11 +30,64 @@ "navigation": { "groups": [ { - "group": "API Reference", + "group": "Getting Started", "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", diff --git a/developer-docs/self-hosted/architecture.mdx b/developer-docs/self-hosted/architecture.mdx new file mode 100644 index 000000000..98c3b0f8c --- /dev/null +++ b/developer-docs/self-hosted/architecture.mdx @@ -0,0 +1,342 @@ +--- +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 + +--- + + +Understanding this architecture helps you make informed decisions about deployment, scaling, and maintenance of your Chatwoot instance. + \ No newline at end of file diff --git a/developer-docs/self-hosted/cloud/aws.mdx b/developer-docs/self-hosted/cloud/aws.mdx new file mode 100644 index 000000000..eb3cf9298 --- /dev/null +++ b/developer-docs/self-hosted/cloud/aws.mdx @@ -0,0 +1,501 @@ +--- +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 + + + + Full control over the deployment with custom architecture + + + Quick deployment using pre-configured AMI + + + +## 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 | + + +Enable "Auto-assign public IPv4 address" for public subnets under Actions > Subnet Settings. + + +#### 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` + + +Note down the RDS endpoint, username, and password for later configuration. + + +### 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 + + +Check: +- Security group rules +- Target group health +- Route table configuration +- DNS resolution + + + +Verify: +- RDS security group allows connections +- Database credentials in .env file +- Network connectivity from app servers + + + +Solutions: +- Increase instance size +- Optimize Sidekiq concurrency +- Enable swap memory +- Monitor for memory leaks + + +### 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. \ No newline at end of file diff --git a/developer-docs/self-hosted/cloud/azure.mdx b/developer-docs/self-hosted/cloud/azure.mdx new file mode 100644 index 000000000..c467e28f3 --- /dev/null +++ b/developer-docs/self-hosted/cloud/azure.mdx @@ -0,0 +1,663 @@ +--- +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 + + + + Full control with custom VM deployment + + + Serverless container deployment + + + Platform-as-a-Service deployment + + + +## 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@ + +# 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 \ + --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 \ + --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 \ + --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 + + +Check: +- PostgreSQL firewall rules +- Network security group rules +- Connection string format +- SSL requirements for Azure Database + + + +Verify: +- Redis access keys +- SSL configuration (required for Azure Cache) +- Network connectivity +- Port 6380 (SSL) vs 6379 (non-SSL) + + + +Solutions: +- Verify storage account access keys +- Check container permissions +- Ensure CORS settings if needed +- Validate Azure Storage configuration + + +### 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. \ No newline at end of file diff --git a/developer-docs/self-hosted/cloud/digitalocean.mdx b/developer-docs/self-hosted/cloud/digitalocean.mdx new file mode 100644 index 000000000..279edca3c --- /dev/null +++ b/developer-docs/self-hosted/cloud/digitalocean.mdx @@ -0,0 +1,670 @@ +--- +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 + + + + Traditional VPS deployment with full control + + + Platform-as-a-Service deployment + + + Container orchestration with DOKS + + + +## 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 + + +Check: +- Firewall rules (ufw status) +- DigitalOcean Cloud Firewalls +- SSH key configuration +- Network connectivity + + + +Verify: +- Database cluster status +- Connection string format +- SSL requirements for managed databases +- Firewall rules for database access + + + +Solutions: +- Verify health check path (/api) +- Check application startup time +- Ensure proper port configuration +- Review application logs + + +### 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. \ No newline at end of file diff --git a/developer-docs/self-hosted/cloud/gcp.mdx b/developer-docs/self-hosted/cloud/gcp.mdx new file mode 100644 index 000000000..a4770107e --- /dev/null +++ b/developer-docs/self-hosted/cloud/gcp.mdx @@ -0,0 +1,745 @@ +--- +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 + + + + Traditional VM deployment with full control + + + Serverless container deployment + + + Managed Kubernetes deployment + + + +## 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 + + +Check: +- Cloud SQL Proxy configuration +- Service account permissions +- Network connectivity +- SSL requirements + + + +Verify: +- Resource quotas and limits +- Image pull permissions +- Service account configuration +- Network policies + + + +Solutions: +- Verify health check path (/api) +- Check firewall rules +- Ensure proper backend configuration +- Review application startup time + + +### 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. \ No newline at end of file diff --git a/developer-docs/self-hosted/cloud/heroku.mdx b/developer-docs/self-hosted/cloud/heroku.mdx new file mode 100644 index 000000000..2d78df5ad --- /dev/null +++ b/developer-docs/self-hosted/cloud/heroku.mdx @@ -0,0 +1,505 @@ +--- +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. + + +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. + + +## Quick Deployment + +### One-Click Deploy + +The fastest way to get Chatwoot running on Heroku is using the one-click deploy button: + + + Click here to deploy Chatwoot to Heroku with one click + + +### 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 + + +Heroku has an "ephemeral" hard disk. Files uploaded to Chatwoot will not persist after application restarts. You must configure cloud storage. + + +**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 + + +**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` + + + +**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` + + + +**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 + + + +**Symptoms**: Settings page shows "unknown" build version + +**Solution**: +Enable runtime dyno metadata: +```bash +heroku labs:enable runtime-dyno-metadata -a your-app-name +``` + + +### Performance Issues + + +**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` + + + +**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` + + +### 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). \ No newline at end of file diff --git a/developer-docs/self-hosted/configuration/environment-variables.mdx b/developer-docs/self-hosted/configuration/environment-variables.mdx new file mode 100644 index 000000000..4515edd87 --- /dev/null +++ b/developer-docs/self-hosted/configuration/environment-variables.mdx @@ -0,0 +1,748 @@ +--- +title: Environment Variables +description: Complete reference for Chatwoot environment variables and configuration options +sidebarTitle: Environment Variables +--- + +# Environment Variables Reference + +Chatwoot uses environment variables for configuration. This guide provides a comprehensive reference for all available environment variables and their usage. + +## Core Application Settings + +### Basic Configuration + +```bash +# Rails Environment +RAILS_ENV=production + +# Node Environment +NODE_ENV=production + +# Frontend URL (required) +FRONTEND_URL=https://chatwoot.yourdomain.com + +# Force SSL (recommended for production) +FORCE_SSL=true + +# Secret Key Base (auto-generated during installation) +SECRET_KEY_BASE=your-secret-key-base + +# Rails Log Level +RAILS_LOG_LEVEL=info + +# Rails Max Threads +RAILS_MAX_THREADS=5 + +# Web Concurrency (Puma workers) +WEB_CONCURRENCY=2 +``` + +### Application Behavior + +```bash +# Enable/disable account signup +ENABLE_ACCOUNT_SIGNUP=false + +# Auto-assign conversations to online agents +AUTO_ASSIGN_CONVERSATIONS=true + +# Enable conversation continuity (link conversations across sessions) +CONVERSATION_CONTINUITY=true + +# Maximum file upload size (in MB) +MAXIMUM_FILE_UPLOAD_SIZE=40 + +# Enable IP-based rate limiting +ENABLE_IP_RATE_LIMIT=true + +# Rate limit per IP (requests per minute) +IP_RATE_LIMIT=100 +``` + +## Database Configuration + +### PostgreSQL + +```bash +# Database URL (primary configuration method) +DATABASE_URL=postgresql://username:password@hostname:port/database_name + +# Alternative: Individual components +POSTGRES_HOST=localhost +POSTGRES_PORT=5432 +POSTGRES_USERNAME=chatwoot +POSTGRES_PASSWORD=your-password +POSTGRES_DATABASE=chatwoot_production + +# Database pool size +DATABASE_POOL_SIZE=5 + +# Database timeout (seconds) +DATABASE_TIMEOUT=5000 + +# Enable prepared statements +DATABASE_PREPARED_STATEMENTS=true +``` + +### Database SSL Configuration + +```bash +# SSL Mode (disable, allow, prefer, require, verify-ca, verify-full) +DATABASE_SSL_MODE=require + +# SSL Certificate paths (for verify-ca and verify-full modes) +DATABASE_SSL_CERT=/path/to/client-cert.pem +DATABASE_SSL_KEY=/path/to/client-key.pem +DATABASE_SSL_ROOT_CERT=/path/to/ca-cert.pem +``` + +## Redis Configuration + +### Basic Redis Settings + +```bash +# Redis URL (primary configuration method) +REDIS_URL=redis://localhost:6379/0 + +# Alternative: Individual components +REDIS_HOST=localhost +REDIS_PORT=6379 +REDIS_DB=0 +REDIS_PASSWORD=your-redis-password + +# Redis connection pool size +REDIS_POOL_SIZE=5 + +# Redis timeout (seconds) +REDIS_TIMEOUT=1 +``` + +### Redis SSL Configuration + +```bash +# Enable SSL for Redis +REDIS_SSL=true + +# Redis SSL certificate verification +REDIS_SSL_VERIFY=true + +# Redis SSL certificate paths +REDIS_SSL_CERT=/path/to/redis-client.crt +REDIS_SSL_KEY=/path/to/redis-client.key +REDIS_SSL_CA=/path/to/redis-ca.crt +``` + +### Sidekiq Configuration + +```bash +# Sidekiq concurrency (number of worker threads) +SIDEKIQ_CONCURRENCY=10 + +# Sidekiq Redis namespace +SIDEKIQ_REDIS_NAMESPACE=chatwoot_sidekiq + +# Sidekiq log level +SIDEKIQ_LOG_LEVEL=info + +# Enable Sidekiq web UI +SIDEKIQ_WEB_UI=true + +# Sidekiq web UI username/password +SIDEKIQ_WEB_USERNAME=admin +SIDEKIQ_WEB_PASSWORD=your-password +``` + +## Email Configuration + +### SMTP Settings + +```bash +# Sender email address +MAILER_SENDER_EMAIL=noreply@yourdomain.com + +# SMTP server configuration +SMTP_ADDRESS=smtp.gmail.com +SMTP_PORT=587 +SMTP_USERNAME=your-email@gmail.com +SMTP_PASSWORD=your-app-password +SMTP_AUTHENTICATION=plain +SMTP_ENABLE_STARTTLS_AUTO=true +SMTP_OPENSSL_VERIFY_MODE=peer + +# SMTP domain (for HELO command) +SMTP_DOMAIN=yourdomain.com + +# Force TLS +SMTP_TLS=true +``` + +### Email Provider Examples + + + + ```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 + ``` + + + + ```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 + ``` + + + + ```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 + ``` + + + + ```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 + ``` + + + +### 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 + + +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 + + +### Security Best Practices + + +**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 + + +### Performance Optimization + + +**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 + + +--- + +This comprehensive environment variables reference covers all aspects of Chatwoot configuration. Customize these settings based on your specific deployment requirements and infrastructure setup. \ No newline at end of file diff --git a/developer-docs/self-hosted/deployment/chatwoot-ctl.mdx b/developer-docs/self-hosted/deployment/chatwoot-ctl.mdx new file mode 100644 index 000000000..91b6f31ee --- /dev/null +++ b/developer-docs/self-hosted/deployment/chatwoot-ctl.mdx @@ -0,0 +1,416 @@ +--- +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 +``` + + +The manual installation requires root access to install `cwctl` to `/usr/local/bin`. + + +## 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 + + +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 +``` + + +### 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 + + +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 +``` + + + +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 +``` + + + +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 +``` + + +### 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. \ No newline at end of file diff --git a/developer-docs/self-hosted/deployment/docker.mdx b/developer-docs/self-hosted/deployment/docker.mdx new file mode 100644 index 000000000..a083eddf5 --- /dev/null +++ b/developer-docs/self-hosted/deployment/docker.mdx @@ -0,0 +1,572 @@ +--- +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 +``` + + +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`. + + +## 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 + +--- + + +Always test upgrades in a staging environment before applying to production. Keep regular backups of your database and file storage. + + + +For high-availability deployments, consider using Docker Swarm or Kubernetes instead of Docker Compose. + \ No newline at end of file diff --git a/developer-docs/self-hosted/deployment/kubernetes.mdx b/developer-docs/self-hosted/deployment/kubernetes.mdx new file mode 100644 index 000000000..30c45b96b --- /dev/null +++ b/developer-docs/self-hosted/deployment/kubernetes.mdx @@ -0,0 +1,537 @@ +--- +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 + + +**Pod Startup Issues**: Check resource limits and node capacity +```bash +kubectl describe pod -n chatwoot +kubectl top nodes +``` + + + +**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 +``` + + +### 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. \ No newline at end of file diff --git a/developer-docs/self-hosted/deployment/linux-vm.mdx b/developer-docs/self-hosted/deployment/linux-vm.mdx new file mode 100644 index 000000000..d3f30b297 --- /dev/null +++ b/developer-docs/self-hosted/deployment/linux-vm.mdx @@ -0,0 +1,675 @@ +--- +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 - +``` + +--- + + +Always test upgrades in a staging environment before applying to production. Keep regular backups of your database and application files. + + + +For high-availability deployments, consider setting up multiple servers with load balancing and database replication. + \ No newline at end of file diff --git a/developer-docs/self-hosted/introduction.mdx b/developer-docs/self-hosted/introduction.mdx new file mode 100644 index 000000000..32078651d --- /dev/null +++ b/developer-docs/self-hosted/introduction.mdx @@ -0,0 +1,127 @@ +--- +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: + + + + Get up and running quickly with Docker containers + + + Traditional server deployment with our automated script + + + Enterprise-scale deployment on Kubernetes + + + One-click deployments on major cloud platforms + + + +## 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) + +--- + + +This documentation covers Chatwoot Community Edition (CE). For Enterprise features and support, visit [Chatwoot Enterprise](https://www.chatwoot.com/pricing). + \ No newline at end of file diff --git a/developer-docs/self-hosted/requirements.mdx b/developer-docs/self-hosted/requirements.mdx new file mode 100644 index 000000000..da816e55f --- /dev/null +++ b/developer-docs/self-hosted/requirements.mdx @@ -0,0 +1,339 @@ +--- +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 + +--- + + +These requirements are guidelines. Your actual needs may vary based on usage patterns, integrations, and performance expectations. Monitor your deployment and adjust resources accordingly. + + + +For high-availability deployments, consider redundancy in all components and implement proper backup and disaster recovery procedures. + \ No newline at end of file