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