enable mcp for tool for all endpoints

chatwoot/developer-docs/self-hosted/runbook/environment-variables.mdx

@@ -0,0 +1,264 @@
+---
+title: Environment Variables
+description: Complete reference for Chatwoot environment variables and configuration options
+sidebarTitle: Environment Variables
+---
+
+## The .env File
+
+We use the `dotenv-rails` gem to manage the environment variables. There is a file called `env.example` in the root directory of this project with all the environment variables set to empty values. You can set the correct values as per the following options. Once you set the values, you should rename the file to `.env` before you start the server.
+
+## Configure frontend URL (domain)
+
+Provide your chatwoot domain as frontend URL.
+
+```bash
+FRONTEND_URL='https://your-chatwoot-domain.tld'
+```
+
+## Rails production variables
+
+For production deployment, you have to set the following variables
+
+```bash
+RAILS_ENV=production
+SECRET_KEY_BASE=replace_with_your_own_secret_string
+```
+
+You can generate `SECRET_KEY_BASE` using `rake secret` command from the project root folder. If you dont have rails installed, use `head /dev/urandom | tr -dc A-Za-z0-9 | head -c 63 ; echo ''`.
+
+<Note>
+SECRET_KEY_BASE should be alphanumeric. Avoid special characters or symbols.
+</Note>
+
+## Database configuration
+
+Postgres can be configured in two ways: via `DATABASE_URL` or setting up independent Postgres variables.
+
+### Configure Postgres
+
+Set the `DATABASE_URL` variable with value as Postgres connection URI to connect to the database.
+
+The URI is of the format
+
+```bash
+postgresql://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]
+```
+
+Or you can set the following environment variables to configure Postgres. Replace the values here with yours. Skip this
+if you have configured `DATABASE_URL`.
+
+```bash
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_DATABASE=chatwoot_production
+POSTGRES_USERNAME=admin
+POSTGRES_PASSWORD=password
+```
+
+### Configure Redis
+
+For development, you can use the following URL to connect to Redis. For production, configure your Redis URL.
+
+```bash
+REDIS_URL='redis://127.0.0.1:6379'
+```
+
+To authenticate Redis connections made by the app server and sidekick, if it's protected by a password, use the following environment variable to set the password.
+
+```bash
+REDIS_PASSWORD=
+```
+
+## Configure emails
+
+For development, you don't need an email provider. Chatwoot uses the [letter-opener](https://github.com/ryanb/letter_opener) gem to test emails locally
+
+For production use, please configure the following variables.
+
+```bash
+# could user either `email@yourdomain.com` or `BrandName <email@yourdomain.com>`
+MAILER_SENDER_EMAIL=
+```
+
+and based on your SMTP server the following variables
+
+```bash
+SMTP_ADDRESS=
+SMTP_USERNAME=
+SMTP_PASSWORD=
+SMTP_TLS=
+SMTP_SSL=
+```
+
+### Postfix
+
+Follow these steps if you want to use a selfhosted mail server with Chatwoot. This is the default behavior starting from `v2.12.0` and relies on `SMTP_ADDRESS` environment variable not being set.
+
+```
+sudo apt install -y postfix
+```
+
+Choose internet-site when prompted and enter the domain name you used with Chatwoot setup for `System mail name`.
+
+<Note>
+By default, all major cloud provider have blocked port 25 used for sending emails as part of their spam combat effects. Please raise a support ticket with your cloud provider to enable outbound access on port 25 for this to work. Refer [AWS](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle), [GCP](https://cloud.google.com/compute/docs/tutorials/sending-mail), [Azure](https://learn.microsoft.com/en-us/azure/virtual-network/troubleshoot-outbound-smtp-connectivity) and [DigitalOcean](https://www.digitalocean.com/blog/smtp-restricted-by-default) for more details.
+</Note>
+
+Also please add MX and PTR records for your domain. If your emails are being flagged by `Gmail` and `Outlook`, setup [SPF and DKIM records](https://www.linuxbabe.com/mail-server/setting-up-dkim-and-spf) for your domain as well. This should improve your email reputation.
+
+### Amazon SES
+
+```bash
+SMTP_ADDRESS=email-smtp.<region>.amazonaws.com
+SMTP_AUTHENTICATION=plain
+SMTP_ENABLE_STARTTLS_AUTO=true
+SMTP_USERNAME=<Your SMTP username>
+SMTP_PASSWORD=<Your SMTP password>
+```
+
+### SendGrid
+
+<Info>
+For clarification, the `SMTP_USERNAME` should be set to the literal text apikey—this is not the actual API key. SendGrid uses 'apikey' as the standard username for its services.
+</Info>
+
+```bash
+SMTP_ADDRESS=smtp.sendgrid.net
+SMTP_AUTHENTICATION=plain
+SMTP_DOMAIN=<your verified domain>
+SMTP_ENABLE_STARTTLS_AUTO=true
+SMTP_PORT=587
+SMTP_USERNAME=apikey
+SMTP_PASSWORD=<your Sendgrid API key>
+```
+
+### MailGun
+
+```bash
+SMTP_ADDRESS=smtp.mailgun.org
+SMTP_AUTHENTICATION=plain
+SMTP_DOMAIN=<Your domain, this has to be verified in Mailgun>
+SMTP_ENABLE_STARTTLS_AUTO=true
+SMTP_PORT=587
+SMTP_USERNAME=<Your SMTP username, view under Domains tab>
+SMTP_PASSWORD=<Your SMTP password, view under Domains tab>
+```
+
+### Mandrill
+
+If you would like to use Mailchimp to send your emails, use the following environment variables:
+
+<Note>
+Mandrill is the transactional email service for Mailchimp. You need to enable transactional email and login to mandrillapp.com.
+</Note>
+
+```bash
+SMTP_ADDRESS=smtp.mandrillapp.com
+SMTP_AUTHENTICATION=plain
+SMTP_DOMAIN=<Your verified domain in Mailchimp>
+SMTP_ENABLE_STARTTLS_AUTO=true
+SMTP_PORT=587
+SMTP_USERNAME=<Your SMTP username displayed under Settings -> SMTP & API info>
+SMTP_PASSWORD=<Any valid API key, create an API key under Settings -> SMTP & API Info>
+```
+
+## Configure default language
+
+```bash
+DEFAULT_LOCALE='en'
+```
+
+## Configure storage
+
+Chatwoot uses [active storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) for storing attachments. The default storage option is the local storage on your server.
+
+But you can change it to use any of the cloud providers like amazon s3, microsoft azure, google gcs etc. Refer [configuring cloud storage](/docs/self-hosted/deployment/storage/supported-providers) for additional environment variables required.
+
+```bash
+ACTIVE_STORAGE_SERVICE=local
+```
+
+When `local` storage is used the files are stored under `/storage` directory in the chatwoot root folder.
+
+<Warning>
+It is recommended to use a cloud provider for your chatwoot storage to ensure proper backup of the stored attachments and prevent data loss.
+</Warning>
+
+## Rails Logging Variables
+
+By default, Chatwoot will capture `info` level logs in production. Ref [rails docs](https://guides.rubyonrails.org/debugging_rails_applications.html#log-levels) for the additional log-level options.
+We will also retain 1 GB of your recent logs and your last shifted log file.
+You can fine-tune these settings using the following environment variables
+
+```bash
+# possible values: 'debug', 'info', 'warn', 'error', 'fatal' and 'unknown'
+LOG_LEVEL=
+# value in megabytes
+LOG_SIZE= 1024
+```
+
+## Configure FB Channel
+
+To use FB Channel, you have to create a Facebook app in the developer portal. You can find more details about creating FB channels [here](https://developers.facebook.com/docs/apps/#register)
+
+```bash
+FB_VERIFY_TOKEN=
+FB_APP_SECRET=
+FB_APP_ID=
+```
+
+## Using CDN for asset delivery
+
+With the release v1.8.0, we are enabling CDN support for Chatwoot. If you have a high traffic website, we recommend to setup a CDN for your asset delivery. Read setting up [CloudFront as your CDN](/docs/self-hosted/deployment/performance/cloudfront-cdn) guide.
+
+## Enable new account signup
+
+By default, Chatwoot will not allow users to create an account[multi-tenancy] from the login page. However, if you are setting up a public server, you can enable signup using:
+
+```bash
+ENABLE_ACCOUNT_SIGNUP=true
+```
+
+## Enable direct upload to storage cloud
+
+By default, Chatwoot will upload the files to the application server and then it will push them to the cloud storage. We have introduced the direct upload functionality so that we can upload the file directly to the cloud storage. This has been built according to rails new direct upload functionality documented [here](https://edgeguides.rubyonrails.org/active_storage_overview.html#direct-uploads). Set below environment variable to true to use the direct upload feature.
+
+Make sure to follow [this guide](https://edgeguides.rubyonrails.org/active_storage_overview.html#cross-origin-resource-sharing-cors-configuration) and set the appropriate CORS configuration on your cloud storage after setting `DIRECT_UPLOADS_ENABLED` to true.
+
+```bash
+DIRECT_UPLOADS_ENABLED=true
+```
+
+## Google OAuth
+
+To enable Google OAuth in Chatwoot, you need to provide the client ID, client secret, and callback URL. You can find the instructions to generate the details [here](https://support.google.com/cloud/answer/6158849).
+
+Set the `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` environment variables in your Chatwoot installation using the values you copied from the Google API Console. Set the `GOOGLE_OAUTH_CALLBACK_URL` environment variable to the callback URL you used in the Google API Console. Here's an example of the same
+
+```bash
+GOOGLE_OAUTH_CLIENT_ID=369777777777-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
+GOOGLE_OAUTH_CLIENT_SECRET=ABCDEF-GHijklmnoPqrstuvwX-yz1234567
+GOOGLE_OAUTH_CALLBACK_URL=https://<your-server-domain>/omniauth/google_oauth2/callback
+```
+
+<Warning>
+The callback URL should comply with the format in the example above. This endpoint cannot be changed at the moment.
+</Warning>
+
+After setting these environment variables, restart your Chatwoot server to apply the changes. Now, users will be able to sign in using their Google accounts.
+
+## LogRocket
+
+To enable LogRocket in Chatwoot, you need to provide the project ID from LogRocket. Here are the steps to follow:
+
+1. Open the LogRocket [website](https://logrocket.com/) and create an account or sign in to your existing account. 
+2. After signing in, create a new project in LogRocket by clicking on "Create new project". 
+3. Enter a name for your project, and save the project ID.
+4. Set the `LOG_ROCKET_PROJECT_ID` environment variable in your `.env` file with the project ID you copied from LogRocket. 
+
+```bash
+LOG_ROCKET_PROJECT_ID=abcd12/pineapple-on-pizza
+```
+
+After setting this environment variable, restart your Chatwoot server to apply the changes. Now, LogRocket will start capturing user sessions on your Chatwoot installation. 

chatwoot/developer-docs/self-hosted/runbook/help-center.mdx

@@ -0,0 +1,52 @@
+---
+title: Help Center
+description: Set up a public-facing help center portal with custom domain and SSL certificate
+sidebarTitle: Help Center
+---
+
+Help center allows you to create a portal and add articles from the chatwoot app dashboard. You can point to these help center portal articles from your main site and display them as your public-facing help center.
+
+## How to get SSL certificate for your custom domain
+
+### Create a Portal in Chatwoot's dashboard
+
+Follow these step to create your Portal. Refer to [this guide.](https://www.chatwoot.com/hc/user-guide/articles/1677861202-how-to-setup-a-help-center)
+
+### Point your custom domain to your Chatwoot domain
+
+1. Go to your DNS provider and add a new CNAME record.
+   - For the above example, add docs as a CNAME record and point it to the your selfhosted chatwoot domain(FRONTEND_URL).
+
+2. This will ensure that your CNAME record points to the selfhosted Chatwoot installation. For your custom domain, we have your portal information. In this case, `docs.example.com`
+
+### Setting up SSL
+
+1. Use certbot to generate SSL certificates for your custom domain.
+
+```bash
+certbot certonly --agree-tos --nginx -d "docs.example.com"
+```
+
+2. Create a new nginx config to route requests to this domain to Chatwoot. Make a copy of `/etc/nginx/sites-available/nginx_chatwoot.conf` and make necessary changes for the new domain.
+
+3. Restart nginx server.
+
+```bash
+sudo systemctl restart nginx
+```
+
+Voila!
+
+`docs.yourdomain.com` is live with a secure connection, and your portal data is visible.
+
+### How does this work?
+
+These are the engineering details to understand `How does docs.yourdomain.com` gets the portal data with SSL certificate.
+
+1. `docs.yourdomain.com` resolves by customers nameserver and redirects to your Chatwoot domain.
+2. Chatwoot check for the portal record with custom-domain `docs.yourdomain.com`
+3. Redirects to the portal records for the domain `docs.yourdomain.com`
+
+Yaay!!
+
+Now you can have your own help-center, product-documentation related portal saved at Chatwoot dashboard and served at your domain with SSL certificate. 

developer-docs/api-reference/introduction.mdx

@@ -0,0 +1,49 @@
+---
+title: Introduction to Chatwoot APIs
+description: Learn how to use Chatwoot APIs to build integrations, customize chat experiences, and manage your installation.
+sidebarTitle: Introduction
+---
+
+Welcome to the Chatwoot API documentation. Whether you're building custom workflows for your support team, integrating Chatwoot into your product, or managing users across installations, our APIs provide the flexibility and power to help you do more with Chatwoot.
+
+Chatwoot provides three categories of APIs, each designed with a specific use case in mind:
+
+- **Application APIs** – For account-level automation and agent-facing integrations.
+- **Client APIs** – For building custom chat interfaces for end-users
+- **Platform APIs** – For managing and administering installations at scale
+
+---
+
+## Application APIs
+
+Application APIs are designed for interacting with a Chatwoot account from an agent/admin perspective. Use them to build internal tools, automate workflows, or perform bulk operations like data import/export.
+
+- **Authentication**: Requires a user `access_token`, which can be generated from **Profile Settings** after logging into your Chatwoot account.
+- **Availability**: Supported on both **Cloud** and **Self-hosted** Chatwoot installations.
+- **Example**: [Google Cloud Functions Demo](https://github.com/chatwoot/google-cloud-functions-demo)
+
+---
+
+## Client APIs
+
+Client APIs are intended for building custom messaging experiences over Chatwoot. If you're not using the native website widget or want to embed chat in your mobile app, these APIs are the way to go.
+
+- **Authentication**: Uses `inbox_identifier` (from **Settings → Configuration** in API inboxes) and `contact_identifier` (returned when creating a contact).
+- **Availability**: Supported on both **Cloud** and **Self-hosted** Chatwoot installations.
+- **Examples**:
+
+  - [Client API Demo](https://github.com/chatwoot/client-api-demo)
+  - [Flutter SDK](https://github.com/chatwoot/chatwoot-flutter-sdk)
+
+---
+
+## Platform APIs
+
+Platform APIs are used to manage Chatwoot installations at the admin level. These APIs allow you to control users, roles, and accounts, or sync data from external authentication systems.
+
+- **Authentication**: Requires an `access_token` generated by a **Platform App**, which can be created in the **Super Admin Console**.
+- **Availability**: Available on **Self-hosted** / **Managed Hosting** Chatwoot installations only.
+
+---
+
+Use the right API for your use case, and you'll be able to extend, customize, and integrate Chatwoot into your stack with ease.

developer-docs/contributing/code-of-conduct.mdx

@@ -0,0 +1,89 @@
+---
+title: Contributor Covenant Code of Conduct
+description: Code of conduct for Chatwoot community members and contributors
+sidebarTitle: Code of Conduct
+---
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at **hello@chatwoot.com**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html).
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).
+
+---
+
+By participating in the Chatwoot community, you agree to abide by this Code of Conduct. Thank you for helping us create a welcoming and inclusive environment for everyone. 

developer-docs/contributing/community-guidelines.mdx

@@ -0,0 +1,205 @@
+---
+title: Chatwoot Community Guidelines
+description: Guidelines for participating in the Chatwoot community across all platforms
+sidebarTitle: Community Guidelines
+---
+
+# Chatwoot Community Guidelines
+
+Welcome to the Chatwoot community! These guidelines help ensure our community remains welcoming, productive, and inclusive for everyone.
+
+## General Principles
+
+### 1. Respect and Inclusivity
+Everyone is welcome here. Treat all members with respect, regardless of their background, identity, or level of experience.
+
+### 2. Collaboration Over Conflict
+Always approach discussions and feedback with a constructive attitude. We're all here to learn and grow together.
+
+### 3. No Spam or Self-Promotion
+Unsolicited advertisements, promotions, or spammy links are not allowed. Share valuable content that benefits the community.
+
+## Platform-Specific Guidelines
+
+### Discord-Specific Guidelines
+
+Our Discord server is where the community gathers for real-time discussions, support, and collaboration.
+
+#### Channel Etiquette
+
+1. **Stay On Topic**: Each channel has its purpose. Ensure your discussions are relevant to the channel topic.
+2. **Use Thread Responses**: For lengthy discussions, use thread replies to keep channels organized.
+3. **Search Before Asking**: Check pinned messages and recent discussions before asking questions.
+
+#### Content Guidelines
+
+1. **No NSFW Content**: This is a professional community. Do not share or promote any NSFW content.
+2. **Quality Over Quantity**: Focus on helpful, meaningful contributions rather than frequent low-value messages.
+3. **Appropriate Language**: Keep language professional and appropriate for a business environment.
+
+#### Voice Channels
+
+1. **Microphone Etiquette**: Ensure your microphone is muted when not speaking.
+2. **Respect Speaking Time**: Avoid interrupting others and allow everyone to participate.
+3. **Background Noise**: Use push-to-talk if you're in a noisy environment.
+
+#### Reporting and Support
+
+1. **Report Violations**: If you see someone violating these guidelines, don't engage. Instead, report it to the moderators.
+2. **Use Private Messages**: For sensitive issues, reach out to moderators via private message.
+
+### GitHub-Specific Guidelines
+
+GitHub is our primary platform for code collaboration, issue tracking, and project management.
+
+#### Issue Reporting
+
+1. **Search First**: Before reporting a bug or requesting a feature, search the issues to ensure it hasn't been addressed already.
+2. **Use Templates**: Follow the provided issue templates for bug reports and feature requests.
+3. **Provide Details**: Include clear steps to reproduce, expected behavior, and actual behavior.
+4. **Stay Updated**: Monitor your issues for questions from maintainers and respond promptly.
+
+#### Pull Requests
+
+1. **Clear Descriptions**: Ensure your PRs are concise, have a clear title, and are linked to relevant issues.
+2. **Follow Style Guide**: Adhere to the existing coding style and conventions.
+3. **Test Thoroughly**: Test your changes in multiple scenarios before submitting.
+4. **Respond to Reviews**: Address feedback constructively and make requested changes promptly.
+
+#### Code Review Guidelines
+
+1. **Be Constructive**: Provide specific, actionable feedback rather than general criticism.
+2. **Explain Reasoning**: When suggesting changes, explain why the change would improve the code.
+3. **Appreciate Good Work**: Acknowledge good code and clever solutions.
+4. **Stay Professional**: Keep discussions focused on the code, not the person.
+
+#### Documentation
+
+1. **Update Documentation**: If your PR introduces a new feature, ensure that it's documented.
+2. **Fix What You See**: If you spot outdated or missing documentation, consider updating it or raising an issue.
+3. **Clear Examples**: Provide clear, working examples in documentation.
+
+## Community Support
+
+### Helping Others
+
+#### In Discord
+
+- **Be Patient**: Remember that people have different experience levels
+- **Provide Context**: When helping, explain not just what to do, but why
+- **Share Resources**: Link to relevant documentation or previous discussions
+- **Follow Up**: Check if your help resolved the issue
+
+#### In GitHub
+
+- **Helpful Comments**: Provide constructive feedback on issues and PRs
+- **Share Knowledge**: Contribute to discussions with your expertise
+- **Test Solutions**: Help test proposed fixes when possible
+
+### Getting Help
+
+#### Before Asking
+
+1. **Check Documentation**: Review the official docs first
+2. **Search History**: Look through previous discussions and issues
+3. **Try Solutions**: Attempt basic troubleshooting steps
+
+#### When Asking
+
+1. **Be Specific**: Provide clear details about your issue
+2. **Include Context**: Share relevant environment information
+3. **Show Effort**: Explain what you've already tried
+4. **Be Patient**: Allow time for community members to respond
+
+## Consequences for Violating Guidelines
+
+We enforce these guidelines to maintain a positive community environment.
+
+### Warning System
+
+1. **First Violation**: For most violations, you will receive a warning from the moderators.
+2. **Repeated Minor Violations**: Additional warnings may lead to temporary restrictions.
+
+### Immediate Actions
+
+For serious violations, immediate actions may be taken:
+
+- **Spam or Self-Promotion**: Immediate ban or removal
+- **Harassment or Abuse**: Immediate removal from the community
+- **Sharing Inappropriate Content**: Content removal and potential ban
+
+### Appeal Process
+
+If you believe you've been unfairly moderated:
+
+1. **Contact Moderators**: Reach out via private message
+2. **Provide Context**: Explain your perspective respectfully
+3. **Accept Decisions**: Respect final moderation decisions
+
+Refer to [enforcement guidelines](/contributing/code-of-conduct#enforcement-guidelines) for more details.
+
+## Moderator and Admin Privileges
+
+### Selection Process
+
+Active contributors to the Chatwoot community, those who consistently offer valuable insights, help, and engagement, may be handpicked as moderators or granted specific privileges.
+
+### Criteria for Moderators
+
+- **Consistent Contribution**: Regular, helpful participation in the community
+- **Good Judgment**: Demonstrated ability to handle conflicts constructively
+- **Technical Knowledge**: Understanding of Chatwoot and related technologies
+- **Time Commitment**: Ability to dedicate time to moderation duties
+
+### Responsibilities
+
+Moderators are expected to:
+
+- **Enforce Guidelines**: Apply community guidelines fairly and consistently
+- **Facilitate Discussions**: Help keep conversations productive and on-topic
+- **Support Users**: Provide assistance and guidance to community members
+- **Report Issues**: Escalate serious violations to administrators
+
+### Discretionary Decisions
+
+- **Appointment Process**: The appointment of moderators and the granting of additional privileges are at the sole discretion of the Chatwoot team.
+- **Review Process**: Moderator performance is reviewed regularly to ensure community standards are maintained.
+
+### Admin Privileges
+
+For compliance and security reasons, admin privileges in all Chatwoot communities are reserved exclusively for Chatwoot employees.
+
+## Building a Positive Community
+
+### Encouraging Participation
+
+- **Welcome Newcomers**: Help new members feel included and valued
+- **Celebrate Contributions**: Acknowledge helpful contributions and achievements
+- **Share Knowledge**: Contribute your expertise to help others learn
+- **Provide Feedback**: Offer constructive feedback on ideas and solutions
+
+### Creating Inclusive Environment
+
+- **Use Inclusive Language**: Choose words that welcome all community members
+- **Respect Differences**: Value diverse perspectives and experiences
+- **Avoid Assumptions**: Don't assume others' backgrounds or knowledge levels
+- **Learn Together**: Approach discussions as learning opportunities
+
+## Resources for Community Members
+
+### Getting Started
+
+- **Community Onboarding**: [Discord community](https://discord.com/invite/cJXdrwS)
+- **Contributor Guide**: [Contributing documentation](/contributing/introduction)
+- **Code of Conduct**: [Detailed guidelines](/contributing/code-of-conduct)
+
+### Stay Connected
+
+- **Discord Server**: Real-time community discussions
+- **GitHub Discussions**: Long-form technical discussions
+- **Twitter**: [@chatwootapp](https://twitter.com/chatwootapp) for updates
+- **Blog**: [Chatwoot Blog](https://www.chatwoot.com/blog) for articles and insights
+
+---
+
+Together, we can build an amazing community that supports Chatwoot users and contributors worldwide. Thank you for being part of our journey! 🚀 

developer-docs/contributing/contributors.mdx

@@ -0,0 +1,37 @@
+---
+title: Contributors
+description: Meet the amazing people who contribute to Chatwoot
+sidebarTitle: Contributors
+---
+
+# Contributors
+
+Chatwoot is made possible by the amazing community of developers, designers, translators, and supporters who contribute their time and expertise to make it better every day.
+
+## Our Contributors
+
+You can find the full list of contributors at [https://contributors.chatwoot.com](https://contributors.chatwoot.com)
+
+<a href="https://github.com/chatwoot/chatwoot/graphs/contributors"><img src="https://contributors.chatwoot.com/api/graph.svg?columns=30&size=32" /></a>
+
+## Join Our Contributors
+
+Ready to make your mark on Chatwoot? Here's how to get started:
+
+### Quick Start
+
+1. **Star the Repository**: [Star Chatwoot on GitHub](https://github.com/chatwoot/chatwoot)
+2. **Join Discord**: [Join our Discord community](https://discord.com/invite/cJXdrwS)
+3. **Pick an Issue**: Find a [good first issue](https://github.com/chatwoot/chatwoot/labels/good%20first%20issue)
+4. **Make Your First Contribution**: Follow our [contribution guide](/contributing/introduction)
+
+### Stay Connected
+
+- **GitHub**: [github.com/chatwoot/chatwoot](https://github.com/chatwoot/chatwoot)
+- **Discord**: [discord.com/invite/cJXdrwS](https://discord.com/invite/cJXdrwS)
+- **Twitter**: [@chatwootapp](https://twitter.com/chatwootapp)
+- **LinkedIn**: [Chatwoot Company Page](https://www.linkedin.com/company/chatwoot)
+
+---
+
+Every contribution, no matter how small, makes Chatwoot better for thousands of users worldwide. Thank you for considering joining our contributor community! 🙏 

developer-docs/contributing/cypress.mdx

@@ -0,0 +1,127 @@
+---
+title: End-to-end testing with Cypress
+description: Guide to running Cypress end-to-end tests for Chatwoot
+sidebarTitle: Cypress Testing
+---
+
+# End-to-end testing with Cypress
+
+Chatwoot uses [Cypress](https://www.cypress.io/) for end-to-end testing. Use the following steps to run the tests on your local machine.
+
+## Prepare the Test Server
+
+Choose any of the given methods to run your Chatwoot test server.
+
+<Tabs>
+<Tab title="Local Installation">
+
+### Using Local Chatwoot Installation
+
+<Note>
+You have to install the necessary dependencies as described in [setup guide](/contributing/project-setup/setup-guide) for this method to work.
+</Note>
+
+Navigate to Chatwoot codebase in your local machine and execute the following steps:
+
+#### Create a fresh test database
+
+```bash
+RAILS_ENV=test bin/rake db:drop
+RAILS_ENV=test bin/rake db:create
+RAILS_ENV=test bin/rake db:schema:load
+```
+
+#### Start Chatwoot in the test environment
+
+```bash
+RAILS_ENV=test foreman start -f Procfile.test
+```
+
+Load the URL in the browser and wait for it to start up:
+```
+http://localhost:5050/app/login
+```
+
+</Tab>
+<Tab title="Docker Setup">
+
+### Using Docker
+
+Follow the [docker setup guide](/contributing/project-setup/docker-setup) until you build the images.
+
+#### Change the Rails Environment
+
+Open `docker-compose.yaml` and update all the `RAILS_ENV` values from `development` to `test`:
+
+```yaml
+# In docker-compose.yaml
+environment:
+  - RAILS_ENV=test  # Change from development to test
+```
+
+#### Update the Port
+
+Under rails section in your `docker-compose.yaml` update the port value as given below:
+
+```yaml
+# In docker-compose.yaml
+ports:
+  - 5050:3000  # Change from 3000:3000 to 5050:3000
+```
+
+#### Reset the Database
+
+```bash
+docker-compose run --rm rails bundle exec rails db:reset
+```
+
+#### Start Chatwoot Docker in the test environment
+
+```bash
+docker-compose up
+```
+
+Load the URL in the browser and wait for it to start up:
+```
+http://localhost:5050/app/login
+```
+
+</Tab>
+</Tabs>
+
+## Run Cypress
+
+Load `localhost:5050` on your browser and ensure that the Chatwoot server is running.
+
+Navigate to your Chatwoot local directory and execute the following command to run the Cypress tests:
+
+```bash
+pnpm cypress open --project ./spec
+```
+
+This will open the Cypress Test Runner where you can:
+
+1. **Choose a browser** for running tests
+2. **Select test files** to run individual or all tests
+3. **Watch tests run** in real-time with step-by-step execution
+4. **Debug failed tests** with detailed error information
+
+
+## Getting Help
+
+If you encounter issues with Cypress testing:
+
+- **Cypress Documentation**: [Official Cypress Docs](https://docs.cypress.io/)
+- **Cypress Best Practices**: [Testing Guide](https://docs.cypress.io/guides/references/best-practices)
+- **Common Errors**: See [Common Errors](/contributing/project-setup/common-errors)
+- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
+
+## Useful Resources
+
+- **Cypress API Reference**: [https://docs.cypress.io/api/table-of-contents](https://docs.cypress.io/api/table-of-contents)
+- **Testing Library**: [Testing utilities for better element selection](https://testing-library.com/)
+- **Cypress Examples**: [Real-world examples](https://github.com/cypress-io/cypress-example-recipes)
+
+---
+
+Your Cypress testing environment is now ready for comprehensive end-to-end testing! 🧪 

developer-docs/contributing/introduction.mdx

@@ -4,319 +4,193 @@ description: Complete guide to contributing to Chatwoot - from setting up your d
 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.
+# Contributing Guide
 
-## 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
+Thank you for taking an interest in contributing to Chatwoot! This guide will help you get started with contributing to our open-source customer support platform. Before submitting your contribution, please make sure to take a moment and read through the following guidelines.
 
 ## Getting Started
 
-### Prerequisites
+<Warning>
+Before starting your work, ensure an issue exists for it. If not, feel free to create one. You can also take a look into the issues tagged [Good first issues](https://github.com/chatwoot/chatwoot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+</Warning>
 
-Before you start contributing, make sure you have:
+### Initial Steps
 
-- **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
+1. **Check for Existing Issues**: Browse the [GitHub issues](https://github.com/chatwoot/chatwoot/issues) to see if someone is already working on what you want to contribute.
 
-### Development Workflow
+2. **Comment on the Issue**: Add a comment on the issue and wait for the issue to be assigned before you start working on it.
+   - This helps to avoid multiple people working on similar issues.
 
-Our development workflow follows these steps:
+3. **Propose Complex Solutions**: If the solution is complex, propose the solution on the issue and wait for one of the core contributors to approve before going into the implementation.
+   - This helps in shorter turn around times in merging PRs.
 
-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!
+4. **Justify New Features**: For new feature requests, provide a convincing reason to add this feature. Real-life business use-cases will be super helpful.
 
-## 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
+5. **Join the Community**: Feel free to join our [Discord community](https://discord.com/invite/cJXdrwS) if you need further discussions with the core team.
 
 ## Pull Request Guidelines
 
-### Branch Naming
+<Info>
+We use git-flow branching model. The base branch is `develop`. Please raise your PRs against the `develop` branch.
+</Info>
 
-Use descriptive branch names that follow our conventions:
+### Before Submitting
+
+- Please make sure that you have read the [issue triage guidelines](https://www.chatwoot.com/hc/handbook/articles/issue-triage-29) before you make a contribution.
+- It's okay and encouraged to have multiple small commits as you work on the PR - we will squash the commits before merging.
+- For other guidelines, see [PR Guidelines](https://www.chatwoot.com/hc/handbook/articles/pull-request-guidelines-32)
+- Ensure that all the text copies that you add into the product are i18n translatable. You are only required to add the `English` version of the strings. We pull in other language translations from our contributors on crowdin. See [Translation guidelines](https://www.chatwoot.com/docs/contributing-guide/translation-guidelines) to learn more.
+
+## Development Workflow
+
+### Developing a New Feature
 
 ```bash
-# Feature branches
-feature/issue-id-short-description
+# Create a branch in the following format:
+feature/<issue-id>-<issue-name>
+
+# Example:
 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
+**Requirements:**
+- Add accompanying test cases
+- Follow our coding standards
+- Include proper documentation
 
-Write clear, descriptive commit messages:
+### Bug Fixes or Chores
 
 ```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
+# Branch naming for bug fixes:
+fix/<issue-id>-<issue-name>
 
-# Avoid
-Update stuff
-Fix bug
-WIP
+# Branch naming for chores:
+chore/<description>
 ```
 
-### Pull Request Template
+**Requirements:**
+- If you are resolving a particular issue, add `fix: Fixes xxxx` (#xxxx is the issue) in your PR title
+- Provide a detailed description of the bug in the PR
+- Add appropriate test coverage if applicable
 
-When creating a pull request, include:
+## Environment Setup
 
-**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:
+Choose the guide that matches your operating system:
 
 <CardGroup cols={2}>
-  <Card title="macOS Setup" icon="apple" href="/contributing/environment-setup/macos">
-    Set up development environment on macOS
+  <Card
+    title="macOS Setup"
+    icon="apple"
+    href="/contributing/project-setup/macos-setup"
+  >
+    Complete setup guide for macOS developers
   </Card>
-  <Card title="Ubuntu Setup" icon="ubuntu" href="/contributing/environment-setup/ubuntu">
-    Set up development environment on Ubuntu Linux
+  <Card
+    title="Ubuntu Setup"
+    icon="ubuntu"
+    href="/contributing/project-setup/ubuntu-setup"
+  >
+    Step-by-step Ubuntu installation guide
   </Card>
-  <Card title="Windows Setup" icon="windows" href="/contributing/environment-setup/windows">
-    Set up development environment on Windows
+  <Card
+    title="Windows Setup"
+    icon="windows"
+    href="/contributing/project-setup/windows-setup"
+  >
+    Windows 10/11 development environment setup
   </Card>
-  <Card title="Docker Setup" icon="docker" href="/contributing/environment-setup/docker">
-    Use Docker for consistent development environment
+  <Card
+    title="Docker Setup"
+    icon="docker"
+    href="/contributing/project-setup/docker-setup"
+  >
+    Quick setup using Docker containers
   </Card>
 </CardGroup>
 
-## Issue Labels
+### Speed Up Development
 
-Understanding our issue labels helps you find the right issues to work on:
+Use our [Make commands](/contributing/project-setup/make-setup) to speed up your local development workflow.
 
-| 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 |
+## Project Setup
+
+Once you have set up the environment, follow these guides to get Chatwoot running locally:
+
+1. **[Quick Setup Guide](/contributing/project-setup/setup-guide)** - Step-by-step setup instructions
+2. **[Environment Variables](/contributing/project-setup/environment-variables)** - Configuration options
+3. **[Common Errors](/contributing/project-setup/common-errors)** - Troubleshooting guide
+
+### Special App Integrations
+
+If you're working on specific integrations:
+- **[Telegram App Setup](/contributing/project-setup/telegram-app)** 
+- **[Line App Setup](/contributing/project-setup/line-app)**
+- **[Mobile App Development](/contributing/project-setup/mobile-app)**
+
+## Testing Your Contributions
+
+We use comprehensive testing to ensure code quality:
+
+### Test Types
+- **Unit Tests**: Test individual components and functions
+- **Integration Tests**: Test component interactions
+- **End-to-End Tests**: Test complete user workflows with [Cypress](/contributing/testing)
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/models/user_spec.rb
+
+# Run Cypress tests
+npm run cypress:open
+```
+
+## Documentation and Translation
+
+### Documentation Guidelines
+- Keep documentation clear and concise
+- Include code examples where helpful
+- Update documentation when changing functionality
+- Follow our [translation guidelines](https://www.chatwoot.com/docs/contributing-guide/other/translation-guidelines)
+
+### Internationalization
+- All user-facing text must be translatable
+- Only add English strings - other languages are handled via [Crowdin](https://translate.chatwoot.com/)
+- Use proper i18n keys and formatting
 
 ## Community Guidelines
 
-### Be Respectful
+We strive to maintain a welcoming and inclusive community:
 
-- Treat everyone with respect and kindness
-- Be patient with new contributors
-- Provide constructive feedback
-- Help others learn and grow
+- **[Code of Conduct](https://www.chatwoot.com/docs/contributing-guide/other/code-of-conduct)** - Our community standards
+- **[Community Guidelines](https://www.chatwoot.com/docs/contributing-guide/other/community-guidelines)** - How we interact
+- **[Security Reports](https://www.chatwoot.com/docs/contributing-guide/other/security-reports)** - Reporting security issues
 
-### Communication
+## API Development
 
-- Use clear, concise language
-- Ask questions when unsure
-- Share knowledge and resources
-- Be responsive to feedback
+If you're working on API-related features:
 
-### 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
+- **[Chatwoot APIs](https://www.chatwoot.com/docs/contributing-guide/other/chatwoot-apis)** - API development guide
+- **[API Documentation](https://www.chatwoot.com/docs/contributing-guide/other/api-documentation)** - Documenting APIs
+- **[Platform APIs](https://www.chatwoot.com/docs/contributing-guide/other/chatwoot-platform-apis)** - Platform-level APIs
 
 ## Recognition
 
-We value all contributions and recognize contributors in several ways:
+We value all contributions to Chatwoot. Check out our [Contributors page](https://www.chatwoot.com/docs/contributing-guide/other/contributors) to see the amazing people who have helped make Chatwoot better.
 
-- **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
+## Getting Help
 
-## Code of Conduct
+Need assistance? Here are your options:
 
-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
+- **GitHub Issues**: For bug reports and feature requests
+- **Discord Community**: For real-time discussions with the core team
+- **Documentation**: Comprehensive guides and API references
+- **Community Forums**: Connect with other contributors
 
 ---
 
-<Note>
-Remember, contributing to open source is a learning process. Don't be afraid to ask questions, make mistakes, and learn from the community. Every contribution, no matter how small, makes a difference!
-</Note>
-
-<Tip>
-Start small with documentation improvements or bug fixes to get familiar with the codebase and contribution process before tackling larger features.
-</Tip> 
+Ready to start contributing? Pick an issue that interests you and follow our guidelines above. Every contribution, no matter how small, helps make Chatwoot better for everyone! 🚀 

developer-docs/contributing/project-setup/common-errors.mdx

@@ -991,9 +991,7 @@ What you expected to happen
 What actually happened
 
 ## Error Messages
-```
 Full error message and stack trace
-```
 
 ## Additional Context
 Any other relevant information

developer-docs/contributing/project-setup/docker-setup.mdx

@@ -0,0 +1,283 @@
+---
+title: Docker Development Setup
+description: Complete guide to setting up Chatwoot development environment using Docker and Docker Compose.
+sidebarTitle: Docker Setup
+---
+
+# Docker Development Setup
+
+This guide will help you set up a complete Chatwoot development environment using Docker and Docker Compose.
+
+## Pre-requisites
+
+Before proceeding, make sure you have the latest version of `docker` and `docker-compose` installed.
+
+As of now, we recommend a version equal to or higher than the following:
+
+```bash
+$ docker --version
+Docker version 25.0.4, build 1a576c5
+$ docker compose --version
+docker-compose version 2.24.7
+```
+
+### Install Docker
+
+#### Windows
+
+1. **Download Docker Desktop** from [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/)
+2. **Run the installer** and follow setup instructions
+3. **Enable WSL2 backend** (recommended)
+4. **Restart your computer** when prompted
+
+#### macOS
+
+```bash
+# Option 1: Download from website
+# Go to https://www.docker.com/products/docker-desktop/
+
+# Option 2: Using Homebrew
+brew install --cask docker
+```
+
+#### Linux (Ubuntu/Debian)
+
+```bash
+# Update package index
+sudo apt update
+
+# Install dependencies
+sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
+
+# Add Docker's official GPG key
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
+
+# Add Docker repository
+echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+# Install Docker
+sudo apt update
+sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+
+# Add user to docker group
+sudo usermod -aG docker $USER
+
+# Start Docker service
+sudo systemctl start docker
+sudo systemctl enable docker
+```
+
+<Warning>
+After adding yourself to the docker group on Linux, log out and log back in for the changes to take effect.
+</Warning>
+
+## Development Environment
+
+1. **Clone the repository.**
+
+    ```bash
+    git clone https://github.com/chatwoot/chatwoot.git
+    ```
+
+2. **Make a copy of the example environment file and modify it as required.**
+
+    ```bash
+    # Navigate to Chatwoot
+    cd chatwoot
+    cp .env.example .env
+    # Update redis and postgres passwords
+    nano .env
+    # Update docker-compose.yaml with the same postgres password
+    nano docker-compose.yaml
+    ```
+
+3. **Build the images.**
+
+    ```bash
+    # Build base image first
+    docker compose build base
+
+    # Build the server and worker
+    docker compose build
+    ```
+
+4. **After building the image or destroying the stack, you would have to reset the database using the following command.**
+
+    ```bash
+    docker compose run --rm rails bundle exec rails db:chatwoot_prepare
+    ```
+
+5. **To run the app:**
+
+    ```bash
+    docker compose up
+    ```
+
+    * Access the rails app frontend by visiting `http://0.0.0.0:3000/`
+    * Access Mailhog inbox by visiting `http://0.0.0.0:8025/` (You will receive all emails going out of the application here)
+
+    #### Login with credentials
+    ```
+    url: http://localhost:3000
+    user_name: john@acme.inc
+    password: Password1!
+    ```
+
+6. **To stop the app:**
+
+    ```bash
+    docker compose down
+    ```
+
+## Running RSpec Tests
+
+For running the complete RSpec tests:
+
+```bash
+docker compose run --rm rails bundle exec rspec
+```
+
+For running specific test:
+
+```bash
+docker compose run --rm rails bundle exec rspec spec/<path-to-file>:<line-number>
+```
+
+## Production Environment
+
+To debug the production build locally, set `SECRET_KEY_BASE` environment variable in your `.env` file and then run the below commands:
+
+```bash
+docker compose -f docker-compose.production.yaml build
+docker compose -f docker-compose.production.yaml up
+```
+
+## Debugging Mode
+
+To use debuggers like `byebug` or `binding.pry`, use the following command to bring up the app instead of `docker compose up`:
+
+```bash
+docker compose run --rm --service-port rails
+```
+
+## Development Workflow
+
+### Daily Development Commands
+
+```bash
+# Start development environment
+docker compose up
+
+# View logs
+docker compose logs -f rails
+
+# Access Rails console
+docker compose exec rails bundle exec rails console
+
+# Run migrations
+docker compose exec rails bundle exec rails db:migrate
+
+# Install new gems
+docker compose exec rails bundle install
+
+# Restart a service
+docker compose restart rails
+
+# Stop all services
+docker compose down
+
+# Stop and remove volumes (reset database)
+docker compose down -v
+```
+
+## Troubleshooting
+
+If there is an update to any of the following:
+- `dockerfile`
+- `gemfile`
+- `package.json`
+- schema change
+
+Make sure to rebuild the containers and run `db:reset`.
+
+```bash
+docker compose down
+docker compose build
+docker compose run --rm rails bundle exec rails db:reset
+docker compose up
+```
+
+### Common Issues
+
+<Accordion title="Container fails to start">
+**Solution**: Check service dependencies and logs:
+```bash
+# Check service status
+docker compose ps
+
+# Check logs for specific service
+docker compose logs rails
+
+# Restart problematic service
+docker compose restart rails
+```
+</Accordion>
+
+<Accordion title="Database connection refused">
+**Solution**: Ensure PostgreSQL container is healthy:
+```bash
+# Check postgres health
+docker compose exec postgres pg_isready
+
+# Restart postgres if needed
+docker compose restart postgres
+```
+</Accordion>
+
+<Accordion title="Port already in use">
+**Solution**: Stop other services using the same ports:
+```bash
+# Check what's using port 3000
+lsof -i :3000
+
+# Or change ports in docker-compose.yaml
+```
+</Accordion>
+
+<Accordion title="Out of disk space">
+**Solution**: Clean up Docker resources:
+```bash
+# Remove unused containers, networks, images
+docker system prune -f
+
+# Remove volumes (WARNING: This deletes data)
+docker volume prune -f
+
+# Remove everything (nuclear option)
+docker system prune -a --volumes
+```
+</Accordion>
+
+<Accordion title="Build fails">
+**Solution**: Clear Docker cache and rebuild:
+```bash
+# Clear build cache
+docker builder prune
+
+# Rebuild without cache
+docker compose build --no-cache
+```
+</Accordion>
+
+## Getting Help
+
+If you encounter Docker-specific issues:
+
+- **Docker Documentation**: [https://docs.docker.com/](https://docs.docker.com/)
+- **Docker Compose Reference**: [https://docs.docker.com/compose/](https://docs.docker.com/compose/)
+- **Chatwoot Issues**: [GitHub Issues](https://github.com/chatwoot/chatwoot/issues)
+- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
+
+---
+
+Your Docker development environment is now ready for Chatwoot development! 🐳 

developer-docs/contributing/project-setup/environment-variables.mdx

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

developer-docs/contributing/project-setup/line-channel-setup.mdx

@@ -0,0 +1,198 @@
+---
+title: Line App Integration Setup
+description: Setup Line app integration on your local machine for development
+sidebarTitle: Line Setup
+---
+
+# Setup Line app integration on your local machine
+
+Please follow the steps if you are trying to work with the Line integration on your local machine.
+
+## Prerequisites
+
+- Line Developer Account
+- Access to [Line Developer Console](https://developers.line.biz/console)
+- Ngrok or similar tunneling service
+- Running Chatwoot development environment
+
+## Setup Steps
+
+### 1. Start Ngrok Server
+
+Start a Ngrok server listening at port `3000` or the port you will be running the Chatwoot installation:
+
+```bash
+# Install ngrok if you haven't already
+# Download from https://ngrok.com/download
+
+# Start ngrok tunnel
+ngrok http 3000
+```
+
+### 2. Update Environment Variables
+
+Update the `.env` variable `FRONTEND_URL` in Chatwoot with the `https` version of the Ngrok URL:
+
+```bash
+# In your .env file
+FRONTEND_URL=https://your-ngrok-subdomain.ngrok.io
+```
+
+### 3. Configure Line Developer Console
+
+1. **Access Line Developer Console**: Go to [Line Developer Console](https://developers.line.biz/console)
+2. **Create a Provider** (if you don't have one)
+3. **Create a New Channel** and select "Messaging API"
+4. **Configure Basic Settings**:
+   - Channel name
+   - Channel description
+   - Category
+   - Subcategory
+
+### 4. Get Required Credentials
+
+From the Line Developer Console under the "Messaging API" channel, collect the following values:
+
+1. **Channel Name**
+2. **LINE Channel ID**
+3. **LINE Channel Secret**
+4. **LINE Channel Token**
+
+### 5. Start Chatwoot Server
+
+Start the Chatwoot server and create a new Line channel with the values obtained from Line Developer Console:
+
+```bash
+# Start the development server
+make run
+# or
+foreman start -f Procfile.dev
+```
+
+### 6. Create Line Channel in Chatwoot
+
+1. **Access Chatwoot**: Go to your Chatwoot instance (http://localhost:3000)
+2. **Navigate to Settings** → **Inboxes** → **Add Inbox**
+3. **Select Line** as the channel type
+4. **Enter Line Credentials**:
+   - Channel Name
+   - LINE Channel ID
+   - LINE Channel Secret
+   - LINE Channel Token
+5. **Save Configuration**
+
+## Configure Webhook in Line Developer Console
+
+After creating the channel, Chatwoot will provide a webhook URL for the channel. You need to configure this webhook URL in the Line Developer Console:
+
+### Steps to Configure Webhook
+
+1. **Go to Line Developer Console** → Your Channel → **Messaging API**
+2. **Find Webhook Settings**
+3. **Set Webhook URL**: Use the URL provided by Chatwoot
+   ```
+   https://your-ngrok-subdomain.ngrok.io/webhooks/line/your-channel-id
+   ```
+4. **Enable Webhook**: Toggle the webhook to "Enabled"
+5. **Verify Webhook**: Use the "Verify" button to test the connection
+
+### Additional Line Settings
+
+Configure these settings in the Line Developer Console:
+
+- **Auto-reply messages**: Disable (so Chatwoot can handle responses)
+- **Greeting messages**: Optional
+- **Webhook redelivery**: Enable for reliability
+
+## Testing the Integration
+
+If the webhook is registered correctly with Line, your Ngrok server should receive events for new Line messages, and new conversations will be created in Chatwoot.
+
+### Test Steps
+
+1. **Add your Line bot as a friend** using the QR code or bot ID
+2. **Send a message** to your Line bot
+3. **Check Ngrok logs** to see if the webhook request is received
+4. **Check Chatwoot** to see if a new conversation is created
+5. **Reply from Chatwoot** to test bidirectional communication
+
+## Troubleshooting
+
+<Accordion title="Webhook verification fails">
+**Problem**: Line webhook verification fails in Developer Console
+
+**Solution**:
+- Ensure your Ngrok URL is accessible publicly
+- Check that `FRONTEND_URL` is set correctly in your `.env` file
+- Verify the webhook URL format is correct
+- Restart Chatwoot after updating environment variables
+</Accordion>
+
+<Accordion title="Messages not appearing in Chatwoot">
+**Problem**: Line messages don't create conversations in Chatwoot
+
+**Solution**:
+- Check Ngrok logs for incoming webhook requests
+- Verify webhook is enabled in Line Developer Console
+- Check Chatwoot logs for any error messages
+- Ensure all Line credentials are entered correctly
+- Verify the channel is enabled in Chatwoot
+</Accordion>
+
+<Accordion title="SSL/TLS errors">
+**Problem**: SSL certificate issues with webhook
+
+**Solution**:
+- Use the `https` version of your Ngrok URL
+- Ensure Ngrok is running properly
+- Line requires HTTPS for webhook URLs
+- Try restarting Ngrok and updating the webhook
+</Accordion>
+
+<Accordion title="Authentication errors">
+**Problem**: Line API authentication failures
+
+**Solution**:
+- Verify Channel ID, Channel Secret, and Channel Token are correct
+- Check that the channel is published and not in development mode
+- Ensure the Messaging API is enabled for your channel
+- Regenerate Channel Token if necessary
+</Accordion>
+
+## Line API Features
+
+Line offers various features you can integrate:
+
+- **Rich Messages**: Cards, carousels, quick replies
+- **Flex Messages**: Custom layouts
+- **LIFF (Line Frontend Framework)**: Web apps within Line
+- **Line Login**: User authentication
+
+## Next Steps
+
+After successful setup:
+
+1. **Test message flow** between Line and Chatwoot
+2. **Configure agent assignments** for Line conversations
+3. **Set up automated responses** if needed
+4. **Explore rich message features** for enhanced user experience
+5. **Review webhook logs** for debugging
+
+## Getting Help
+
+If you encounter issues:
+
+- **Check Logs**: Review both Chatwoot and Ngrok logs
+- **Line Developers Documentation**: [Official Line API Docs](https://developers.line.biz/en/docs/)
+- **Common Errors**: See [Common Errors](/contributing/project-setup/common-errors)
+- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
+
+## Useful Resources
+
+- **Line Messaging API Documentation**: [https://developers.line.biz/en/docs/messaging-api/](https://developers.line.biz/en/docs/messaging-api/)
+- **Line Developer Console**: [https://developers.line.biz/console](https://developers.line.biz/console)
+- **Webhook Test Tool**: Available in Line Developer Console
+
+---
+
+Your Line integration is now ready for development and testing! 💬 

developer-docs/contributing/project-setup/macos-setup.mdx

@@ -0,0 +1,314 @@
+---
+title: macOS Development Setup
+description: Complete guide to setting up your macOS development environment for Chatwoot contribution.
+sidebarTitle: macOS Setup
+---
+
+# macOS Development Setup
+
+This guide will help you set up your macOS development environment for contributing to Chatwoot. Open Terminal app and run the following commands.
+
+## Installing the Standalone Command Line Tools
+
+Open Terminal app and run:
+
+```bash
+xcode-select --install
+```
+
+This installs essential development tools including Git, GCC, and other command line utilities.
+
+## Install Homebrew
+
+Homebrew is the missing package manager for macOS:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+```
+
+After installation, add Homebrew to your PATH (if not automatically added):
+
+```bash
+echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
+eval "$(/opt/homebrew/bin/brew shellenv)"
+```
+
+## Install Git
+
+```bash
+brew update
+brew install git
+```
+
+Configure Git with your information:
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+```
+
+## Install Ruby Version Manager
+
+Choose between RVM or rbenv for managing Ruby versions.
+
+### Option 1: Install RVM (Recommended)
+
+```bash
+curl -L https://get.rvm.io | bash -s stable
+source ~/.rvm/scripts/rvm
+```
+
+### Option 2: Install rbenv (Alternative)
+
+```bash
+brew install rbenv ruby-build
+echo 'eval "$(rbenv init -)"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+## Install Ruby
+
+Chatwoot APIs are built on Ruby on Rails. You need to install Ruby 3.2.2.
+
+### If using RVM:
+
+```bash
+rvm install ruby-3.2.2
+rvm use 3.2.2 --default
+source ~/.rvm/scripts/rvm
+```
+
+### If using rbenv:
+
+```bash
+rbenv install 3.2.2
+rbenv global 3.2.2
+```
+
+<Info>
+rbenv identifies the ruby version from `.ruby-version` file on the root of the project and loads it automatically.
+</Info>
+
+Verify Ruby installation:
+
+```bash
+ruby --version
+# Should output: ruby 3.2.2
+```
+
+## Install Node.js
+
+Chatwoot requires Node.js version 20:
+
+```bash
+brew install node@20
+```
+
+If you need to link Node.js 20:
+
+```bash
+brew link node@20
+echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Verify Node.js installation:
+
+```bash
+node --version
+# Should output: v20.x.x
+```
+
+## Install pnpm
+
+We use `pnpm` as our package manager for better performance:
+
+```bash
+brew install pnpm
+```
+
+Verify pnpm installation:
+
+```bash
+pnpm --version
+```
+
+## Install PostgreSQL
+
+The database used in Chatwoot is PostgreSQL.
+
+### Option 1: PostgresApp (Recommended)
+
+1. Download and install PostgresApp from [https://postgresapp.com](https://postgresapp.com)
+2. This is the easiest way to get started with PostgreSQL on macOS
+3. Follow the setup instructions on their website
+
+### Option 2: Homebrew Installation
+
+```bash
+brew install postgresql@14
+```
+
+Start PostgreSQL service:
+
+```bash
+brew services start postgresql@14
+```
+
+Create a PostgreSQL user:
+
+```bash
+createuser -s postgres
+```
+
+Connect to PostgreSQL to verify installation:
+
+```bash
+psql postgres
+# Type \q to exit
+```
+
+## Install Redis Server
+
+Chatwoot uses Redis server for agent assignments and reporting:
+
+```bash
+brew install redis
+```
+
+Start the Redis service:
+
+```bash
+brew services start redis
+```
+
+Verify Redis installation:
+
+```bash
+redis-cli ping
+# Should output: PONG
+```
+
+## Install ImageMagick
+
+Chatwoot uses ImageMagick library to resize images for previews and thumbnails:
+
+```bash
+brew install imagemagick
+```
+
+Verify ImageMagick installation:
+
+```bash
+convert --version
+```
+
+## Install Additional Dependencies
+
+Install other useful development tools:
+
+```bash
+# Install Yarn (alternative to pnpm if needed)
+brew install yarn
+
+# Install SQLite (for testing)
+brew install sqlite
+
+# Install libvips (for image processing)
+brew install libvips
+```
+
+## Install Docker (Optional)
+
+For development and testing with containers:
+
+```bash
+# Install Docker Desktop
+brew install --cask docker
+```
+
+Or download Docker Desktop from [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/).
+
+## Environment Verification
+
+Verify all installations are working:
+
+```bash
+# Check versions
+ruby --version        # Should be 3.2.2
+node --version         # Should be v20.x.x
+pnpm --version        # Should show pnpm version
+psql --version        # Should show PostgreSQL version
+redis-cli --version   # Should show Redis version
+convert --version     # Should show ImageMagick version
+git --version         # Should show Git version
+```
+
+## Configure Shell Environment
+
+Add useful aliases to your shell configuration file (`~/.zshrc` for Zsh):
+
+```bash
+# Add to ~/.zshrc
+echo '# Chatwoot Development Aliases' >> ~/.zshrc
+echo 'alias cw-server="bundle exec rails server"' >> ~/.zshrc
+echo 'alias cw-console="bundle exec rails console"' >> ~/.zshrc
+echo 'alias cw-test="bundle exec rspec"' >> ~/.zshrc
+echo 'alias cw-migrate="bundle exec rails db:migrate"' >> ~/.zshrc
+
+# Reload shell configuration
+source ~/.zshrc
+```
+## Troubleshooting Common Issues
+
+<Accordion title="Command line tools installation fails">
+**Solution**: Update macOS to the latest version and try again. You can also download Xcode from the App Store.
+</Accordion>
+
+<Accordion title="Homebrew installation permission errors">
+**Solution**: 
+```bash
+sudo chown -R $(whoami) /opt/homebrew
+```
+</Accordion>
+
+<Accordion title="Ruby installation fails with RVM">
+**Solution**: 
+```bash
+# Install missing dependencies
+brew install openssl readline libyaml
+rvm reinstall 3.2.2 --with-openssl-dir=$(brew --prefix openssl)
+```
+</Accordion>
+
+<Accordion title="PostgreSQL connection refused">
+**Solution**: 
+```bash
+# Restart PostgreSQL
+brew services restart postgresql@14
+
+# Check if it's running
+brew services list | grep postgresql
+```
+</Accordion>
+
+<Accordion title="ImageMagick installation issues">
+**Solution**: 
+```bash
+# If you encounter issues, try:
+brew uninstall imagemagick
+brew install imagemagick
+```
+</Accordion>
+
+## Getting Help
+
+If you encounter issues:
+
+- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
+- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
+- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)
+
+---
+
+Your macOS development environment is now ready for Chatwoot development! 🚀 

developer-docs/contributing/project-setup/make-setup.mdx

@@ -0,0 +1,115 @@
+---
+title: Make Commands Setup
+description: Speed up your local development workflow with Make commands for Chatwoot.
+sidebarTitle: Make Setup
+---
+
+# Speed up your local development with Make
+
+Speed up your local development workflow with make commands for Chatwoot.
+
+## Clone the repo and cd to the Chatwoot directory
+
+Clone the repository and navigate to the Chatwoot directory:
+
+```bash
+git clone https://github.com/chatwoot/chatwoot.git
+cd chatwoot
+```
+
+## Install Ruby & JavaScript dependencies
+
+Install Ruby and JavaScript dependencies using the following command. This command runs Bundler and pnpm:
+
+```bash
+make burn
+```
+
+## Run database migrations
+
+Apply necessary database schema changes to your development environment by running the following command:
+
+```bash
+make db
+```
+
+## Run database seed
+
+Load some seed data to your development environment for testing by running the following command:
+
+```bash
+make db_seed
+```
+
+## Run dev server using Overmind
+
+Start the development server using Overmind, a process manager that can run multiple processes concurrently:
+
+```bash
+make run
+```
+
+## Force run if ./.overmind.sock file exists
+
+If the `make run` command fails due to the existence of a `./.overmind.sock` file, you can try using the following command:
+
+```bash
+make force_run
+```
+
+## Debug - Attach to backend via Overmind tmux session
+
+For debugging purposes, you can attach to the backend via the Overmind tmux session using the following command:
+
+```bash
+make debug
+```
+
+## Debug worker
+
+To debug the worker, use the following command:
+
+```bash
+make debug_worker
+```
+
+## Get Rails console
+
+Access the Rails console, which provides an interactive environment for interacting with the Chatwoot application:
+
+```bash
+make console
+```
+
+## Build Docker image
+
+Build the Docker image for the Chatwoot project:
+
+```bash
+make docker
+```
+
+## Workflow after pulling in the latest changes from `develop`
+
+To update your development environment after pulling the latest changes from the `develop` branch, follow these steps:
+
+```bash
+make burn     # Install dependencies
+
+make db       # Run migrations
+
+make run      # Start the server
+```
+
+## Getting Help
+
+If you encounter issues with Make commands:
+
+- **Makefile Documentation**: Check the project's `Makefile` for available commands
+- **Overmind Documentation**: [https://github.com/DarthSim/overmind](https://github.com/DarthSim/overmind)
+- **Chatwoot Issues**: [GitHub Issues](https://github.com/chatwoot/chatwoot/issues)
+- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
+
+---
+
+Your Make-based development workflow is now ready for efficient Chatwoot development! 🚀 

developer-docs/contributing/project-setup/mobile-app-setup.mdx

@@ -0,0 +1,242 @@
+---
+title: Mobile App Development Setup
+description: Setup guide for Chatwoot mobile app development
+sidebarTitle: Mobile App Setup
+---
+
+# Setup guide for mobile app
+
+Complete guide to setting up the Chatwoot mobile app for development and contribution.
+
+## Installation and setup
+
+### Prerequisites
+
+Before starting, ensure you have the following installed:
+
+- [Node.js](https://nodejs.org/en/download/) (Latest LTS version)
+- [React Native CLI](https://reactnative.dev/docs/environment-setup)
+- [Expo CLI](https://docs.expo.dev/get-started/installation/)
+- [Expo Account](https://expo.dev/signup)
+
+<Note>
+To learn more about the most up-to-date instructions, please refer to the guide available [here](https://docs.expo.dev/get-started/set-up-your-environment/).
+</Note>
+
+### Clone the repository
+
+```bash
+git clone git@github.com:chatwoot/chatwoot-mobile-app.git
+cd chatwoot-mobile-app
+```
+
+### Install dependencies
+
+```bash
+pnpm install
+```
+
+### Install Expo CLI
+
+```bash
+pnpm install -g expo-cli
+```
+
+## Environment Variables
+
+Create your environment configuration file:
+
+```bash
+cp .env.example .env
+```
+
+Configure the following environment variables:
+
+| Name                                     | Description                                 | Default Value            | Required |
+| ---------------------------------------- | ------------------------------------------- | ------------------------ | -------- |
+| EXPO_PUBLIC_CHATWOOT_WEBSITE_TOKEN       | Web widget token for in-app support         | -                        | No       |
+| EXPO_PUBLIC_CHATWOOT_BASE_URL            | Self-hosted installation URL                | https://app.chatwoot.com | Yes      |
+| EXPO_PUBLIC_JUNE_SDK_KEY                 | June analytics SDK key                      | -                        | No       |
+| EXPO_PUBLIC_MINIMUM_CHATWOOT_VERSION     | Minimum supported Chatwoot version          | -                        | Yes      |
+| EXPO_PUBLIC_SENTRY_DSN                   | Sentry DSN URL for error reporting          | -                        | No       |
+| EXPO_PUBLIC_PROJECT_ID                   | Expo project identifier                     | -                        | Yes      |
+| EXPO_PUBLIC_APP_SLUG                     | Application slug for Expo                   | -                        | Yes      |
+| EXPO_PUBLIC_SENTRY_PROJECT_NAME          | Project name in Sentry                      | -                        | No       |
+| EXPO_PUBLIC_SENTRY_ORG_NAME              | Organization name in Sentry                 | -                        | No       |
+| EXPO_PUBLIC_IOS_GOOGLE_SERVICES_FILE     | Path to iOS Google Services config file     | -                        | No       |
+| EXPO_PUBLIC_ANDROID_GOOGLE_SERVICES_FILE | Path to Android Google Services config file | -                        | No       |
+| EXPO_APPLE_ID                            | Apple Developer account ID                  | -                        | No       |
+| EXPO_APPLE_TEAM_ID                       | Apple Developer team ID                     | -                        | No       |
+| EXPO_STORYBOOK_ENABLED                   | Enable/disable Storybook                    | false                    | No       |
+
+## Generate the native code
+
+```bash
+pnpm generate
+```
+
+This command generates native Android and iOS directories using [Prebuild](https://docs.expo.dev/workflow/continuous-native-generation/).
+
+<Warning>
+You need to run pre-build if you add a new native dependency to your project or change the project configuration in Expo app config (app.config.ts).
+</Warning>
+
+## How to run the app
+
+Connect your iPhone/Android device and run the following command to install the app on your device.
+
+### iOS Development
+
+```bash
+pnpm run:ios
+```
+
+### Android Development
+
+```bash
+pnpm run:android
+```
+
+## Package Installation
+
+<Warning>
+Please always install packages using the command `npx expo install package-name` instead of `pnpm install package-name`.
+</Warning>
+
+This is crucial for native dependencies because Expo will automatically install the correct compatible version, while pnpm/yarn/npm may install the latest version, which may not be compatible.
+
+```bash
+# Correct way to install packages
+npx expo install package-name
+
+# Incorrect way (may cause compatibility issues)
+pnpm install package-name
+```
+
+## Push notification
+
+If you are using the community edition of Chatwoot, you can now use the [official mobile app](https://www.chatwoot.com/mobile-apps) with push notifications without any additional configuration. 
+
+For more details, please refer to the [push notification documentation](https://www.chatwoot.com/hc/handbook/articles/1687935909-push-notification).
+
+## Build & Submit using EAS
+
+We use Expo Application Services (EAS) for building, deploying, and submitting the app to app stores. EAS Build and Submit is available to anyone with an Expo account, regardless of whether you pay for EAS or use our Free plan. 
+
+You can sign up at [Expo EAS](https://expo.dev/eas).
+
+### Build the app
+
+#### iOS Build
+
+```bash
+pnpm run build:ios:local
+```
+
+#### Android Build
+
+```bash
+pnpm run build:android:local
+```
+
+### Submit the app
+
+#### iOS Submission
+
+```bash
+pnpm submit:ios
+```
+
+#### Android Submission
+
+```bash
+pnpm submit:android
+```
+
+When you run the above command, you will be prompted to provide a path to a local app binary file. Please select the file that you built in the previous step:
+
+- **iOS**: `.ipa` file
+- **Android**: `.aab` file
+
+<Note>
+It may take a while to complete the submission process. You will see the status of the submission on your terminal.
+</Note>
+
+## Troubleshooting
+
+<Accordion title="Metro bundler issues">
+**Problem**: Metro bundler fails to start or bundle
+
+**Solution**:
+```bash
+# Clear cache and restart
+pnpm clear
+pnpm start --reset-cache
+```
+</Accordion>
+
+<Accordion title="iOS build fails">
+**Problem**: iOS build or simulator issues
+
+**Solution**:
+- Ensure Xcode is properly installed
+- Check iOS simulator version compatibility
+- Clear derived data in Xcode
+- Restart Metro bundler
+</Accordion>
+
+<Accordion title="Android build fails">
+**Problem**: Android build or emulator issues
+
+**Solution**:
+- Verify Android Studio setup
+- Check SDK versions and build tools
+- Ensure emulator is running
+- Clear Gradle cache
+</Accordion>
+
+<Accordion title="Expo CLI issues">
+**Problem**: Expo commands fail
+
+**Solution**:
+```bash
+# Update Expo CLI
+npm install -g @expo/cli@latest
+
+# Login to Expo
+expo login
+
+# Clear Expo cache
+expo r -c
+```
+</Accordion>
+
+## Contributing Guidelines
+
+When contributing to the mobile app:
+
+1. **Follow coding standards**: Use ESLint and Prettier configurations
+2. **Write tests**: Include unit tests for new features
+3. **Test on both platforms**: Ensure iOS and Android compatibility
+4. **Update documentation**: Document new features and changes
+5. **Check performance**: Monitor app performance impact
+
+## Getting Help
+
+If you encounter issues:
+
+- **Expo Documentation**: [Official Expo Docs](https://docs.expo.dev/)
+- **React Native Documentation**: [React Native Docs](https://reactnative.dev/docs/getting-started)
+- **GitHub Issues**: [Mobile App Issues](https://github.com/chatwoot/chatwoot-mobile-app/issues)
+- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
+
+## Useful Resources
+
+- **Expo Development**: [https://docs.expo.dev/](https://docs.expo.dev/)
+- **React Native**: [https://reactnative.dev/](https://reactnative.dev/)
+- **EAS Build**: [https://docs.expo.dev/build/introduction/](https://docs.expo.dev/build/introduction/)
+- **EAS Submit**: [https://docs.expo.dev/submit/introduction/](https://docs.expo.dev/submit/introduction/)
+
+---
+
+Your Chatwoot mobile app development environment is now ready! 📱 

developer-docs/contributing/project-setup/setup-guide.mdx

@@ -1,589 +1,181 @@
 ---
 title: Project Setup Guide
-description: Complete guide to setting up Chatwoot for development and contribution
+description: Complete guide to setting up and running Chatwoot in development mode
 sidebarTitle: Setup Guide
 ---
 
-# Project Setup Guide
+# Project Setup
 
-This comprehensive guide will walk you through setting up Chatwoot for development, from initial repository setup to running your first successful build.
+This guide will help you to setup and run Chatwoot in development mode. Please make sure you have completed the environment setup.
 
-## 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
+## Clone the repo
 
 ```bash
-# Check Ruby version (should be 3.3.3)
-ruby --version
+# change location to the path you want chatwoot to be installed
+cd ~
 
-# 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
+# clone the repo and cd to chatwoot dir
+git clone https://github.com/chatwoot/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
+## Install Ruby & Javascript dependencies
+
+Use the following command to run `bundle && pnpm install` to install ruby and Javascript dependencies.
 
 ```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
+make burn
 ```
 
-## Environment Configuration
+This would install all required dependencies for Chatwoot application.
 
-### 1. Environment File Setup
+<Warning>
+If you face issue with pg gem, please refer to [Common Errors](/contributing/project-setup/common-errors#pg-gem-installation-error)
+</Warning>
+
+## Setup environment variables
 
 ```bash
-# Copy the example environment file
 cp .env.example .env
-
-# Open the file for editing
-nano .env
 ```
 
-### 2. Basic Configuration
+Please refer to [environment-variables](/contributing/project-setup/environment-variables) to read on setting environment variables.
 
-Update your `.env` file with the following essential settings:
+## Setup rails server
 
 ```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
+# run db migrations
+make db
+# fireup the server
 foreman start -f Procfile.dev
-
-# This starts:
-# - Rails server (port 3000)
-# - Webpack dev server
-# - Sidekiq worker
 ```
 
-### 2. Manual Startup
+<Note>
+If you have overmind installed, use `make run` to run the server.
+</Note>
 
-If you prefer to run services separately:
+## Login with credentials
 
 ```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
+http://localhost:3000
+user name: john@acme.inc
+password: Password1!
 ```
 
-### 3. Verify Installation
+## Testing chat widget in your local environment
 
-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:
+When running Chatwoot in development environment, the chat widget can be accessed under the following URL.
 
 ```
-Email: john@acme.inc
-Password: Password1!
+http://localhost:3000/widget_tests
 ```
 
-### Creating Additional Users
+You can also test the `setUser` method by using
+
+```
+http://localhost:3000/widget_tests?setUser=true
+```
+
+## Docker for development
+
+<Note>
+Follow this section only if you are trying to setup Chatwoot via docker. Else skip this.
+</Note>
+
+The first time you start your development environment run the following two commands:
 
 ```bash
-# Access Rails console
-bundle exec rails console
+# build base image first
+docker compose build base
 
-# Create a new user
-user = User.create!(
-  name: "Your Name",
-  email: "your.email@example.com",
-  password: "Password123!",
-  password_confirmation: "Password123!"
-)
+# build the server and worker
+docker compose build
 
-# Make user an administrator
-user.account_users.first.update!(role: 'administrator')
+# prepare the database
+docker compose exec rails bundle exec rails db:chatwoot_prepare
+
+# docker compose up
 ```
 
-## Development Workflow
-
-### 1. Code Quality Setup
+Then browse http://localhost:3000
 
 ```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
+# To stop your environment use Control+C (on Mac) CTRL+C (on Win) or
+docker compose down
+# start the services
+docker compose up
 ```
 
-### 2. Running Tests
+When you change the service's Dockerfile or the contents of the build directory, run stop then build. (For example after modifying package.json or Gemfile)
 
 ```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
+docker compose stop
+docker compose build
 ```
 
-### 3. Code Linting and Formatting
+The docker-compose environment consists of:
+- chatwoot server
+- postgres
+- redis
+- webpacker-dev-server
+
+If in case you encounter a seeding issue or you want reset the database you can do it using the following command:
 
 ```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
+docker compose run --rm rails bundle exec rake db:reset
 ```
 
-## IDE Configuration
+This command essentially runs postgres and redis containers and then run the rake command inside the chatwoot server container.
 
-### VS Code Setup
+## Running Cypress Tests
 
-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
+Refer the docs to learn how to write cypress specs:
+- https://github.com/shakacode/cypress-on-rails
+- https://docs.cypress.io/guides/overview/why-cypress.html
 
 ```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)"
+# in terminal tab1
+overmind start -f Procfile.test
+# in terminal tab2
+pnpm cypress open --project ./test
 ```
 
-## Performance Optimization
+## Debugging Docker for production
 
-### Development Performance
+You can use our official Docker image from [https://hub.docker.com/r/chatwoot/chatwoot](https://hub.docker.com/r/chatwoot/chatwoot)
 
 ```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
+docker pull chatwoot/chatwoot
 ```
 
-### Database Performance
-
-```ruby
-# Add to config/environments/development.rb for query analysis
-config.active_record.verbose_query_logs = true
-
-# Enable query plan logging
-config.active_record.dump_schema_after_migration = false
-```
-
-## Troubleshooting Setup Issues
-
-### Common Setup Problems
-
-<Accordion title="Bundle install fails">
-**Error**: `An error occurred while installing pg`
-
-**Solution**:
-```bash
-# macOS
-brew install postgresql
-bundle config build.pg --with-pg-config=/usr/local/bin/pg_config
-
-# Ubuntu/Debian
-sudo apt-get install libpq-dev
-bundle install
-```
-</Accordion>
-
-<Accordion title="Database connection refused">
-**Error**: `could not connect to server: Connection refused`
-
-**Solution**:
-```bash
-# Check if PostgreSQL is running
-sudo systemctl status postgresql
-
-# Start PostgreSQL
-sudo systemctl start postgresql
-
-# macOS with Homebrew
-brew services start postgresql
-```
-</Accordion>
-
-<Accordion title="Redis connection refused">
-**Error**: `Redis::CannotConnectError`
-
-**Solution**:
-```bash
-# Check if Redis is running
-redis-cli ping
-
-# Start Redis
-sudo systemctl start redis
-
-# macOS with Homebrew
-brew services start redis
-```
-</Accordion>
-
-<Accordion title="Webpack compilation fails">
-**Error**: `Module not found` or compilation errors
-
-**Solution**:
-```bash
-# Clear webpack cache
-rm -rf tmp/cache/webpacker
-
-# Reinstall node modules
-rm -rf node_modules
-pnpm install
-
-# Restart webpack dev server
-pnpm run dev
-```
-</Accordion>
-
-### Verification Commands
+You can create an image yourselves by running the following command on the root directory.
 
 ```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
+docker compose -f docker-compose.production.yaml build
 ```
 
+This will build the image which you can deploy in Kubernetes (GCP, Openshift, AWS, Azure or anywhere), Amazon ECS or Docker Swarm. You can tag this image and push this image to docker registry of your choice.
+
+Remember to make the required environment variables available during the deployment.
+
 ## Next Steps
 
-After successful setup:
+After completing this 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
-```
+1. **Verify Installation**: Access http://localhost:3000 and log in with the provided credentials
+2. **Explore the Code**: Start making changes and see them reflected in your development environment
+3. **Run Tests**: Execute the test suite to ensure everything works correctly
+4. **Check Troubleshooting**: If you encounter issues, refer to [Common Errors](/contributing/project-setup/common-errors)
 
 ## 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
+- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
+- **Environment Variables**: See [Environment Variables](/contributing/project-setup/environment-variables)
+- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
+- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)
 
 ---
 
-You're now ready to start developing with Chatwoot! Your development environment should be fully functional and ready for contribution. 
+Your Chatwoot development environment is now ready for contribution! 🚀 

developer-docs/contributing/project-setup/telegram-channel-setup.mdx

@@ -0,0 +1,129 @@
+---
+title: Telegram App Integration Setup
+description: Setup Telegram app integration on your local machine for development
+sidebarTitle: Telegram Setup
+---
+
+# Setup Telegram app integration on your local machine
+
+Please follow the steps if you are trying to work with the Telegram integration on your local machine.
+
+## Prerequisites
+
+- Telegram Bot Token from [BotFather](https://t.me/botfather)
+- Ngrok or similar tunneling service
+- Running Chatwoot development environment
+
+## Setup Steps
+
+### 1. Start Ngrok Server
+
+Start a Ngrok server listening at port `3000` or the port you will be running the Chatwoot installation:
+
+```bash
+# Install ngrok if you haven't already
+# Download from https://ngrok.com/download
+
+# Start ngrok tunnel
+ngrok http 3000
+```
+
+### 2. Update Environment Variables
+
+Update the `.env` variable `FRONTEND_URL` in Chatwoot with the `https` version of the Ngrok URL:
+
+```bash
+# In your .env file
+FRONTEND_URL=https://your-ngrok-subdomain.ngrok.io
+```
+
+### 3. Start Chatwoot Server
+
+Start the Chatwoot server and create a new Telegram channel with the token obtained from Telegram BotFather.
+
+```bash
+# Start the development server
+make run
+# or
+foreman start -f Procfile.dev
+```
+
+### 4. Create Telegram Channel
+
+1. **Access Chatwoot**: Go to your Chatwoot instance (http://localhost:3000)
+2. **Navigate to Settings** → **Inboxes** → **Add Inbox**
+3. **Select Telegram** as the channel type
+4. **Enter Bot Token**: Paste the token you received from BotFather
+5. **Configure Channel**: Set up the channel name and other settings
+
+## Verify Webhook Registration
+
+While creating the channel, Chatwoot should have registered a webhook callback URL in Telegram for your Bot. You can verify whether this URL registration was done successfully by calling the Telegram API:
+
+```bash
+GET https://api.telegram.org/bot{your_bot_token}/getWebhookInfo
+```
+
+## Testing the Integration
+
+If the webhook is registered correctly with Telegram, your Ngrok server should receive events for new Telegram messages, and new conversations will be created in Chatwoot.
+
+### Test Steps
+
+1. **Send a message** to your Telegram bot
+2. **Check Ngrok logs** to see if the webhook request is received
+3. **Check Chatwoot** to see if a new conversation is created
+4. **Reply from Chatwoot** to test bidirectional communication
+
+## Troubleshooting
+
+<Accordion title="Webhook not registered">
+**Problem**: Telegram webhook registration fails
+
+**Solution**:
+- Ensure your Ngrok URL is accessible publicly
+- Check that `FRONTEND_URL` is set correctly in your `.env` file
+- Verify the bot token is correct
+- Restart Chatwoot after updating environment variables
+</Accordion>
+
+<Accordion title="Messages not appearing in Chatwoot">
+**Problem**: Telegram messages don't create conversations in Chatwoot
+
+**Solution**:
+- Check Ngrok logs for incoming webhook requests
+- Verify the webhook URL in Telegram using the API call above
+- Check Chatwoot logs for any error messages
+- Ensure the channel is properly configured and enabled
+</Accordion>
+
+<Accordion title="SSL/TLS errors">
+**Problem**: SSL certificate issues with webhook
+
+**Solution**:
+- Use the `https` version of your Ngrok URL
+- Ensure Ngrok is running properly
+- Try restarting Ngrok and updating the webhook
+</Accordion>
+
+## Next Steps
+
+After successful setup:
+
+1. **Test message flow** between Telegram and Chatwoot
+2. **Configure agent assignments** for Telegram conversations
+3. **Set up automated responses** if needed
+4. **Review webhook logs** for debugging
+
+## Getting Help
+
+If you encounter issues:
+
+- **Check Logs**: Review both Chatwoot and Ngrok logs
+- **Telegram Bot API**: [Official Documentation](https://core.telegram.org/bots/api)
+- **Common Errors**: See [Common Errors](/contributing/project-setup/common-errors)
+- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
+
+---
+
+Your Telegram integration is now ready for development and testing! 📱 

developer-docs/contributing/project-setup/ubuntu-setup.mdx

@@ -0,0 +1,246 @@
+---
+title: Ubuntu Development Setup
+description: Complete guide to setting up your Ubuntu development environment for Chatwoot contribution.
+sidebarTitle: Ubuntu Setup
+---
+
+# Ubuntu Development Setup
+
+This guide will help you set up your Ubuntu development environment for contributing to Chatwoot. These instructions work for Ubuntu 20.04, 22.04, and newer versions.
+
+## Update System Packages
+
+First, update your system packages to ensure you have the latest security updates:
+
+```bash
+sudo apt update
+sudo apt upgrade -y
+```
+
+## Install Essential Build Tools
+
+Install fundamental development tools and dependencies:
+
+```bash
+sudo apt install -y curl wget gnupg2 software-properties-common apt-transport-https ca-certificates build-essential libssl-dev libreadline-dev zlib1g-dev libyaml-dev libxml2-dev libxslt-dev
+```
+
+## Install Git
+
+Install Git for version control:
+
+```bash
+sudo apt install -y git
+```
+
+Configure Git with your information:
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+```
+
+Verify Git installation:
+
+```bash
+git --version
+```
+
+## Install Ruby Version Manager (RVM)
+
+Install RVM to manage Ruby versions:
+
+```bash
+# Install GPG keys
+curl -sSL https://rvm.io/mpapis.asc | gpg --import -
+curl -sSL https://rvm.io/pkuczynski.asc | gpg --import -
+
+# Install RVM
+curl -L https://get.rvm.io | bash -s stable
+
+# Load RVM into current shell
+source ~/.rvm/scripts/rvm
+```
+
+Add RVM to your shell profile:
+
+```bash
+echo 'source ~/.rvm/scripts/rvm' >> ~/.bashrc
+source ~/.bashrc
+```
+
+## Install Ruby
+
+Install Ruby 3.2.2 using RVM:
+
+```bash
+# Install Ruby 3.2.2
+rvm install ruby-3.2.2
+
+# Set as default Ruby version
+rvm use 3.2.2 --default
+
+# Verify installation
+ruby --version
+# Should output: ruby 3.2.2
+```
+
+## Install Node.js
+
+Install Node.js 20 using NodeSource repository:
+
+```bash
+# Add NodeSource repository
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+
+# Install Node.js
+sudo apt install -y nodejs
+
+# Verify installation
+node --version
+# Should output: v20.x.x
+
+npm --version
+```
+
+## Install pnpm
+
+Install pnpm package manager:
+
+```bash
+# Install pnpm globally
+npm install -g pnpm
+
+# Verify installation
+pnpm --version
+```
+
+## Install PostgreSQL
+
+Install PostgreSQL database server:
+
+```bash
+# Install PostgreSQL
+sudo apt install -y postgresql postgresql-contrib libpq-dev
+
+# Start and enable PostgreSQL service
+sudo systemctl start postgresql
+sudo systemctl enable postgresql
+```
+
+Configure PostgreSQL:
+
+```bash
+# Switch to postgres user and create a superuser
+sudo -u postgres createuser --superuser $USER
+
+# Set password for your user
+sudo -u postgres psql -c "ALTER USER $USER PASSWORD 'password';"
+
+# Create a database for your user
+sudo -u postgres createdb $USER
+```
+
+Verify PostgreSQL installation:
+
+```bash
+psql --version
+psql -c "SELECT version();"
+```
+
+## Install Redis
+
+Install Redis server for background job processing:
+
+```bash
+# Install Redis
+sudo apt install -y redis-server
+
+# Start and enable Redis service
+sudo systemctl start redis-server
+sudo systemctl enable redis-server
+```
+
+Verify Redis installation:
+
+```bash
+redis-cli ping
+# Should output: PONG
+```
+
+## Install ImageMagick
+
+Install ImageMagick for image processing:
+
+```bash
+sudo apt install -y imagemagick libmagickwand-dev
+```
+
+Verify ImageMagick installation:
+
+```bash
+convert --version
+```
+
+## Troubleshooting Common Issues
+
+<Accordion title="Ruby installation fails">
+**Solution**: Install missing dependencies:
+```bash
+sudo apt install -y autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev
+rvm reinstall 3.2.2
+```
+</Accordion>
+
+<Accordion title="PostgreSQL authentication fails">
+**Solution**: Configure peer authentication:
+```bash
+sudo -u postgres psql
+ALTER USER postgres PASSWORD 'your_password';
+\q
+
+# Edit pg_hba.conf
+sudo nano /etc/postgresql/*/main/pg_hba.conf
+# Change 'peer' to 'md5' for local connections
+sudo systemctl restart postgresql
+```
+</Accordion>
+
+<Accordion title="Permission denied for /usr/local">
+**Solution**: Fix ownership:
+```bash
+sudo chown -R $USER:$USER /usr/local
+```
+</Accordion>
+
+<Accordion title="Node.js installation issues">
+**Solution**: Use Node Version Manager (nvm):
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+source ~/.bashrc
+nvm install 20
+nvm use 20
+nvm alias default 20
+```
+</Accordion>
+
+<Accordion title="ImageMagick policy errors">
+**Solution**: Update ImageMagick policy:
+```bash
+sudo nano /etc/ImageMagick-6/policy.xml
+# Comment out or modify restrictive policies
+```
+</Accordion>
+
+## Getting Help
+
+If you encounter issues:
+
+- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
+- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
+- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)
+- **Ubuntu Community**: [Ubuntu Forums](https://ubuntuforums.org/)
+
+---
+
+Your Ubuntu development environment is now ready for Chatwoot development! 🐧 

developer-docs/contributing/project-setup/windows-setup.mdx

@@ -0,0 +1,320 @@
+---
+title: Windows Development Setup
+description: Complete guide to setting up your Windows development environment for Chatwoot contribution using WSL2.
+sidebarTitle: Windows Setup
+---
+
+# Windows Development Setup
+
+This guide will walk you through setting up your Windows development environment for contributing to Chatwoot. We'll use Windows Subsystem for Linux 2 (WSL2) which provides the best development experience on Windows.
+
+## Requirements
+
+You need to install the Windows Subsystem for Linux 2 (WSL2) on your Windows machine.
+
+### Prerequisites
+
+- Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11
+- Administrator privileges on your Windows machine
+
+## Step 1: Enable Developer Mode
+
+The first step is to enable "Developer mode" in Windows. You can do this by opening up Settings and navigating to "Update & Security". In there, choose the tab on the left that reads "For Developers". Turn the "Developer mode" toggle on to enable it.
+
+<img src="/contributing/project-setup/img/developer-mode.jpg" width="500" alt="Enable Developer Mode" />
+
+## Step 2: Enable Windows Subsystem for Linux
+
+Next you have to enable the Windows Subsystem for Linux. Open the "Control Panel" and go to "Programs and Features". Click on the link on the left "Turn Windows features on or off". Look for the "Windows Subsystem for Linux" option and select the checkbox next to it.
+
+<img src="/contributing/project-setup/img/enable-wsl.jpg" width="500" alt="Enable WSL" />
+
+You'll also need to enable "Virtual Machine Platform" for WSL2. Make sure both checkboxes are selected:
+- ✅ Windows Subsystem for Linux
+- ✅ Virtual Machine Platform
+
+After enabling these features, restart your computer.
+
+## Step 3: Install WSL2 and Ubuntu
+
+### Option 1: Using Microsoft Store (Recommended)
+
+1. **Open Microsoft Store** and search for "Ubuntu"
+2. **Install Ubuntu 22.04 LTS** (or latest LTS version)
+3. **Launch Ubuntu** from the Start Menu
+
+### Option 2: Using Command Line
+
+Open PowerShell as Administrator and run:
+
+```powershell
+# Install WSL2 with Ubuntu
+wsl --install -d Ubuntu-22.04
+
+# Set WSL2 as default version
+wsl --set-default-version 2
+```
+
+## Step 4: Initial Ubuntu Setup
+
+When you first launch Ubuntu, you'll be prompted to create a user account:
+
+```bash
+# Create a username and password when prompted
+# This will be your Linux user account
+```
+
+Update the system packages:
+
+```bash
+sudo apt update && sudo apt upgrade -y
+```
+
+## Step 5: Install Core Dependencies
+
+You need core Linux dependencies installed in order to install Ruby and other tools.
+
+```bash
+sudo apt-get update
+sudo apt-get install -y git-core curl zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev
+```
+
+## Installing RVM & Ruby
+
+Install additional dependencies required for RVM:
+
+```bash
+sudo apt-get install -y libgdbm-dev libncurses5-dev automake libtool bison libffi-dev
+```
+
+Install RVM & Ruby version 3.2.2:
+
+```bash
+# Add RVM GPG keys
+gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
+
+# Install RVM
+curl -sSL https://get.rvm.io | bash -s stable
+
+# Load RVM into current session
+source ~/.rvm/scripts/rvm
+
+# Install Ruby 3.2.2
+rvm install 3.2.2
+rvm use 3.2.2 --default
+
+# Verify installation
+ruby -v
+```
+
+## Install Node.js
+
+Chatwoot requires Node.js version 20. Install Node.js from NodeSource using the following commands:
+
+```bash
+curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+Verify Node.js installation:
+
+```bash
+node --version
+# Should output: v20.x.x
+```
+
+## Install pnpm
+
+We use `pnpm` as the package manager for better performance:
+
+```bash
+# Install pnpm globally
+npm install -g pnpm
+
+# Verify installation
+pnpm --version
+```
+
+## Install PostgreSQL
+
+The database used in Chatwoot is PostgreSQL. Use the following commands to install PostgreSQL:
+
+```bash
+sudo apt install -y postgresql postgresql-contrib
+```
+
+The installation procedure created a user account called postgres that is associated with the default Postgres role. In order to use PostgreSQL, you can log into that account:
+
+```bash
+sudo -u postgres psql
+```
+
+Install `libpq-dev` dependencies for Ubuntu:
+
+```bash
+sudo apt-get install -y libpq-dev
+```
+
+Start PostgreSQL service:
+
+```bash
+sudo service postgresql start
+```
+
+Configure PostgreSQL to start automatically:
+
+```bash
+echo 'sudo service postgresql start' >> ~/.bashrc
+```
+
+Create a database user:
+
+```bash
+# Switch to postgres user and create a superuser
+sudo -u postgres createuser --superuser $USER
+
+# Set password for your user  
+sudo -u postgres psql -c "ALTER USER $USER PASSWORD 'password';"
+```
+
+## Install Redis Server
+
+Chatwoot uses Redis server for agent assignments and reporting. To install `redis-server`:
+
+```bash
+sudo apt-get install -y redis-server
+```
+
+Start Redis service:
+
+```bash
+sudo service redis-server start
+```
+
+Configure Redis to start automatically:
+
+```bash
+echo 'sudo service redis-server start' >> ~/.bashrc
+```
+
+Enable Redis to start on system boot:
+
+```bash
+sudo systemctl enable redis-server.service
+```
+
+## Install ImageMagick
+
+Chatwoot uses ImageMagick for image processing:
+
+```bash
+sudo apt-get install -y imagemagick libmagickwand-dev
+```
+
+## Configure Git
+
+Set up Git with your information:
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+```
+
+## Windows-Specific Configuration
+
+### Install VS Code with WSL Extension
+
+1. **Install Visual Studio Code** on Windows from [https://code.visualstudio.com/](https://code.visualstudio.com/)
+2. **Install Remote - WSL extension** from the Extensions marketplace
+3. **Open your project in WSL** by running `code .` from your WSL terminal
+
+### Configure File Permissions
+
+WSL2 may have file permission issues. Fix them:
+
+```bash
+# Add to ~/.bashrc for better file permissions
+echo 'umask 022' >> ~/.bashrc
+
+# Configure Git to ignore file mode changes
+git config --global core.filemode false
+```
+
+## Environment Verification
+
+Verify all installations are working correctly:
+
+```bash
+# Check all versions
+ruby --version        # Should be 3.2.2
+node --version         # Should be v20.x.x
+pnpm --version        # Should show pnpm version
+psql --version        # Should show PostgreSQL version
+redis-cli ping        # Should output: PONG
+convert --version     # Should show ImageMagick version
+git --version         # Should show Git version
+```
+
+## Troubleshooting Common Issues
+
+<Accordion title="WSL installation fails">
+**Solution**: Ensure virtualization is enabled in BIOS and Windows features are properly enabled:
+1. Restart computer and enter BIOS settings
+2. Enable Intel VT-x or AMD-V virtualization
+3. Enable Hyper-V in Windows Features
+4. Restart and try installation again
+</Accordion>
+
+<Accordion title="Ubuntu terminal won't open">
+**Solution**: Reset WSL or reinstall Ubuntu:
+```powershell
+# Reset Ubuntu (will delete all data)
+wsl --unregister Ubuntu-22.04
+wsl --install -d Ubuntu-22.04
+```
+</Accordion>
+
+<Accordion title="PostgreSQL fails to start">
+**Solution**: Check if Windows PostgreSQL service is conflicting:
+```bash
+# Stop Windows PostgreSQL service first (run in Windows Command Prompt as Admin)
+net stop postgresql-x64-14
+
+# Then start WSL2 PostgreSQL
+sudo service postgresql start
+```
+</Accordion>
+
+<Accordion title="Permission denied errors">
+**Solution**: Fix file permissions:
+```bash
+# For the entire project
+find . -type f -exec chmod 644 {} \;
+find . -type d -exec chmod 755 {} \;
+
+# For executable files
+chmod +x bin/*
+```
+</Accordion>
+
+<Accordion title="Slow performance">
+**Solution**: Ensure code is stored in WSL2 filesystem:
+```bash
+# Good: Store code here (fast)
+/home/username/projects/chatwoot
+
+# Avoid: Storing code here (slow)
+/mnt/c/Users/Username/projects/chatwoot
+```
+</Accordion>
+
+If you encounter issues during setup:
+
+- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
+- **WSL2 Documentation**: [Microsoft WSL Documentation](https://docs.microsoft.com/en-us/windows/wsl/)
+- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
+- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)
+
+---
+
+Your Windows development environment with WSL2 is now ready for Chatwoot development! 🪟🐧 

developer-docs/contributing/security-reports.mdx

@@ -0,0 +1,127 @@
+---
+title: Reporting Security Issues
+description: How to report security vulnerabilities in Chatwoot
+sidebarTitle: Security Reports
+---
+
+# Reporting Security Issues
+
+Chatwoot is looking forward to working with security researchers worldwide to keep Chatwoot and our users safe. If you have found an issue in our systems/applications, please reach out to us.
+
+## Reporting a Vulnerability
+
+We use GitHub for security issues that affect our project. If you believe you have found a vulnerability, please disclose it via this [form](https://github.com/chatwoot/chatwoot/security/advisories/new).
+
+This will enable us to review the vulnerability, fix it promptly, and reward you for your efforts.
+
+If you have any questions about the process, contact **security@chatwoot.com**.
+
+Please try your best to describe a clear and realistic impact for your report, and please don't open any public issues on GitHub or social media; we're doing our best to respond through GitHub as quickly as possible.
+
+<Note>
+Please use the email for questions related to the process. Disclosures should be done via [GitHub](https://github.com/chatwoot/chatwoot/security/advisories/new).
+</Note>
+
+## Supported Versions
+
+| Version  | Supported |
+| -------- | --------- |
+| latest   | ️✅        |
+| < latest | ❌         |
+
+## Vulnerabilities We Care About 🫣
+
+<Warning>
+Please do not perform testing against Chatwoot production services. Use a `self-hosted instance` to perform tests.
+</Warning>
+
+We consider the following vulnerabilities as high priority:
+
+- Remote command execution
+- SQL Injection
+- Authentication bypass
+- Privilege Escalation
+- Cross-site scripting (XSS)
+- Performing limited admin actions without authorization
+- CSRF
+
+## Non-Qualifying Vulnerabilities
+
+We consider the following out of scope, though there may be exceptions:
+
+- Missing HTTP security headers
+- Incomplete/Missing SPF/DKIM
+- Reports from automated tools or scanners
+- Theoretical attacks without proof of exploitability
+- Social engineering
+- Reflected file download
+- Physical attacks
+- Weak SSL/TLS/SSH algorithms or protocols
+- Attacks involving physical access to a user's device or a device or network that's already seriously compromised (e.g., man-in-the-middle)
+- The user attacks themselves
+- Incomplete/Missing SPF/DKIM
+- Denial of Service attacks
+- Brute force attacks
+- DNSSEC
+
+If you are unsure about the scope, please create a [report](https://github.com/chatwoot/chatwoot/security/advisories/new).
+
+## Triaging Process
+
+Chatwoot team triages the issues in GitHub weekly. We're doing our best to respond through GitHub as quickly as we can, so please don't open any public issues on GitHub or social media and avoid duplicate reports over emails.
+
+- Based on reviewing the report, the team will assign a priority to the issue and move it into the internal backlog to prioritize a fix.
+- In cases where the team needs more information or disagreements of severity, the team will communicate the same over GitHub before completing the triaging.
+
+After triage, the team will start working on the issue based on the following severity and timelines:
+
+## Response Timeline
+
+| Severity      | Timeline  |
+| ------------- | --------- |
+| Critical (P0) | ️  7 Days |
+| High          | 30 Days   |
+| Medium        | 60 Days   |
+| Low           | 90 Days   |
+
+## Security Best Practices
+
+### For Researchers
+
+- **Test Responsibly**: Only test on your own self-hosted instances
+- **Provide Clear Details**: Include steps to reproduce, impact assessment, and suggested fixes
+- **Be Patient**: Allow time for our team to investigate and respond
+- **Follow Responsible Disclosure**: Don't publish vulnerabilities publicly until they're fixed
+
+### For Users
+
+- **Keep Updated**: Always use the latest version of Chatwoot
+- **Secure Configuration**: Follow security best practices for your deployment
+- **Monitor Logs**: Regularly check logs for suspicious activity
+- **Report Issues**: If you notice anything unusual, report it through proper channels
+
+## Bounty Program
+
+While we don't currently have a formal bug bounty program, we do recognize and appreciate security researchers who help us improve Chatwoot's security:
+
+- **Hall of Fame**: Recognition on our security acknowledgments page
+- **Direct Communication**: Work directly with our security team
+- **Early Access**: Get early access to security updates and patches
+
+## Getting Help
+
+If you need assistance with security reporting:
+
+- **Process Questions**: Contact security@chatwoot.com
+- **Technical Issues**: Use our [Discord community](https://discord.com/invite/cJXdrwS)
+- **General Support**: Check our [documentation](/contributing/project-setup/common-errors)
+
+## Thanks
+
+Thank you for keeping Chatwoot and our users safe. 🙇
+
+Your efforts help us maintain a secure platform for thousands of businesses worldwide. We appreciate the time and expertise you contribute to making Chatwoot better for everyone.
+
+---
+
+Remember: Security is a shared responsibility. Together, we can make Chatwoot safer for everyone. 

developer-docs/contributing/translation-guidelines.mdx

@@ -0,0 +1,151 @@
+---
+title: Translate Chatwoot to Your Language
+description: Guide to translating Chatwoot using Crowdin translation platform
+sidebarTitle: Translation Guidelines
+---
+
+# Translate Chatwoot to Your Language
+
+Chatwoot uses American English by default. Each and every string available in Chatwoot can be translated to the language of your choice. Chatwoot uses Crowdin to manage the translation process. The updates from Crowdin are also included along with every release.
+
+## How do I see the strings that need to be translated?
+
+In the codebase, the strings are placed in the following locations:
+
+- `app/javascript/dashboard/i18n` - The strings related to the agent dashboard
+- `app/javascript/widget/i18n` - The strings related to the web widget
+- `app/javascript/survey/i18n` - The strings related to CSAT surveys
+- `config/locales` - The strings used in backend messages or API responses
+
+You can login to **Crowdin** ([https://translate.chatwoot.com](https://translate.chatwoot.com)) and create an account to view the strings that need to be translated.
+
+## How to contribute?
+
+If you don't find your language on Crowdin, please create an issue on [GitHub](https://github.com/chatwoot/chatwoot/issues) to add the language.
+
+### Translate Strings
+
+The translation process for Chatwoot web and mobile app is managed at [https://translate.chatwoot.com](https://translate.chatwoot.com) using Crowdin. You will have to create an account at Crowdin before you can select a language and contribute.
+
+<Note>
+New to Crowdin? Check out their [getting started guide](https://support.crowdin.com/crowdin-intro/) to learn the basics of translation management.
+</Note>
+
+### Translation Guidelines
+
+#### Formal vs Informal Context
+
+At Chatwoot, we prefer to use formal form of language wherever possible. For instance in German there are two forms of "you" where one is rather used in formal contexts ("Sie") and the other one is used among friends ("Du"). "Sie" is preferred over "Du" in translating Chatwoot.
+
+#### Consistency Guidelines
+
+- **Maintain consistency** across similar contexts and features
+- **Use standard terminology** for technical terms when available in your language
+- **Keep placeholders intact** - Don't translate variables like `{name}` or `%{count}`
+- **Preserve formatting** - Maintain HTML tags, markdown, and line breaks
+- **Consider context** - UI strings may need to be shorter than descriptive text
+
+#### Brand and Product Names
+
+- **Chatwoot** - Always keep as "Chatwoot" (don't translate)
+- **Feature names** - Translate feature names but maintain consistency
+- **Third-party services** - Keep original names (GitHub, Slack, etc.)
+
+### Proofreading
+
+Proofreading helps ensure the accuracy and consistency of translations. Right now, the translations are being accepted without a proofreading step. This would be changed in the future as and when there are more contributors for each language.
+
+<Warning>
+If you are the only person contributing to a language, make sure that you inform any of the Chatwoot members to gain access to manage the language.
+</Warning>
+
+### Releasing a New Language
+
+All the translated strings would be included in the next release. If a language has **60% or more translated strings** in Crowdin, we would enable the language in Chatwoot app during the next release.
+
+#### Steps to Raise a Pull Request for New Language
+
+Please use this [pull request](https://github.com/chatwoot/chatwoot/pull/7905) as a reference for enabling a new language into Chatwoot.
+
+- Ensure language is added and enabled in `config/initializers/languages.rb`
+- Include the language in `i18n/index.js` for all the packs → `dashboard, widget, survey`
+- Select the language from Chatwoot settings UI and confirm the PR to be working
+
+## Translation Progress and Metrics
+
+### Current Status
+
+You can check the translation progress for different languages on our [Crowdin project page](https://translate.chatwoot.com). This shows:
+
+- **Overall completion percentage** for each language
+- **Component-wise progress** (Dashboard, Widget, Survey, API)
+- **Recent activity** and contributor statistics
+
+### Quality Metrics
+
+We track several quality indicators:
+
+- **Translation coverage** - Percentage of strings translated
+- **Review coverage** - Percentage of translations reviewed
+- **Consistency score** - How consistent terminology is across the platform
+- **Community engagement** - Number of active translators
+
+## Best Practices for Translators
+
+### Before You Start
+
+1. **Review existing translations** in your language for consistency
+2. **Understand the context** - Test the feature in Chatwoot if possible
+3. **Check for existing glossaries** or style guides for your language
+4. **Join the community** discussions for your language
+
+### During Translation
+
+1. **Focus on user experience** - How will end users understand this?
+2. **Maintain professional tone** appropriate for business communication
+3. **Ask questions** if context is unclear
+4. **Suggest improvements** for source text if needed
+
+### After Translation
+
+1. **Test your translations** in a live Chatwoot instance
+2. **Report issues** if translations don't fit in the UI
+3. **Help review** other contributors' work
+4. **Stay updated** with new strings added
+
+## Getting Help and Support
+
+### Community Resources
+
+- **GitHub Discussions**: [Translation category](https://github.com/chatwoot/chatwoot/discussions/categories/translations)
+- **Discord**: Join our [Discord community](https://discord.gg/uPtCrFfb9B) (#translations channel)
+- **Crowdin Comments**: Use comments feature in Crowdin for context-specific questions
+
+### Technical Support
+
+For technical issues with translations:
+
+- **Missing context**: Create an issue on GitHub
+- **UI layout problems**: Report in Discord with screenshots  
+- **Crowdin access issues**: Contact the maintainers
+
+### Recognition
+
+We recognize and appreciate our translation contributors:
+
+- **Contributors page**: Featured on our contributors page
+- **Release notes**: Mentioned in release announcements
+- **Community highlights**: Featured in community updates
+
+## Multilingual Support Features
+
+Chatwoot's internationalization supports:
+
+- **Right-to-left (RTL) languages** - Arabic, Hebrew, etc.
+- **Pluralization rules** - Correct plural forms for different languages
+- **Date and time formatting** - Localized date/time display
+- **Number formatting** - Currency and number format localization
+
+---
+
+Ready to help make Chatwoot accessible to users worldwide? [Start translating today](https://translate.chatwoot.com)! 🌍 

developer-docs/docs.json

@@ -28,23 +28,36 @@
   },
   "theme": "maple",
   "navigation": {
-    "groups": [
+    "anchors": [
       {
-        "group": "Getting Started",
+        "anchor": "Introduction",
+        "icon": "house",
         "pages": [
           "introduction"
         ]
       },
       {
-        "group": "Self-Hosted Installation",
+        "anchor": "Installation & Setup",
+        "icon": "server",
         "pages": [
-          "self-hosted/introduction",
-          "self-hosted/architecture",
           {
-            "group": "Deployment",
+            "group": "Getting Started",
             "pages": [
-              "self-hosted/deployment/linux-vm",
-              "self-hosted/deployment/docker",
+              "self-hosted/introduction",
+              "self-hosted/architecture",
+              "self-hosted/requirements"
+            ]
+          },
+          {
+            "group": "Deployment Methods",
+            "pages": [
+              {
+                "group": "Linux",
+                "pages": [
+                  "self-hosted/deployment/linux-vm",
+                  "self-hosted/deployment/docker"
+                ]
+              },
               "self-hosted/deployment/kubernetes",
               "self-hosted/deployment/chatwoot-ctl"
             ]
@@ -52,96 +65,232 @@
           {
             "group": "Cloud Providers",
             "pages": [
-              "self-hosted/cloud/aws",
+              {
+                "group": "AWS",
+                "pages": [
+                  "self-hosted/cloud/aws",
+                  "self-hosted/cloud/aws-marketplace"
+                ]
+              },
               "self-hosted/cloud/azure",
               "self-hosted/cloud/digitalocean",
               "self-hosted/cloud/gcp",
-              "self-hosted/cloud/heroku"
+              "self-hosted/cloud/heroku",
+              {
+                "group": "Community Contributed",
+                "pages": [
+                  "self-hosted/cloud/caprover",
+                  "self-hosted/cloud/clevercloud",
+                  "self-hosted/cloud/cloudron",
+                  "self-hosted/cloud/restack",
+                  "self-hosted/cloud/easypanel",
+                  "self-hosted/cloud/elestio"
+                ]
+              }
             ]
           },
           {
             "group": "Configuration",
             "pages": [
-              "self-hosted/configuration/environment-variables"
+              "self-hosted/configuration/environment-variables",
+              {
+                "group": "Performance",
+                "pages": [
+                  "self-hosted/configuration/performance/optimizing-configurations",
+                  "self-hosted/configuration/performance/cloudfront-cdn"
+                ]
+              },
+              {
+                "group": "Monitoring",
+                "pages": [
+                  "self-hosted/configuration/monitoring/super-admin-console",
+                  "self-hosted/configuration/monitoring/apm-and-tracing",
+                  "self-hosted/configuration/monitoring/rate-limiting"
+                ]
+              },
+              {
+                "group": "Storage",
+                "pages": [
+                  "self-hosted/configuration/storage/supported-providers",
+                  "self-hosted/configuration/storage/s3-bucket",
+                  "self-hosted/configuration/storage/gcs-bucket"
+                ]
+              },
+              {
+                "group": "Email Channel",
+                "pages": [
+                  "self-hosted/configuration/features/email-channel/conversation-continuity",
+                  "self-hosted/configuration/features/email-channel/conversation-continuity-using-sendgrid",
+                  "self-hosted/configuration/features/email-channel/email-channel-setup",
+                  "self-hosted/configuration/features/email-channel/azure-app-setup",
+                  "self-hosted/configuration/features/email-channel/google-workspace-setup"
+                ]
+              },
+              {
+                "group": "Help Center",
+                "pages": [
+                  "self-hosted/configuration/help-center"
+                ]
+              }
+            ]
+          },
+          {
+            "group": "Integrations",
+            "pages": [
+              "self-hosted/configuration/integrations/facebook-channel-setup",
+              "self-hosted/configuration/integrations/instagram-channel-setup",
+              "self-hosted/configuration/integrations/instagram-via-instagram-business-login",
+              "self-hosted/configuration/integrations/slack-integration-setup",
+              "self-hosted/configuration/integrations/linear-integration-setup",
+              "self-hosted/configuration/integrations/shopify-integration-setup"
+            ]
+          },
+          {
+            "group": "Maintenance",
+            "pages": [
+              "self-hosted/maintenance/upgrade",
+              "self-hosted/maintenance/backup"
+            ]
+          },
+          {
+            "group": "Runbooks",
+            "pages": [
+              "self-hosted/runbook/migrate-chatwoot-database",
+              "self-hosted/runbook/upgrade-to-chatwoot-v4",
+              "self-hosted/runbook/enable-ip-logging",
+              "self-hosted/runbook/email-notifications"
+            ]
+          },
+          {
+            "group": "Others",
+            "pages": [
+              "self-hosted/others/telemetry",
+              "self-hosted/others/enterprise-edition",
+              "self-hosted/others/supported-features",
+              "self-hosted/others/restricted-instances",
+              "self-hosted/others/instagram-app-review",
+              "self-hosted/others/faq"
             ]
           }
         ]
       },
       {
-        "group": "Contributing Guide",
+        "anchor": "Contributing Guide",
+        "icon": "code",
         "pages": [
-          "contributing/introduction",
+          {
+            "group": "Getting Started",
+            "pages": [
+              "contributing/introduction"
+            ]
+          },
+          {
+            "group": "Environment Setup",
+            "pages": [
+              "contributing/project-setup/macos-setup",
+              "contributing/project-setup/ubuntu-setup",
+              "contributing/project-setup/windows-setup",
+              "contributing/project-setup/docker-setup",
+              "contributing/project-setup/make-setup"
+            ]
+          },
           {
             "group": "Project Setup",
             "pages": [
               "contributing/project-setup/setup-guide",
               "contributing/project-setup/environment-variables",
-              "contributing/project-setup/common-errors"
+              "contributing/project-setup/common-errors",
+              "contributing/project-setup/telegram-channel-setup",
+              "contributing/project-setup/line-channel-setup",
+              "contributing/project-setup/mobile-app-setup"
             ]
           },
-          "contributing/testing",
-          "contributing/guidelines",
-          "contributing/code-of-conduct"
+          {
+            "group": "Testing",
+            "pages": [
+              "contributing/cypress"
+            ]
+          },
+          {
+            "group": "Others",
+            "pages": [
+              "contributing/code-of-conduct",
+              "contributing/security-reports",
+              "contributing/translation-guidelines",
+              "contributing/community-guidelines",
+              "contributing/contributors"
+            ]
+          }
         ]
       },
       {
-        "group": "API Reference",
-        "pages": []
-      },
-      {
-        "group": "Application API",
-        "description": "APIs for managing application aspects of Chatwoot",
-        "includeTags": [
-          "Agents",
-          "Automation Rule",
-          "Account AgentBots",
-          "Canned Responses",
-          "Contact Labels",
-          "Contacts",
-          "Conversation Assignments",
-          "Conversation Labels",
-          "Conversations",
-          "Custom Attributes",
-          "Custom Filters",
-          "Help Center",
-          "Inboxes",
-          "Integrations",
-          "Messages",
-          "Profile",
-          "Reports",
-          "Teams",
-          "Webhooks"
-        ],
-        "openapi": "https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json"
-      },
-      {
-        "group": "Platform API",
-        "description": "APIs for managing platform aspects of Chatwoot",
-        "includeTags": [
-          "Accounts",
-          "Account Users",
-          "AgentBots",
-          "Users"
-        ],
-        "openapi": "https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json"
-      },
-      {
-        "group": "Client API",
-        "description": "APIs for client applications",
-        "includeTags": [
-          "Contacts API",
-          "Conversations API",
-          "Messages API"
-        ],
-        "openapi": "https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json"
-      },
-      {
-        "group": "Other APIs",
-        "description": "Other Chatwoot APIs",
-        "includeTags": [
-          "CSAT Survey Page"
-        ],
-        "openapi": "https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/other_swagger.json"
+        "anchor": "API Reference",
+        "icon": "square-terminal",
+        "pages": [],
+        "groups": [
+          {
+            "group": "Getting Started",
+            "description": "Learn about Chatwoot APIs and how to use them",
+            "pages": [
+              "api-reference/introduction"
+            ]
+          },
+          {
+            "group": "Application APIs",
+            "description": "APIs for managing application aspects of Chatwoot",
+            "includeTags": [
+              "Agents",
+              "Automation Rule",
+              "Account AgentBots",
+              "Canned Responses",
+              "Contact Labels",
+              "Contacts",
+              "Conversation Assignments",
+              "Conversation Labels",
+              "Conversations",
+              "Custom Attributes",
+              "Custom Filters",
+              "Help Center",
+              "Inboxes",
+              "Integrations",
+              "Messages",
+              "Profile",
+              "Reports",
+              "Teams",
+              "Webhooks"
+            ],
+            "openapi": "https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json"
+          },
+          {
+            "group": "Platform APIs",
+            "description": "APIs for managing platform aspects of Chatwoot",
+            "includeTags": [
+              "Accounts",
+              "Account Users",
+              "AgentBots",
+              "Users"
+            ],
+            "openapi": "https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json"
+          },
+          {
+            "group": "Client APIs",
+            "description": "APIs for client applications",
+            "includeTags": [
+              "Contacts API",
+              "Conversations API",
+              "Messages API"
+            ],
+            "openapi": "https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json"
+          },
+          {
+            "group": "Other APIs",
+            "description": "Additional Chatwoot APIs",
+            "includeTags": [
+              "CSAT Survey Page"
+            ],
+            "openapi": "https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/other_swagger.json"
+          }
+        ]
       }
     ]
   },

developer-docs/introduction.mdx

@@ -1,49 +1,96 @@
 ---
-title: Introduction to Chatwoot APIs
-description: Learn how to use Chatwoot APIs to build integrations, customize chat experiences, and manage your installation.
+title: Welcome to Chatwoot Developer Docs
+description: Your comprehensive guide to installing, configuring, developing with, and integrating Chatwoot - the open-source customer support platform.
 sidebarTitle: Introduction
 ---
 
-Welcome to the Chatwoot API documentation. Whether you're building custom workflows for your support team, integrating Chatwoot into your product, or managing users across installations, our APIs provide the flexibility and power to help you do more with Chatwoot.
+# Welcome to Chatwoot Developer Documentation
 
-Chatwoot provides three categories of APIs, each designed with a specific use case in mind:
+Welcome to the complete developer documentation for Chatwoot, the open-source customer support platform trusted by thousands of businesses worldwide. Whether you're setting up your own instance, contributing to the project, or building integrations, this documentation will guide you through every step.
 
-- **Application APIs** – For account-level automation and agent-facing integrations.
-- **Client APIs** – For building custom chat interfaces for end-users
-- **Platform APIs** – For managing and administering installations at scale
+## What You'll Find Here
+
+<CardGroup cols={2}>
+  <Card
+    title="Installation & Setup"
+    icon="server"
+    href="/self-hosted/introduction"
+  >
+    Deploy Chatwoot on your infrastructure with Docker, Kubernetes, or cloud providers
+  </Card>
+  <Card
+    title="Development Guide"
+    icon="code"
+    href="/contributing/introduction"
+  >
+    Contribute to Chatwoot with our development setup, testing guidelines, and best practices
+  </Card>
+  <Card
+    title="API Reference"
+    icon="square-terminal"
+    href="/api-reference/introduction"
+  >
+    Build powerful integrations with our comprehensive REST APIs
+  </Card>
+  <Card
+    title="Architecture"
+    icon="sitemap"
+    href="/self-hosted/architecture"
+  >
+    Understand Chatwoot's system architecture and components
+  </Card>
+</CardGroup>
+
+## Getting Started Paths
+
+Choose your path based on what you want to accomplish:
+
+### 🚀 **I want to install Chatwoot**
+Perfect! Head to our [Installation Guide](/self-hosted/introduction) to deploy Chatwoot on your preferred platform. We support:
+- Docker containers for quick setup
+- Kubernetes for scalable deployments  
+- Major cloud providers (AWS, GCP, Azure)
+- Traditional Linux VMs
+
+### 🛠️ **I want to contribute to Chatwoot**
+Amazing! Check out our [Contributing Guide](/contributing/introduction) to:
+- Set up your development environment
+- Understand our coding standards
+- Learn our testing practices
+- Submit your first pull request
+
+### 🔌 **I want to build integrations**
+Great! Explore our [API Reference](/api-reference/introduction) with three categories of APIs:
+- **Application APIs** - Manage accounts, agents, and conversations
+- **Platform APIs** - Administrative control for installations
+- **Client APIs** - Build custom chat interfaces
+
+### 📚 **I want to understand the architecture**
+Excellent! Our [Architecture Guide](/self-hosted/architecture) covers:
+- System components and their interactions
+- Database schemas and relationships
+- Scalability considerations
+- Security best practices
+
+## Why Chatwoot?
+
+Chatwoot is built with modern technologies and follows industry best practices:
+
+- **Open Source**: Full transparency and community-driven development
+- **Multi-channel**: Support customers across web, mobile, email, and social platforms
+- **Scalable**: From small teams to enterprise deployments
+- **Extensible**: Rich APIs and webhook system for custom integrations
+- **Modern Stack**: Ruby on Rails backend, Vue.js frontend, PostgreSQL database
+
+## Community & Support
+
+Join our thriving community of developers and users:
+
+- **GitHub**: [github.com/chatwoot/chatwoot](https://github.com/chatwoot/chatwoot)
+- **Community Slack**: [chatwoot.com/slack](https://chatwoot.com/slack)  
+- **Discussions**: [GitHub Discussions](https://github.com/chatwoot/chatwoot/discussions)
+- **Twitter**: [@chatwootapp](https://twitter.com/chatwootapp)
 
 ---
 
-## Application APIs
-
-Application APIs are designed for interacting with a Chatwoot account from an agent/admin perspective. Use them to build internal tools, automate workflows, or perform bulk operations like data import/export.
-
-- **Authentication**: Requires a user `access_token`, which can be generated from **Profile Settings** after logging into your Chatwoot account.
-- **Availability**: Supported on both **Cloud** and **Self-hosted** Chatwoot installations.
-- **Example**: [Google Cloud Functions Demo](https://github.com/chatwoot/google-cloud-functions-demo)
-
----
-
-## Client APIs
-
-Client APIs are intended for building custom messaging experiences over Chatwoot. If you're not using the native website widget or want to embed chat in your mobile app, these APIs are the way to go.
-
-- **Authentication**: Uses `inbox_identifier` (from **Settings → Configuration** in API inboxes) and `contact_identifier` (returned when creating a contact).
-- **Availability**: Supported on both **Cloud** and **Self-hosted** Chatwoot installations.
-- **Examples**:
-
-  - [Client API Demo](https://github.com/chatwoot/client-api-demo)
-  - [Flutter SDK](https://github.com/chatwoot/chatwoot-flutter-sdk)
-
----
-
-## Platform APIs
-
-Platform APIs are used to manage Chatwoot installations at the admin level. These APIs allow you to control users, roles, and accounts, or sync data from external authentication systems.
-
-- **Authentication**: Requires an `access_token` generated by a **Platform App**, which can be created in the **Super Admin Console**.
-- **Availability**: Available on **Self-hosted** / **Managed Hosting** Chatwoot installations only.
-
----
-
-Use the right API for your use case, and you'll be able to extend, customize, and integrate Chatwoot into your stack with ease.
+Ready to dive in? Choose your path above and let's build something amazing together! 🚀

developer-docs/self-hosted/architecture.mdx

@@ -1,342 +1,52 @@
 ---
-title: Chatwoot Architecture
-description: Understanding Chatwoot's system architecture, components, and how they work together.
+title: Chatwoot Production Deployment Guide
+description: Understanding Chatwoot's production architecture and deployment requirements
 sidebarTitle: Architecture
 ---
 
-Understanding Chatwoot's architecture is crucial for successful deployment, scaling, and maintenance. This guide explains the core components and how they interact.
+This guide will help you to deploy Chatwoot to production!
 
-## High-Level Architecture
+## Architecture
 
-Chatwoot follows a modern, scalable web application architecture with clear separation of concerns:
+Running Chatwoot in production requires the following set of services.
 
-```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
+* Chatwoot web servers
+* Chatwoot workers
+* PostgreSQL Database
+* Redis Database
+* Email service (SMTP servers / SendGrid / Mailgun etc)
+* Object Storage (S3, Azure Storage, GCS, etc)
+
+![architecture](/self-hosted/images/architecture.png)
+
+## Updating your Chatwoot installation
+
+A new version of Chatwoot is released around the first Monday of every month. We also release minor versions when there is a need for hotfixes or security updates.
+
+You can stay tuned to our [Roadmap](https://github.com/chatwoot/chatwoot/milestones) and [releases](https://github.com/chatwoot/chatwoot/releases) on GitHub. We recommend you to stay up to date with our releases to enjoy the latest features and security updates.
+
+The deployment process for a newer version involves updating your app servers and workers with the latest code. Most updates would involve database migrations as well which can be executed through the following Rails command.
+
+```bash
+bundle exec rails db:migrate
 ```
 
-## Core Components
+The detailed instructions can be found in respective deployment guides.
 
-### 1. Web Application (Rails)
+## Available deployment options
 
-The main application server built with Ruby on Rails handles:
+If you want to self host Chatwoot, the recommended approach is to use one of the recommended one click installation options from the below list. If you are comfortable with Ruby on Rails applications, you can also make use of the other deployment options mentioned below.
 
-- **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**
+* **[Heroku](/self-hosted/deployment/heroku)** (recommended)
+* **[Docker](/self-hosted/deployment/docker)** (recommended)
+* **[Linux](/self-hosted/deployment/linux-vm)**
+* **[Kubernetes](/self-hosted/deployment/kubernetes)**
+* **[Chatwoot CTL](/self-hosted/deployment/chatwoot-ctl)**
 
-**Key characteristics:**
-- Stateless design for horizontal scaling
-- RESTful API architecture
-- WebSocket support for real-time updates
-- Multi-tenant architecture support
+### Cloud Providers
 
-### 2. Background Workers (Sidekiq)
-
-Sidekiq handles asynchronous processing:
-
-- **Email notifications** and delivery
-- **Webhook processing** for integrations
-- **File processing** and optimization
-- **Report generation** and analytics
-- **Third-party API calls** (Facebook, WhatsApp, etc.)
-
-**Key characteristics:**
-- Redis-backed job queue
-- Retry mechanisms for failed jobs
-- Horizontal scaling support
-- Job prioritization and scheduling
-
-### 3. Database (PostgreSQL)
-
-PostgreSQL stores all application data:
-
-- **User accounts and authentication**
-- **Conversations and messages**
-- **Contact information and profiles**
-- **Configuration and settings**
-- **Analytics and reporting data**
-
-**Key characteristics:**
-- ACID compliance for data integrity
-- JSON support for flexible schemas
-- Full-text search capabilities
-- Horizontal scaling with read replicas
-
-### 4. Cache and Session Store (Redis)
-
-Redis provides high-performance caching and session management:
-
-- **Session storage** for user authentication
-- **Cache layer** for frequently accessed data
-- **Job queue** for background processing
-- **Real-time data** for WebSocket connections
-- **Rate limiting** and throttling
-
-**Key characteristics:**
-- In-memory performance
-- Persistence options available
-- Pub/Sub for real-time features
-- Clustering support for high availability
-
-### 5. File Storage
-
-Chatwoot supports multiple storage backends:
-
-- **Local filesystem** (development/small deployments)
-- **AWS S3** (recommended for production)
-- **Google Cloud Storage**
-- **Azure Blob Storage**
-- **MinIO** (self-hosted S3-compatible)
-
-**Stored content:**
-- User avatars and profile images
-- Message attachments and files
-- Email templates and assets
-- Exported reports and backups
-
-### 6. Reverse Proxy (Nginx)
-
-Nginx serves as the front-end proxy:
-
-- **SSL termination** and certificate management
-- **Static file serving** for assets
-- **Load balancing** across application instances
-- **Request routing** and filtering
-- **Compression** and caching headers
-
-## Data Flow
-
-### 1. Incoming Messages
-
-```mermaid
-sequenceDiagram
-    participant C as Customer
-    participant W as Widget/Channel
-    participant N as Nginx
-    participant R as Rails App
-    participant D as Database
-    participant Q as Redis Queue
-    participant S as Sidekiq
-    participant A as Agent Dashboard
-    
-    C->>W: Sends message
-    W->>N: HTTP/WebSocket request
-    N->>R: Forward request
-    R->>D: Store message
-    R->>Q: Queue notification job
-    R->>A: Real-time update (WebSocket)
-    Q->>S: Process notification
-    S->>D: Update delivery status
-```
-
-### 2. Agent Responses
-
-```mermaid
-sequenceDiagram
-    participant A as Agent
-    participant D as Dashboard
-    participant R as Rails App
-    participant DB as Database
-    participant Q as Redis Queue
-    participant S as Sidekiq
-    participant C as Customer
-    
-    A->>D: Types response
-    D->>R: Send message API
-    R->>DB: Store message
-    R->>Q: Queue delivery job
-    R->>D: Real-time update
-    Q->>S: Process delivery
-    S->>C: Deliver via channel
-    S->>DB: Update status
-```
-
-## Scaling Considerations
-
-### Horizontal Scaling
-
-Chatwoot is designed for horizontal scaling:
-
-**Web Servers:**
-- Stateless design allows multiple instances
-- Load balancer distributes traffic
-- Session data stored in Redis
-
-**Background Workers:**
-- Multiple Sidekiq processes can run
-- Jobs distributed across workers
-- Queue-based processing prevents overload
-
-**Database:**
-- Read replicas for query scaling
-- Connection pooling for efficiency
-- Partitioning for large datasets
-
-### Vertical Scaling
-
-For smaller deployments, vertical scaling is often sufficient:
-
-**CPU:** Background processing and real-time features
-**Memory:** Caching and session storage
-**Storage:** Database and file storage growth
-**Network:** WebSocket connections and API traffic
-
-## Security Architecture
-
-### Authentication Flow
-
-```mermaid
-graph LR
-    A[User Login] --> B[Rails Auth]
-    B --> C[JWT Token]
-    C --> D[API Requests]
-    D --> E[Token Validation]
-    E --> F[Authorized Access]
-```
-
-### Data Protection
-
-- **Encryption at rest** for sensitive data
-- **TLS encryption** for data in transit
-- **Input validation** and sanitization
-- **SQL injection** protection via ORM
-- **XSS protection** with content security policies
-
-### Access Control
-
-- **Role-based permissions** (Admin, Agent, etc.)
-- **Account-level isolation** in multi-tenant setup
-- **API rate limiting** to prevent abuse
-- **Audit logging** for compliance
-
-## Monitoring and Observability
-
-### Application Metrics
-
-- **Response times** and throughput
-- **Error rates** and exceptions
-- **Background job** processing times
-- **WebSocket connection** counts
-
-### Infrastructure Metrics
-
-- **CPU and memory** utilization
-- **Database performance** and connections
-- **Redis memory** usage and hit rates
-- **Storage usage** and I/O patterns
-
-### Logging Strategy
-
-- **Structured logging** with JSON format
-- **Centralized collection** (ELK, Fluentd)
-- **Log levels** for different environments
-- **Sensitive data** filtering
-
-## Deployment Patterns
-
-### Single Server
-
-Suitable for small teams and development:
-- All components on one server
-- SQLite or PostgreSQL database
-- Local file storage
-- Simple backup strategy
-
-### Multi-Server
-
-For production environments:
-- Separate database server
-- Dedicated Redis instance
-- Load-balanced web servers
-- Shared file storage (S3/NFS)
-
-### Containerized
-
-Using Docker and orchestration:
-- Container images for each component
-- Kubernetes or Docker Swarm
-- Service discovery and networking
-- Rolling updates and health checks
-
-### Cloud-Native
-
-Leveraging cloud services:
-- Managed databases (RDS, Cloud SQL)
-- Managed Redis (ElastiCache, MemoryStore)
-- Object storage (S3, GCS)
-- Load balancers and CDN
-
-## Performance Optimization
-
-### Database Optimization
-
-- **Indexing strategy** for common queries
-- **Connection pooling** to reduce overhead
-- **Query optimization** and monitoring
-- **Read replicas** for scaling reads
-
-### Caching Strategy
-
-- **Application-level caching** for expensive operations
-- **HTTP caching** for static assets
-- **Database query caching** with Redis
-- **CDN caching** for global distribution
-
-### Background Processing
-
-- **Job prioritization** for critical tasks
-- **Batch processing** for bulk operations
-- **Queue monitoring** and alerting
-- **Resource allocation** per job type
-
----
-
-<Note>
-Understanding this architecture helps you make informed decisions about deployment, scaling, and maintenance of your Chatwoot instance.
-</Note> 
+* **[AWS](/self-hosted/cloud/aws)**
+* **[Azure](/self-hosted/cloud/azure)**
+* **[DigitalOcean](/self-hosted/cloud/digitalocean)**
+* **[Google Cloud](/self-hosted/cloud/gcp)**
+* **[Heroku](/self-hosted/cloud/heroku)** 

developer-docs/self-hosted/cloud/aws-marketplace.mdx

@@ -0,0 +1,170 @@
+---
+title: AWS Marketplace AMI Deployment
+description: Deploy Chatwoot on AWS using the marketplace AMI listing
+sidebarTitle: AWS Marketplace
+---
+
+# AWS Chatwoot Deployment Guide
+
+The following is the guide for deploying Chatwoot on AWS using the marketplace listing. Use our helm charts with AWS Elastic Kubernetes Service(EKS) for a cloud-native deployment.
+
+## Prerequisites
+- AWS account
+
+## Install Chatwoot via AWS Marketplace AMI
+
+### Step 1: Subscribe to Chatwoot
+
+1. Go to [Chatwoot AWS marketplace listing](https://aws.amazon.com/marketplace/pp/prodview-tolblk4kmdqd4) and click on **Subscribe**.
+
+![Subscribe to Chatwoot](/self-hosted/images/aws-ami/awsmp-01-subscribe.png)
+
+### Step 2: Sign In
+
+2. Sign in with your AWS account.
+
+![AWS Sign In](/self-hosted/images/aws-ami/awsmp-02-signin.png)
+
+### Step 3: Continue to Configuration
+
+3. Click on **Continue to Configuration**.
+
+![Continue to Configuration](/self-hosted/images/aws-ami/awsmp-03-continue.png)
+
+### Step 4: Configure Software
+
+4. Select the latest version in **Software Version** and pick your AWS **region**. Click **Continue to Launch**.
+
+![Configure Software](/self-hosted/images/aws-ami/awsmp-04-configure.png)
+
+### Step 5: Launch Configuration
+
+5. Review the launch configuration. Leave the **Choose Action** field with the default value **Launch from Website**. Choose a VPC and subnet as per your AWS region preference.
+
+![Launch Configuration](/self-hosted/images/aws-ami/awsmp-05-launch.png)
+
+### Step 6: Create Security Group
+
+6. Scroll down to the **Security Group** section and click **Create New Based On Seller Settings**.
+
+![Create Security Group](/self-hosted/images/aws-ami/awsmp-06-sg.png)
+
+### Step 7: Save Security Group
+
+7. Save the new security group and choose it after creation.
+
+![Save Security Group](/self-hosted/images/aws-ami/awsmp-07-sg.png)
+
+### Step 8: Configure Key Pair
+
+8. Pick a key pair you already have or create a new one in the region you are deploying. Click **Launch**.
+
+![Configure Key Pair](/self-hosted/images/aws-ami/awsmp-08-keypair.png)
+
+### Step 9: Launch Confirmation
+
+9. AWS should now display a congratulations screen confirming that Chatwoot instance is launched successfully. Click on the **EC2 Console** link.
+
+![Launch Confirmation](/self-hosted/images/aws-ami/awsmp-09-launch.png)
+
+### Step 10: Wait for Instance
+
+10. Wait for a few minutes to let the instance come up.
+
+![Wait for Instance](/self-hosted/images/aws-ami/awsmp-10-ec2.png)
+
+### Step 11: Get Public IP
+
+11. Select the instance and copy the public IP.
+
+![Get Public IP](/self-hosted/images/aws-ami/awsmp-11-public-ip.png)
+
+### Step 12: Access Chatwoot
+
+12. Visit `http://<your-public-ip>:3000`. This should bring up the Chatwoot UI. Congratulations. Woot! Woot!!
+
+![Access Chatwoot](/self-hosted/images/aws-ami/awsmp-12-chatwoot.png)
+
+## Configuring Chatwoot
+
+To configure Chatwoot, we need to SSH into the instance. We will use **AWS Console Connect** for this.
+
+### Step 1: Connect to Instance
+
+1. Select the instance and click on **Connect**.
+
+![Connect to Instance](/self-hosted/images/aws-ami/awsmp-13-connect.png)
+
+### Step 2: Use Ubuntu User
+
+2. Change the username from `root` to `ubuntu` and click **Connect**.
+
+![Use Ubuntu User](/self-hosted/images/aws-ami/awsmp-14-connect.png)
+
+### Step 3: Configure Environment Variables
+
+3. Switch to the `chatwoot` user and configure the necessary environment variables. Refer to [Environment variables](/self-hosted/configuration/environment-variables) document for the complete list.
+
+```bash
+sudo -i -u chatwoot
+cd chatwoot
+vi .env
+```
+
+<Note>
+It is recommended to configure a proxy server like Nginx and set up SSL. Make sure to modify the security group created in step 6 accordingly.
+</Note>
+
+## Updating the Instance
+
+Please follow the Chatwoot update process in the standard [Linux VM setup](/self-hosted/deployment/linux-vm).
+
+## Security Recommendations
+
+### SSL Configuration
+- Set up SSL certificates using Let's Encrypt or AWS Certificate Manager
+- Configure Nginx as a reverse proxy
+- Update security group rules to allow HTTPS traffic (port 443)
+
+### Access Control
+- Restrict SSH access to specific IP addresses
+- Use IAM roles for EC2 instances where possible
+- Enable AWS CloudTrail for audit logging
+
+### Backup Strategy
+- Set up automated EBS snapshots
+- Configure database backups
+- Store backups in S3 with appropriate lifecycle policies
+
+## Troubleshooting
+
+### Common Issues
+
+<Accordion title="Instance not accessible">
+**Problem**: Cannot access Chatwoot on port 3000
+
+**Solutions**:
+- Check security group allows inbound traffic on port 3000
+- Verify instance is running and healthy
+- Check if Chatwoot service is running: `sudo systemctl status chatwoot`
+</Accordion>
+
+<Accordion title="Application not starting">
+**Problem**: Chatwoot service fails to start
+
+**Solutions**:
+- Check logs: `sudo journalctl -u chatwoot -f`
+- Verify environment variables are correctly set
+- Ensure database connection is working
+- Check disk space and memory usage
+</Accordion>
+
+### Support Resources
+
+- [AWS Support](https://aws.amazon.com/support/)
+- [Chatwoot Community Discord](https://discord.com/invite/cJXdrwS)
+- [GitHub Issues](https://github.com/chatwoot/chatwoot/issues)
+
+---
+
+The AWS Marketplace AMI provides a quick way to deploy Chatwoot with pre-configured settings. For production use, ensure you implement proper security measures and backup strategies. 

developer-docs/self-hosted/cloud/aws.mdx

@@ -1,501 +1,277 @@
 ---
-title: AWS Deployment
-description: Deploy Chatwoot on Amazon Web Services with manual installation or marketplace AMI
-sidebarTitle: AWS
+title: AWS Chatwoot deployment guide
+description: Deploy Chatwoot on AWS with a reference HA architecture
+sidebarTitle: Manual Install
 ---
 
-# AWS Deployment Guide
+The following is a reference HA architecture guide for deploying Chatwoot on AWS. For a cloud-native deployment, use our [helm charts](https://github.com/chatwoot/charts) with AWS Elastic Kubernetes Service(EKS).
 
-Deploy Chatwoot on Amazon Web Services (AWS) using either manual installation or the AWS Marketplace AMI for a scalable, production-ready setup.
+## Introduction
 
-## Deployment Options
-
-<CardGroup cols={2}>
-  <Card title="Manual Installation" icon="code" href="#manual-installation">
-    Full control over the deployment with custom architecture
-  </Card>
-  <Card title="AWS Marketplace AMI" icon="aws" href="#aws-marketplace-ami">
-    Quick deployment using pre-configured AMI
-  </Card>
-</CardGroup>
-
-## Manual Installation
-
-### Architecture Overview
-
-This guide follows a standard 3-tier architecture on AWS for high availability:
-
-```
-Internet Gateway
-       |
-Application Load Balancer (Public Subnets)
-       |
-Chatwoot Instances (Private Subnets)
-       |
-RDS PostgreSQL + ElastiCache Redis (Private Subnets)
-```
+We will use the Linux installation script to get a chatwoot instance running. Also instead of
+relying on Redis, Postgres and Nginx installed in the same ec2; we will proceed to make use
+of managed AWS services for the same viz Elasticache, RDS, and ALB.
 
 ### Prerequisites
 
-- AWS account with appropriate permissions
-- Domain name for your Chatwoot installation
-- Basic knowledge of AWS services (VPC, EC2, RDS, etc.)
+1. AWS account
+2. Domain to use with Chatwoot
 
-### Step 1: Network Setup
+### Architecture
 
-#### Create VPC
+This guide will follow a standard 3-tier architecture on AWS.
 
-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
+![aws-architecture](/self-hosted/images/aws-01-architecture.png)
 
-#### Create Subnets
+## Network
 
-Create subnets across two availability zones:
+### Create VPC
 
-| 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 |
+1. Sign in to the AWS console and pick the region you will deploy.
+2. Navigate to the VPC console and create a new vpc for chatwoot. At the `name` tag, enter
+   `chatwoot-vpc` and use the CIDR block `10.0.0.0/16`.
+3. Leave the rest of the options as default and click on `Create VPC`.
 
-<Note>
-Enable "Auto-assign public IPv4 address" for public subnets under Actions > Subnet Settings.
-</Note>
+![aws-create-vpc](/self-hosted/images/aws-02-create-vpc.png)
 
-#### Internet Gateway
+### Subnets
+Create two public and private subnets in the vpc we created. Make sure to have them in different AZ's and have non-overlapping CIDR ranges.
 
-1. Create Internet Gateway named `chatwoot-igw`
-2. Attach it to `chatwoot-vpc`
+1. Navigate to VPC > Subnets.
+2. Click on `Create Subnet`. Select the `chatwoot-vpc` we created before, name it as `chatwoot-public-1`, select an availability zone (for example, ap-south-1a), and the CIDR block as
+`10.0.0.0/24`.
 
-#### NAT Gateways
+![aws-create-subnet](/self-hosted/images/aws-03-create-subnet.png)
 
-Create NAT gateways in each public subnet:
+3. Follow the same to create the remaining subnets.
 
-1. **chatwoot-nat-1** in `chatwoot-public-1`
-2. **chatwoot-nat-2** in `chatwoot-public-2`
+| Name                | Type     | Availability Zone  | CIDR Block    |
+| ------------------- | -------- | ------------------ | ------------- |
+| `chatwoot-public-1`  | public  | `ap-south-1a`      | `10.0.0.0/24` |
+| `chatwoot-public-2`  | public  | `ap-south-1b`      | `10.0.1.0/24` |
+| `chatwoot-private-1` | private | `ap-south-1a`      | `10.0.2.0/24` |
+| `chatwoot-private-2` | private | `ap-south-1b`      | `10.0.3.0/24` |
 
-Allocate Elastic IPs for each NAT gateway.
+4. After creating all subnets, enable `auto assign public ipv4 address` for public subnets under `Actions` > `Subnet Settings`.
 
-#### Route Tables
+### Internet Gateway
 
-**Public Route Table** (`chatwoot-public-rt`):
-- Route: `0.0.0.0/0` → `chatwoot-igw`
-- Associate with public subnets
+1. Select  `Create Internet Gateway` , name it `chatwoot-igw`, and click create.
+2. Select it from the internet gateways list, choose actions and then select `Attach to VPC`.
+3. Choose `chatwoot-vpc` and click attach.
 
-**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`
+![aws-create-igw](/self-hosted/images/aws-04-create-igw.png)
 
-### Step 2: Application Load Balancer
+### NAT Gateway
 
-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
+Chatwoot app servers need to be deployed in the private subnet. For them to access the internet, we need to add NAT gateways to our public subnet and add a route from the private subnets.
 
-#### Security Group for ALB
+1. Navigate the VPC dashboard and select `NAT gateways`.
+2. Click `Create NAT Gateway`.
 
-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)
+    1. Name it `chatwoot-nat-1`.
+    2. Select the `chatwoot-public-1` subnet.
+    3. Click on `Allocate Elastic IP`.
+    4. Add additional tags as per your need.
+    5. Click `Create NAT gateway`.
 
-#### Target Group
+![aws-create-nat](/self-hosted/images/aws-05-create-nat.png)
 
-Create `chatwoot-tg` target group:
-- **Target type**: Instances
-- **Protocol**: HTTP
-- **Port**: 3000
-- **Health check path**: `/api`
+3. Follow the same to create a second NAT gateway (`chatwoot-nat-2`) and choose the `chatwoot-public-2` subnet.
 
-### Step 3: Database Setup (RDS)
+### Route tables
 
-#### RDS Security Group
+The route table controls the inbound and outbound access for a subnet.
 
-Create `chatwoot-rds-sg`:
-- PostgreSQL (5432) from `chatwoot-loadbalancer-sg`
+#### Public Route table
 
-#### RDS Subnet Group
+We will create route tables so that our public subnets can reach the internet via the Internet gateway.
 
-Create `chatwoot-rds-group`:
-- **VPC**: `chatwoot-vpc`
-- **Subnets**: Both private subnets
+Navigate to the VPC dashboard and select `Route Tables`.
+1. Click `Create route table`.
+2. Use the name `chatwoot-public-rt` and choose `chatwoot-vpc` under VPC.
+3. Click `Create`.
 
-#### Create RDS Instance
+![aws-create-rt](/self-hosted/images/aws-06-create-rt.png)
 
-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`
+Next, we need to add a route to the internet gateway we created earlier(`chatwoot-igw`).
 
-<Warning>
-Note down the RDS endpoint, username, and password for later configuration.
-</Warning>
+1. Select the `chatwoot-public-rt` route table from the list and click on `Edit routes` > `Add Route`.
+2. Set the destination as `0.0.0.0/0` and choose the target as `chatwoot-igw`. Click on `Save Changes`.
 
-### Step 4: Redis Setup (ElastiCache)
+Also,
 
-#### ElastiCache Security Group
+1. Select the `chatwoot-public-rt` route table from the list and click on `Subnet Associations` > `Edit subnet associations`.
+2. Select both the public subnets(`chatwoot-public-1`,`chatwoot-public-2`) and click `save`.
 
-Create `chatwoot-redis-sg`:
-- Redis (6379) from `chatwoot-loadbalancer-sg`
+#### Private Route table
 
-#### ElastiCache Subnet Group
+We will also create private route tables so that our private subnets can reach the internet via the NAT gateways.
 
-Create `chatwoot-redis-group`:
-- **VPC**: `chatwoot-vpc`
-- **Subnets**: Both private subnets
+1. Follow the above guide and create two private route tables, namely, `chatwoot-private-a` and `chatwoot-private-b`.
+2. Select the route tables and add a route to the NAT gateway in their respective availability zone.
+    1. For `chatwoot-private-a`, add a route to `0.0.0.0/0` and target as `chatwoot-nat-1`.
+    2. For `chatwoot-private-b`, add a route to `0.0.0.0/0` and target as `chatwoot-nat-2`.
 
-#### Create Redis Cluster
+Also,
 
-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`
+1. Associate the private route tables with corresponding private subnets.
+    1. For `chatwoot-private-a`, associate `chatwoot-private-1` subnet.
+    2. For `chatwoot-private-b`, associate `chatwoot-private-2` subnet.
 
-### Step 5: Bastion Host
+## Application Load Balancer (ALB)
 
-Create bastion servers for secure access to private instances:
+Create an application load balancer to receive traffic on port 80 and 443 and distribute it across Chatwoot 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)
+1. Navigate to the EC2 section and choose the Load Balancer section.
+2. Click `Create Load Balancer`.
+    1. Choose `Application Load Balancer`.
+    2. For the load balancer name, use `chatwoot-loadbalancer`.
+    3. Select the scheme as `internet-facing` and IP address type as `IPv4`.
+    4. For the network mapping section,
+       1. Select `chatwoot-vpc`.
+       2. Select the public subnets `chatwoot-public-1` and `chatwoot-public-2` under the mapping section.
+   5. For the Security group section,
+       1. Create a new security group, `chatwoot-loadbalancer-sg`.
+       2. Add rules to allow HTTP and HTTPS traffic from anywhere(`0.0.0.0/0`, `::/0`).
+       3. Also, add a rule to allow TCP on port 3000. This rule allows the load balancer health checks to pass since Chatwoot runs on port 3000.
+       4. Add a rule to allow SSH traffic from the bastion security group we will create at the latter stage of the guide. Revisit this section after completing the bastion step.
+   6. For the Listeners and routing section, create two listeners for 80 and 443. Set the forwarding rule on listener 80 to redirect `http` to `https`.
+       1. Also, create a target group, `chatwoot-tg`, that will forward the requests to port `3000`(Chatwoot listens on this port).
+       2. Add a health check to the endpoint `/api`. This endpoint is not authenticated and should return the application version.
+```
+{
+  "version": "1.22.1",
+  "timestamp": "2021-12-06 16:07:39"
+}
+```
+   7. Add any necessary tags and click create.
 
-### Step 6: Chatwoot Application Servers
+Also, add if you have your domain on Route53 and use ACM to generate a certificate to use with ALB.
 
-#### Launch Chatwoot Instance
+## Postgresql using AWS RDS
 
-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`
+Chatwoot uses Postgres as a DB layer, and we will use Amazon RDS with a multi-AZ option for reliability.
 
-#### Install Chatwoot
+### RDS security group
 
-1. SSH to bastion host, then to Chatwoot instance
-2. Switch to root user and download installation script:
+1. Navigate to EC2 > Security groups and create a new sg.
+2. Name it `chatwoot-rds-sg`.
+3. Select the `chatwoot-vpc` and add an inbound rule for postgres port with source `chatwoot-loadbalancer-sg`.
+
+### RDS subnet group
+
+1. Navigate to the RDS section and select subnet groups.
+2. Create `chatwoot-rds-group` and choose `chatwoot-vpc`.
+3. Select both az's and the private subnets.
+
+### RDS
+
+1. Select create a database.
+2. Use standard create and choose the Postgres engine.
+3. Use the production template, and create a Postgres master username and password.
+4. Enable Multi-AZ deployment.
+5. Select `chatwoot-vpc` and select the rds security group we created earlier.
+6. Enable password authentication.
+7. Click create.
+8. After completing the creation, note down the hostname, username, and password. We will need this to configure Chatwoot.
+
+## Redis using AWS Elasticache
+
+1. Follow similar steps like the rds to create Redis security and subnet groups.
+2. Create the Redis cluster with a multi-AZ option.
+
+## Creating Bastion servers
+
+Create bastion servers in both public subnets. These servers will be used to ssh into Chatwoot servers in private subnets.
+
+1. Navigate to the EC2 dashboard and click launch instance.
+2. Use an `Ubuntu 20.04 image` with a `t3.micro` type.
+3. Choose `chatwoot-vpc` and subnet `chatwoot-public-1`.
+4. Name it `chatwoot-bastion-a`.
+5. Add a new sg, `chatwoot-bastion-sg` and enable ssh access from anywhere.
+6. Leave the rest as defaults and click launch.
+7. Once the instance is up, try to SSH into the instance.
+
+Repeat and create another bastion, `chatwoot-bastion-b` in the other AZ.
+
+## Install Chatwoot
+
+1. Navigate to the EC2 section, and click on launch instance.
+2. Use an `Ubuntu 20.04 image` with a `c5.xlarge` instance type.
+3. Choose the chatwoot-vpc and select the private subnet `chatwoot-private-1`.
+4. Disable auto-assign public IP and increase the storage of root volume to 60 GB.
+5. Add necessary tags. Set the `Name` tag to `chatwoot`.
+6. Select the load balancer security group and click launch.
+7. SSH into the bastion server and, from there, ssh to the chatwoot instance we created.
+8. Switch to the `root` user.
+9. Download the chatwoot Linux installation script.
 
 ```bash
-sudo su -
 wget https://get.chatwoot.app/linux/install.sh
-chmod +x install.sh
+chmod 755 install.sh
+```
+
+10. Run the script.
+
+```bash
 ./install.sh --install
 ```
 
-#### Configure Chatwoot
+## Configure Chatwoot
 
-1. Switch to chatwoot user and edit environment:
+11. Once the installation is complete, switch to the chatwoot user and navigate to the chatwoot folder. Edit the .env file and replace the Postgres and Redis credentials with RDS and elasticache values.
 
 ```bash
 sudo -i -u chatwoot
 cd chatwoot
-nano .env
+vi .env
 ```
 
-2. Update database and Redis configuration:
+12. Run the db migration.
 
 ```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"
+RAILS_ENV=production bundle exec rake db:prepare
 ```
 
-3. Run database preparation:
+13. Also modify the other necessary environment variable for your chatwoot setup. Refer to https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm#configure-the-required-environment-variables
 
-```bash
-RAILS_ENV=production bundle exec rake db:chatwoot_prepare
-```
-
-4. Restart services:
+14. Restart the `chatwoot` service.
 
 ```bash
 sudo cwctl --restart
 ```
 
-### Step 7: SSL Certificate (ACM)
+## Verify login
 
-1. Navigate to Certificate Manager
-2. Request public certificate for your domain
-3. Validate domain ownership
-4. Attach certificate to ALB HTTPS listener
+15. Add this instance to the target group attached to the alb.
+16. Navigate to your chatwoot domain to see if everything is working.
 
-### Step 8: Auto Scaling
+## Create a custom AMI
 
-#### Create AMI
+1. If you are getting the onboarding page, complete the signup and verify the installation.
+2. Voila !! Your chatwoot instance is up.
+3. If everything looks good, proceed to create an ami from this instance and name it `chatwoot-base-ami`.
 
-1. Stop the Chatwoot instance
-2. Create AMI named `chatwoot-base-ami`
-3. Terminate the original instance
+## Auto Scaling Groups (ASG)
 
-#### Launch Template
+1. Create a launch configuration using the above base image.
+2. Proceed to create an auto-scaling group from this launch config.
+3. Set the minimum and desired capacity to 2 and the maximum to 4. Modify this as per your requirement.
+4. Create a scaling policy based on CPU utilization.
+5. At this point, we are good to terminate the instance we created earlier.
+6. Check the load balancer or target group to verify if two new chatwoot instances have come up.
+7. That's it.
 
-Create launch template with:
-- **AMI**: `chatwoot-base-ami`
-- **Instance type**: `c5.xlarge`
-- **Security group**: `chatwoot-loadbalancer-sg`
-- **User data** (optional):
+## Monitoring
 
-```bash
-#!/bin/bash
-sudo cwctl --restart
-```
+1. Refer to https://www.chatwoot.com/docs/self-hosted/monitoring/apm-and-error-monitoring
 
-#### Auto Scaling Group
+## Updating Chatwoot
 
-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
+1. log in to one of the application servers and complete the update instructions. Run migrations if needed. Refer to https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm#upgrading-to-a-newer-version-of-chatwoot
+2. Create a new ami and update the launch config.
 
-#### Scaling Policies
+## Conclusion
 
-Create scaling policies based on:
-- CPU utilization (scale out at 70%, scale in at 30%)
-- Memory utilization
-- Request count per target
-
-## AWS Marketplace AMI
-
-### Quick Deployment
-
-1. Navigate to AWS Marketplace
-2. Search for "Chatwoot"
-3. Subscribe to Chatwoot AMI
-4. Launch instance with recommended settings:
-   - **Instance type**: `t3.medium` or larger
-   - **Storage**: 20 GB minimum
-   - **Security group**: Allow HTTP, HTTPS, and SSH
-
-### Post-Launch Configuration
-
-1. SSH to the instance
-2. Complete initial setup:
-
-```bash
-sudo /opt/chatwoot/setup.sh
-```
-
-3. Configure domain and SSL:
-
-```bash
-sudo /opt/chatwoot/configure-domain.sh yourdomain.com
-```
-
-## Production Optimizations
-
-### Performance Tuning
-
-```bash
-# Optimize Rails configuration
-export RAILS_MAX_THREADS=20
-export WEB_CONCURRENCY=4
-export SIDEKIQ_CONCURRENCY=25
-
-# Database connection pooling
-export DATABASE_POOL_SIZE=25
-```
-
-### Monitoring Setup
-
-#### CloudWatch Metrics
-
-Enable detailed monitoring for:
-- EC2 instances
-- RDS database
-- ElastiCache cluster
-- Application Load Balancer
-
-#### Custom Metrics
-
-```bash
-# Install CloudWatch agent
-wget https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm
-sudo rpm -U ./amazon-cloudwatch-agent.rpm
-
-# Configure custom metrics
-sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard
-```
-
-### Backup Strategy
-
-#### RDS Automated Backups
-
-- Enable automated backups with 7-day retention
-- Configure backup window during low-traffic hours
-- Enable point-in-time recovery
-
-#### Application Data Backup
-
-```bash
-#!/bin/bash
-# Backup script for application data
-DATE=$(date +%Y%m%d_%H%M%S)
-
-# Database backup
-pg_dump $DATABASE_URL | gzip > "s3://your-backup-bucket/db/chatwoot_$DATE.sql.gz"
-
-# File uploads backup (if using local storage)
-aws s3 sync /home/chatwoot/chatwoot/storage s3://your-backup-bucket/storage/
-```
-
-### Security Hardening
-
-#### IAM Roles
-
-Create IAM roles with minimal permissions:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "s3:GetObject",
-        "s3:PutObject",
-        "s3:DeleteObject"
-      ],
-      "Resource": "arn:aws:s3:::your-chatwoot-bucket/*"
-    },
-    {
-      "Effect": "Allow",
-      "Action": [
-        "ses:SendEmail",
-        "ses:SendRawEmail"
-      ],
-      "Resource": "*"
-    }
-  ]
-}
-```
-
-#### Security Groups
-
-Implement least-privilege access:
-- ALB: Only HTTP/HTTPS from internet
-- App servers: Only from ALB and bastion
-- Database: Only from app servers
-- Redis: Only from app servers
-
-## Cost Optimization
-
-### Reserved Instances
-
-Purchase Reserved Instances for:
-- RDS database instances
-- ElastiCache clusters
-- Predictable EC2 workloads
-
-### Spot Instances
-
-Use Spot Instances for:
-- Development environments
-- Non-critical worker processes
-- Batch processing tasks
-
-### Storage Optimization
-
-- Use GP3 volumes for better price/performance
-- Implement S3 lifecycle policies for old backups
-- Use S3 Intelligent Tiering for file storage
-
-## Troubleshooting
-
-### Common Issues
-
-<Accordion title="Application not accessible">
-Check:
-- Security group rules
-- Target group health
-- Route table configuration
-- DNS resolution
-</Accordion>
-
-<Accordion title="Database connection errors">
-Verify:
-- RDS security group allows connections
-- Database credentials in .env file
-- Network connectivity from app servers
-</Accordion>
-
-<Accordion title="High memory usage">
-Solutions:
-- Increase instance size
-- Optimize Sidekiq concurrency
-- Enable swap memory
-- Monitor for memory leaks
-</Accordion>
-
-### Monitoring Commands
-
-```bash
-# Check application health
-curl -I http://localhost:3000/api
-
-# Monitor system resources
-htop
-iostat -x 1
-free -h
-
-# Check service status
-sudo systemctl status chatwoot.target
-```
-
----
-
-This AWS deployment guide provides a comprehensive approach to hosting Chatwoot on AWS infrastructure. Choose the deployment method that best fits your requirements and scale as needed. 
+This document is a reference guideline for an HA chatwoot architecture on AWS. Modify or build upon this to suit your requirements. 

developer-docs/self-hosted/cloud/azure.mdx

@@ -1,663 +1,41 @@
 ---
-title: Azure Deployment
-description: Deploy Chatwoot on Microsoft Azure with various deployment options
+title: Azure Chatwoot deployment guide
+description: Deploy Chatwoot on a single VM in Azure
 sidebarTitle: Azure
 ---
 
-# Azure Deployment Guide
+This guide will deploy chatwoot on a single VM in Azure. For a cloud native deployment, use our [helm charts](https://github.com/chatwoot/charts) with Azure Kubernetes Service(AKS).
 
-Deploy Chatwoot on Microsoft Azure using various deployment options including Virtual Machines, Container Instances, or App Service for a scalable, production-ready setup.
+<Note>
+This guide is a work in progress and your mileage may vary.
+</Note>
 
-## Deployment Options
+## Create a Virtual Machine
 
-<CardGroup cols={3}>
-  <Card title="Virtual Machines" icon="server" href="#virtual-machines">
-    Full control with custom VM deployment
-  </Card>
-  <Card title="Container Instances" icon="docker" href="#container-instances">
-    Serverless container deployment
-  </Card>
-  <Card title="App Service" icon="cloud" href="#app-service">
-    Platform-as-a-Service deployment
-  </Card>
-</CardGroup>
+1. Login to the Azure portal and choose Virtual Machines.
+2. Select create a VM from scratch.
+3. In the Basics tab, create a subscription and a new resource group.
+4. Name the virtual machine as `chatwoot` and select your preferred region.
+5. Select `Ubuntu 20.04 LTS - Gen2` as the image.
+6. For instance size, we recommend the type `Standard_D4s_v3`(4vCPU, 16GB RAM).
+7. Under authentication, leave the defaults and create a new key pair if needed.
+8. Allow HTTP, HTTPS and SSH under inbound port rules.
+9. Click next and leave the defaults for Disks, Networking, Management, Advanced and Tags section.
+10. Select `Review + create` to spin up the VM.
 
-## Virtual Machines Deployment
+![azure-create-vm](/self-hosted/images/azure.png)
 
-### Architecture Overview
+## Install Chatwoot
 
-```
-Azure Load Balancer
-       |
-Virtual Machines (Availability Set)
-       |
-Azure Database for PostgreSQL + Azure Cache for Redis
-```
+1. SSH into the instance created from your local machine or create a bastion in azure to ssh via the browser.
+2. Follow the linux VM instructions at https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm.
+3. Woot! Woot! Your Chatwoot Instance is ready and can be accessed at `http://<your-instance-ip>:3000`. Or if you completed the domain setup during the installation, chatwoot should be available at `https://<your-domain>`.
 
-### Prerequisites
+<Note>
+Browser access via port 3000 will only work if enabled under inbound rules.
+</Note>
 
-- Azure subscription with appropriate permissions
-- Azure CLI installed and configured
-- Domain name for your Chatwoot installation
+## Configure Chatwoot
 
-### Step 1: Resource Group and Network
-
-#### Create Resource Group
-
-```bash
-# Create resource group
-az group create \
-  --name chatwoot-rg \
-  --location eastus
-```
-
-#### Create Virtual Network
-
-```bash
-# Create virtual network
-az network vnet create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-vnet \
-  --address-prefix 10.0.0.0/16 \
-  --subnet-name chatwoot-subnet \
-  --subnet-prefix 10.0.1.0/24
-```
-
-#### Create Network Security Group
-
-```bash
-# Create NSG
-az network nsg create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-nsg
-
-# Add rules
-az network nsg rule create \
-  --resource-group chatwoot-rg \
-  --nsg-name chatwoot-nsg \
-  --name AllowHTTP \
-  --protocol tcp \
-  --priority 1000 \
-  --destination-port-range 80
-
-az network nsg rule create \
-  --resource-group chatwoot-rg \
-  --nsg-name chatwoot-nsg \
-  --name AllowHTTPS \
-  --protocol tcp \
-  --priority 1001 \
-  --destination-port-range 443
-
-az network nsg rule create \
-  --resource-group chatwoot-rg \
-  --nsg-name chatwoot-nsg \
-  --name AllowSSH \
-  --protocol tcp \
-  --priority 1002 \
-  --destination-port-range 22 \
-  --source-address-prefix "YOUR_IP_ADDRESS"
-```
-
-### Step 2: Database Setup
-
-#### Create PostgreSQL Server
-
-```bash
-# Create PostgreSQL server
-az postgres server create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-postgres \
-  --location eastus \
-  --admin-user chatwoot \
-  --admin-password "YourSecurePassword123!" \
-  --sku-name GP_Gen5_2 \
-  --version 13
-
-# Create database
-az postgres db create \
-  --resource-group chatwoot-rg \
-  --server-name chatwoot-postgres \
-  --name chatwoot_production
-
-# Configure firewall
-az postgres server firewall-rule create \
-  --resource-group chatwoot-rg \
-  --server chatwoot-postgres \
-  --name AllowAzureServices \
-  --start-ip-address 0.0.0.0 \
-  --end-ip-address 0.0.0.0
-```
-
-#### Create Redis Cache
-
-```bash
-# Create Redis cache
-az redis create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-redis \
-  --location eastus \
-  --sku Basic \
-  --vm-size c0
-```
-
-### Step 3: Storage Account
-
-```bash
-# Create storage account
-az storage account create \
-  --resource-group chatwoot-rg \
-  --name chatwootstorage \
-  --location eastus \
-  --sku Standard_LRS
-
-# Create container for file uploads
-az storage container create \
-  --account-name chatwootstorage \
-  --name uploads \
-  --public-access blob
-```
-
-### Step 4: Virtual Machine
-
-#### Create Availability Set
-
-```bash
-# Create availability set
-az vm availability-set create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-avset \
-  --platform-fault-domain-count 2 \
-  --platform-update-domain-count 2
-```
-
-#### Create Virtual Machine
-
-```bash
-# Create VM
-az vm create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-vm \
-  --image UbuntuLTS \
-  --size Standard_D2s_v3 \
-  --availability-set chatwoot-avset \
-  --vnet-name chatwoot-vnet \
-  --subnet chatwoot-subnet \
-  --nsg chatwoot-nsg \
-  --admin-username azureuser \
-  --generate-ssh-keys \
-  --custom-data cloud-init.txt
-```
-
-#### Cloud-Init Configuration
-
-Create `cloud-init.txt`:
-
-```yaml
-#cloud-config
-package_upgrade: true
-packages:
-  - curl
-  - wget
-  - git
-
-runcmd:
-  - wget https://get.chatwoot.app/linux/install.sh
-  - chmod +x install.sh
-  - ./install.sh --install
-```
-
-### Step 5: Load Balancer
-
-```bash
-# Create public IP
-az network public-ip create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-lb-ip \
-  --sku Standard
-
-# Create load balancer
-az network lb create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-lb \
-  --public-ip-address chatwoot-lb-ip \
-  --frontend-ip-name chatwoot-frontend \
-  --backend-pool-name chatwoot-backend
-
-# Create health probe
-az network lb probe create \
-  --resource-group chatwoot-rg \
-  --lb-name chatwoot-lb \
-  --name chatwoot-health \
-  --protocol http \
-  --port 3000 \
-  --path /api
-
-# Create load balancing rule
-az network lb rule create \
-  --resource-group chatwoot-rg \
-  --lb-name chatwoot-lb \
-  --name chatwoot-rule \
-  --protocol tcp \
-  --frontend-port 80 \
-  --backend-port 3000 \
-  --frontend-ip-name chatwoot-frontend \
-  --backend-pool-name chatwoot-backend \
-  --probe-name chatwoot-health
-```
-
-### Step 6: Configuration
-
-SSH to the VM and configure Chatwoot:
-
-```bash
-# SSH to VM
-ssh azureuser@<VM_PUBLIC_IP>
-
-# Switch to chatwoot user
-sudo -i -u chatwoot
-cd chatwoot
-
-# Edit environment variables
-nano .env
-```
-
-Update `.env` with Azure services:
-
-```bash
-# Database
-DATABASE_URL="postgresql://chatwoot:YourSecurePassword123!@chatwoot-postgres.postgres.database.azure.com:5432/chatwoot_production"
-
-# Redis
-REDIS_URL="redis://:PRIMARY_ACCESS_KEY@chatwoot-redis.redis.cache.windows.net:6380/0?ssl=true"
-
-# Storage (Azure Blob)
-ACTIVE_STORAGE_SERVICE="azure"
-AZURE_STORAGE_ACCOUNT_NAME="chatwootstorage"
-AZURE_STORAGE_ACCESS_KEY="your-access-key"
-AZURE_STORAGE_CONTAINER="uploads"
-
-# Frontend URL
-FRONTEND_URL="https://chatwoot.yourdomain.com"
-FORCE_SSL=true
-```
-
-## Container Instances Deployment
-
-### Docker Compose for Azure
-
-Create `docker-compose.azure.yml`:
-
-```yaml
-version: '3.8'
-
-services:
-  chatwoot-web:
-    image: chatwoot/chatwoot:latest
-    environment:
-      - RAILS_ENV=production
-      - DATABASE_URL=postgresql://chatwoot:password@postgres:5432/chatwoot_production
-      - REDIS_URL=redis://redis:6379/0
-      - FRONTEND_URL=https://chatwoot.yourdomain.com
-      - FORCE_SSL=true
-    ports:
-      - "3000:3000"
-    depends_on:
-      - postgres
-      - redis
-
-  chatwoot-worker:
-    image: chatwoot/chatwoot:latest
-    environment:
-      - RAILS_ENV=production
-      - DATABASE_URL=postgresql://chatwoot:password@postgres:5432/chatwoot_production
-      - REDIS_URL=redis://redis:6379/0
-    command: bundle exec sidekiq -C config/sidekiq.yml
-    depends_on:
-      - postgres
-      - redis
-
-  postgres:
-    image: postgres:13
-    environment:
-      - POSTGRES_DB=chatwoot_production
-      - POSTGRES_USER=chatwoot
-      - POSTGRES_PASSWORD=password
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-
-  redis:
-    image: redis:7-alpine
-    volumes:
-      - redis_data:/data
-
-volumes:
-  postgres_data:
-  redis_data:
-```
-
-### Deploy with Azure Container Instances
-
-```bash
-# Create container group
-az container create \
-  --resource-group chatwoot-rg \
-  --file docker-compose.azure.yml \
-  --dns-name-label chatwoot-app \
-  --ports 3000
-```
-
-## App Service Deployment
-
-### Create App Service Plan
-
-```bash
-# Create App Service plan
-az appservice plan create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-plan \
-  --sku P1V2 \
-  --is-linux
-
-# Create web app
-az webapp create \
-  --resource-group chatwoot-rg \
-  --plan chatwoot-plan \
-  --name chatwoot-app \
-  --deployment-container-image-name chatwoot/chatwoot:latest
-```
-
-### Configure App Settings
-
-```bash
-# Set environment variables
-az webapp config appsettings set \
-  --resource-group chatwoot-rg \
-  --name chatwoot-app \
-  --settings \
-    RAILS_ENV=production \
-    DATABASE_URL="postgresql://chatwoot:password@chatwoot-postgres.postgres.database.azure.com:5432/chatwoot_production" \
-    REDIS_URL="redis://:key@chatwoot-redis.redis.cache.windows.net:6380/0?ssl=true" \
-    FRONTEND_URL="https://chatwoot-app.azurewebsites.net" \
-    FORCE_SSL=true
-```
-
-## Monitoring and Logging
-
-### Application Insights
-
-```bash
-# Create Application Insights
-az monitor app-insights component create \
-  --resource-group chatwoot-rg \
-  --app chatwoot-insights \
-  --location eastus \
-  --kind web
-
-# Get instrumentation key
-az monitor app-insights component show \
-  --resource-group chatwoot-rg \
-  --app chatwoot-insights \
-  --query instrumentationKey
-```
-
-### Log Analytics Workspace
-
-```bash
-# Create Log Analytics workspace
-az monitor log-analytics workspace create \
-  --resource-group chatwoot-rg \
-  --workspace-name chatwoot-logs \
-  --location eastus
-```
-
-## Security Configuration
-
-### Key Vault for Secrets
-
-```bash
-# Create Key Vault
-az keyvault create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-vault \
-  --location eastus
-
-# Store secrets
-az keyvault secret set \
-  --vault-name chatwoot-vault \
-  --name database-password \
-  --value "YourSecurePassword123!"
-
-az keyvault secret set \
-  --vault-name chatwoot-vault \
-  --name redis-key \
-  --value "your-redis-access-key"
-```
-
-### Managed Identity
-
-```bash
-# Enable managed identity for VM
-az vm identity assign \
-  --resource-group chatwoot-rg \
-  --name chatwoot-vm
-
-# Grant access to Key Vault
-az keyvault set-policy \
-  --name chatwoot-vault \
-  --object-id <MANAGED_IDENTITY_PRINCIPAL_ID> \
-  --secret-permissions get list
-```
-
-## Backup and Disaster Recovery
-
-### Database Backup
-
-```bash
-# Enable automated backup for PostgreSQL
-az postgres server configuration set \
-  --resource-group chatwoot-rg \
-  --server-name chatwoot-postgres \
-  --name backup_retention_days \
-  --value 7
-
-# Create manual backup
-az postgres server backup create \
-  --resource-group chatwoot-rg \
-  --server-name chatwoot-postgres \
-  --backup-name manual-backup-$(date +%Y%m%d)
-```
-
-### VM Backup
-
-```bash
-# Create Recovery Services vault
-az backup vault create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-vault \
-  --location eastus
-
-# Enable backup for VM
-az backup protection enable-for-vm \
-  --resource-group chatwoot-rg \
-  --vault-name chatwoot-vault \
-  --vm chatwoot-vm \
-  --policy-name DefaultPolicy
-```
-
-## Scaling and Performance
-
-### VM Scale Sets
-
-```bash
-# Create VM scale set
-az vmss create \
-  --resource-group chatwoot-rg \
-  --name chatwoot-vmss \
-  --image UbuntuLTS \
-  --vm-sku Standard_D2s_v3 \
-  --instance-count 2 \
-  --vnet-name chatwoot-vnet \
-  --subnet chatwoot-subnet \
-  --lb chatwoot-lb \
-  --backend-pool-name chatwoot-backend \
-  --custom-data cloud-init.txt
-
-# Configure autoscaling
-az monitor autoscale create \
-  --resource-group chatwoot-rg \
-  --resource chatwoot-vmss \
-  --resource-type Microsoft.Compute/virtualMachineScaleSets \
-  --name chatwoot-autoscale \
-  --min-count 2 \
-  --max-count 5 \
-  --count 2
-
-# Add scale-out rule
-az monitor autoscale rule create \
-  --resource-group chatwoot-rg \
-  --autoscale-name chatwoot-autoscale \
-  --condition "Percentage CPU > 70 avg 5m" \
-  --scale out 1
-
-# Add scale-in rule
-az monitor autoscale rule create \
-  --resource-group chatwoot-rg \
-  --autoscale-name chatwoot-autoscale \
-  --condition "Percentage CPU < 30 avg 5m" \
-  --scale in 1
-```
-
-## SSL Certificate
-
-### App Service Certificate
-
-```bash
-# Create App Service certificate
-az webapp config ssl upload \
-  --resource-group chatwoot-rg \
-  --name chatwoot-app \
-  --certificate-file certificate.pfx \
-  --certificate-password "certificate-password"
-
-# Bind certificate to domain
-az webapp config ssl bind \
-  --resource-group chatwoot-rg \
-  --name chatwoot-app \
-  --certificate-thumbprint <THUMBPRINT> \
-  --ssl-type SNI
-```
-
-### Let's Encrypt with VM
-
-```bash
-# Install Certbot on VM
-sudo apt update
-sudo apt install certbot python3-certbot-nginx
-
-# Obtain certificate
-sudo certbot --nginx -d chatwoot.yourdomain.com
-
-# Auto-renewal
-sudo crontab -e
-# Add: 0 12 * * * /usr/bin/certbot renew --quiet
-```
-
-## Cost Optimization
-
-### Reserved Instances
-
-```bash
-# Purchase reserved capacity for VMs
-az reservations reservation-order purchase \
-  --reservation-order-id <ORDER_ID> \
-  --sku Standard_D2s_v3 \
-  --location eastus \
-  --quantity 2 \
-  --term P1Y
-```
-
-### Azure Advisor
-
-```bash
-# Get cost recommendations
-az advisor recommendation list \
-  --category Cost \
-  --resource-group chatwoot-rg
-```
-
-## Troubleshooting
-
-### Common Issues
-
-<Accordion title="Database connection timeout">
-Check:
-- PostgreSQL firewall rules
-- Network security group rules
-- Connection string format
-- SSL requirements for Azure Database
-</Accordion>
-
-<Accordion title="Redis connection issues">
-Verify:
-- Redis access keys
-- SSL configuration (required for Azure Cache)
-- Network connectivity
-- Port 6380 (SSL) vs 6379 (non-SSL)
-</Accordion>
-
-<Accordion title="Storage upload failures">
-Solutions:
-- Verify storage account access keys
-- Check container permissions
-- Ensure CORS settings if needed
-- Validate Azure Storage configuration
-</Accordion>
-
-### Diagnostic Commands
-
-```bash
-# Check VM status
-az vm get-instance-view \
-  --resource-group chatwoot-rg \
-  --name chatwoot-vm
-
-# View application logs
-az webapp log tail \
-  --resource-group chatwoot-rg \
-  --name chatwoot-app
-
-# Check database connectivity
-az postgres server show \
-  --resource-group chatwoot-rg \
-  --name chatwoot-postgres
-```
-
-## Best Practices
-
-### Security
-- Use Azure Key Vault for secrets management
-- Enable managed identities for Azure resources
-- Implement network security groups with least privilege
-- Enable Azure Security Center recommendations
-
-### Performance
-- Use Azure CDN for static assets
-- Implement Redis caching strategies
-- Monitor with Application Insights
-- Use proximity placement groups for low latency
-
-### Cost Management
-- Use Azure Cost Management for monitoring
-- Implement auto-shutdown for development VMs
-- Consider spot instances for non-critical workloads
-- Use reserved instances for predictable workloads
-
-### Backup and Recovery
-- Enable automated backups for all data services
-- Test backup restoration procedures regularly
-- Implement geo-redundant storage for critical data
-- Document disaster recovery procedures
-
----
-
-This Azure deployment guide provides multiple options for hosting Chatwoot on Microsoft Azure. Choose the deployment method that best fits your requirements, budget, and operational preferences. 
+1. Follow the Chatwoot docs to configure your domain, email and other parameters you need.
+https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm#configure-the-required-environment-variables 

developer-docs/self-hosted/cloud/caprover.mdx

@@ -0,0 +1,106 @@
+---
+title: Caprover Chatwoot Production deployment guide
+description: Deploy Chatwoot using Caprover's one-click application management
+sidebarTitle: Caprover
+---
+
+## Caprover Overview
+
+Caprover is an extremely easy to use application server management tool. It is blazing fast and uses Docker under the hood. Chatwoot has been made available as a one-click app in Caprover, and the deployment process is straightforward.
+
+<Note>
+This is a community contributed installation setup. This will only have community support for any issues in future.
+</Note>
+
+## Setup Chatwoot Using Caprover
+
+### 1. Install Caprover on your VM
+
+Finish your Caprover installation by referring to [Getting started guide](https://caprover.com/docs/get-started.html).
+
+### 2. Install Chatwoot
+
+Chatwoot is available in the one-click apps option in Caprover. Search for Chatwoot in the list of one-click apps. Replace the default `version` with the latest `version` of chatwoot. Use appropriate values for the Postgres and Redis passwords and click install. It should only take a few minutes.
+
+### 3. Finish the setup
+
+Head over to the `web` service in the Caprover applications and enable `Websocket Support` in the HTTP settings to true. You could also enable `https` for the application.
+
+![caprover-enable-websocket](/self-hosted/images/caprover-websocket.png)
+
+### 4. Configure environment variables
+
+Caprover will take care of Postgres and Redis installation, along with the app and worker servers. We would advise you to replace the Database/Redis services with managed/standalone servers once you start scaling.
+
+Also, ensure to set the appropriate environment variables for email, Object Store service etc. using our [Environment variables guide](/docs/self-hosted/configuration/environment-variables)
+
+<Note>
+Chatwoot requires websocket support. Do enable it from `chatwoot-web` settings page in Caprover.
+</Note>
+
+## Upgrading Chatwoot installation
+
+To update your chatwoot installation to the latest version in Caprover, run the following command in the deployment tab for web and worker in `method 5: deploy captain-definition`. Make sure to replace `[DESIRED VERSION HERE]` with the current latest stable version. Check [here](https://www.chatwoot.com/changelog/) and [here](https://hub.docker.com/r/chatwoot/chatwoot/tags) for possible version numbers first.
+
+### web
+
+```json
+{
+  "schemaVersion": 2,
+  "dockerfileLines": [
+    "FROM chatwoot/chatwoot:[DESIRED VERSION HERE]",
+    "RUN chmod +x docker/entrypoints/rails.sh",
+    "ENTRYPOINT [\"docker/entrypoints/rails.sh\"]",
+    "CMD bundle exec rake db:chatwoot_prepare; bundle exec rails s -b 0.0.0.0 -p 3000"
+  ]
+}
+```
+
+### worker
+
+```json
+{
+  "schemaVersion": 2,
+  "dockerfileLines": [
+    "FROM chatwoot/chatwoot:[DESIRED VERSION HERE]",
+    "RUN chmod +x docker/entrypoints/rails.sh",
+    "ENTRYPOINT [\"docker/entrypoints/rails.sh\"]",
+    "CMD bundle exec sidekiq -C config/sidekiq.yml"
+  ]
+}
+```
+
+## Accessing Rails Console
+
+Login to the server where you have caprover installed and execute the following commands.
+
+```bash
+# access the shell inside the container
+docker exec -it $(docker ps --filter name=srv-captain--chatwoot-web -q) /bin/sh
+# start rails console
+RAILS_ENV=production bundle exec rails c
+```
+
+## Common Errors
+
+### API requests failing with "You need to sign in or sign up before continuing."
+
+Nginx by default strip of headers with `_` . Head over to the Nginx configuration option in caprover under the Chatwoot web and add the following directive.
+
+Access the Caprover `web dashboard` > `Apps` > `Apps Edit` > `Edit Default Nginx Configurations`. Refer https://caprover.com/docs/nginx-customization.html for more details.
+
+```nginx
+# Nginx strips out underscore in headers by default
+# Chatwoot relies on underscore in headers for API
+# Make sure that the config is set to on.
+underscores_in_headers on;
+```
+
+### Issues related to storage persistance
+
+Please setup a cloud storage like s3 or gcs bucket or any s3 api compatible service as the active storage service.
+Caprover installation needs this for storage persistance. Refer the [storage guide](/docs/self-hosted/deployment/storage/supported-providers).
+
+## Further references
+
+- https://isotropic.co/how-to-install-chatwoot-to-a-digitalocean-droplet/ 

developer-docs/self-hosted/cloud/clevercloud.mdx

@@ -0,0 +1,75 @@
+---
+title: Deploy Chatwoot to Clever Cloud
+description: Deploy Chatwoot on Clever Cloud PaaS platform
+sidebarTitle: Clever Cloud
+---
+
+Clever Cloud is a PaaS platform where you can deploy your applications with ease. To setup Chatwoot on Clever Cloud, you can follow the steps described below.
+
+<Note>
+This is a community contributed installation setup. This will only have community support for any issues in future.
+</Note>
+
+## 1. Create CleverCloud application
+
+- Login to Clever Cloud dashboard
+- Click on create an application
+- Select your deployment type (> 2GB recommended)
+- Provide an app name and select the zone
+
+## 2. Select addons
+
+Chatwoot requires PostgreSQL and Redis to function properly. Select Postgres and Redis from CleverCloud addons.
+
+- Copy connection URI from Postgres Addon and set `DATABASE_URL` environment variable
+- Make sure you have set REDIS_URL
+
+## 3. Setup Clever cloud origin
+
+- Clone Chatwoot project from Github
+
+```bash
+git clone git@github.com:chatwoot/chatwoot.git
+```
+
+- Set Clever Cloud origin
+
+```bash
+git remote add clever git+ssh://git@<id>.clever-cloud.com/<app-name>.git
+```
+
+## 4. Setup build hooks
+
+To install the dependencies, you have to setup builds hooks. Set the following in the environment variables of the application.
+
+```bash
+CC_POST_BUILD_HOOK="RAILS_ENV=production rails assets:precompile"
+CC_PRE_BUILD_HOOK="pnpm install"
+CC_PRE_RUN_HOOK="rake db:chatwoot_prepare"
+```
+
+## 5. Push the latest changes
+
+Push the latest code from your local machine to Clever Cloud.
+
+```bash
+git push clever master
+```
+
+Voila! After the deployment, you would be able to access the application.
+
+## Environment Variables
+
+Make sure you have the following environment variables configured in the application.
+
+```bash
+CC_POST_BUILD_HOOK="RAILS_ENV=production rails assets:precompile"
+CC_PRE_BUILD_HOOK="pnpm install"
+CC_PRE_RUN_HOOK="rake db:chatwoot_prepare"
+DATABASE_URL="<postgres-addon-url>"
+FRONTEND_URL="<clever-cloud-app-url>"
+PORT="8080"
+RAILS_ENV="production"
+REDIS_URL="<redis-addon-url>"
+SECRET_KEY_BASE="<long-secret-key>"
+``` 

developer-docs/self-hosted/cloud/cloudron.mdx

@@ -0,0 +1,41 @@
+---
+title: Cloudron Chatwoot deployment guide
+description: Deploy Chatwoot using Cloudron's 1-click app platform
+sidebarTitle: Cloudron
+---
+
+## Cloudron Overview
+
+[Cloudron](https://cloudron.io) is a platform that makes it easy to install, manage and secure web apps on your server. Chatwoot is now available as a 1-click app in the Cloudron app store and the installation is blazing fast.
+
+<Note>
+This is a community contributed installation setup. This will only have community support for any issues in future.
+</Note>
+
+## Setup Chatwoot using Cloudron
+
+### 1. Install Cloudron on your server
+
+Finish your Cloudron installation by following the instructions at [Get Cloudron](https://www.cloudron.io/get.html).
+
+### 2. Install Chatwoot
+
+Once Cloudron installation is complete, login to your cloudron web portal and click on the appstore icon. Search for `Chatwoot` and click install. That's it. Chatwoot should be up and running in a minute or two.
+
+Direct link to the cloudron app store listing --> https://www.cloudron.io/store/com.chatwoot.cloudronapp.html
+
+### 3. Finish the setup
+
+Navigate to your chatwoot domain and complete the onboarding setup.
+
+### 4. Configure environment variables
+
+Cloudron will take care of Postgres and Redis installation, along with the app and worker processes. We would advise you to replace the Database/Redis services with managed/standalone servers once you start scaling.
+
+Also, ensure to set the appropriate environment variables for email, Object Store service etc. using our [Environment variables guide](/docs/self-hosted/configuration/environment-variables).
+
+Custom environment variables can be set in `/app/data/env` using the Cloudron File manager. Be sure to reboot the app after making any changes.
+
+## Upgrading Chatwoot installation
+
+Chatwoot follows a monthly release pattern with a new release every 15th of the month. Use the built in [Cloudron app updates](https://docs.cloudron.io/updates/) to stay on the latest version. Read about the changelog [here](https://www.chatwoot.com/changelog/). 

developer-docs/self-hosted/cloud/digitalocean.mdx

@@ -1,670 +1,31 @@
 ---
-title: DigitalOcean Deployment
-description: Deploy Chatwoot on DigitalOcean with Droplets, App Platform, or Kubernetes
+title: DigitalOcean Chatwoot deployment guide
+description: Deploy Chatwoot on a single droplet in DigitalOcean
 sidebarTitle: DigitalOcean
 ---
 
-# DigitalOcean Deployment Guide
+This guide will deploy chatwoot on a single droplet in DigitalOcean. For a cloud native deployment, go with
+our [1-click k8s app on DigitalOcean Marketplace](https://marketplace.digitalocean.com/apps/chatwoot).
 
-Deploy Chatwoot on DigitalOcean using Droplets, App Platform, or DigitalOcean Kubernetes for a scalable, cost-effective solution.
+## Create a Droplet (VM)
 
-## Deployment Options
+1. Login to DigitalOcean console and choose create droplet.
+2. Choose `Ubuntu 20.04` image.
+3. Create an instance with a minimum of 4vCPU and 8GB RAM.
+4. Make sure to choose the datacenter region you want to deploy.
+5. Under authentication, choose your SSH key or create a new one. This is important as you will need
+   this key to complete the next section.
+6. Click create.
 
-<CardGroup cols={3}>
-  <Card title="Droplets" icon="server" href="#droplets-deployment">
-    Traditional VPS deployment with full control
-  </Card>
-  <Card title="App Platform" icon="cloud" href="#app-platform">
-    Platform-as-a-Service deployment
-  </Card>
-  <Card title="Kubernetes" icon="kubernetes" href="#kubernetes-deployment">
-    Container orchestration with DOKS
-  </Card>
-</CardGroup>
+![do-create-droplet](/self-hosted/images/do.png)
 
-## Droplets Deployment
+## Install Chatwoot
 
-### Quick Start with One-Click Install
+1. SSH into the droplet created above.
+2. Follow the linux VM instructions at https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm.
+3. Woot! Woot! Your Chatwoot Instance is ready and can be accessed at `http://<your-droplet-ip>:3000`.  Or if you completed the domain setup during the installation, chatwoot should be available at `https://<your-domain>`
 
-DigitalOcean offers a one-click Chatwoot installation from the Marketplace:
+## Configure Chatwoot
 
-1. **Navigate to DigitalOcean Marketplace**
-2. **Search for "Chatwoot"**
-3. **Click "Create Chatwoot Droplet"**
-4. **Configure your Droplet:**
-   - **Plan**: Basic ($12/month minimum recommended)
-   - **CPU options**: Regular Intel
-   - **Region**: Choose closest to your users
-   - **Authentication**: SSH keys (recommended)
-   - **Hostname**: chatwoot-production
-
-5. **Access your installation:**
-   ```bash
-   ssh root@your-droplet-ip
-   ```
-
-### Manual Installation
-
-#### Create Droplet
-
-```bash
-# Using doctl CLI
-doctl compute droplet create chatwoot-prod \
-  --image ubuntu-20-04-x64 \
-  --size s-2vcpu-4gb \
-  --region nyc3 \
-  --ssh-keys your-ssh-key-id \
-  --enable-monitoring \
-  --enable-ipv6
-```
-
-#### Install Chatwoot
-
-```bash
-# SSH to droplet
-ssh root@your-droplet-ip
-
-# Download and run installation script
-wget https://get.chatwoot.app/linux/install.sh
-chmod +x install.sh
-./install.sh --install
-```
-
-### Database Setup
-
-#### Managed PostgreSQL
-
-```bash
-# Create managed database cluster
-doctl databases create chatwoot-db \
-  --engine postgres \
-  --version 13 \
-  --size db-s-1vcpu-1gb \
-  --region nyc3 \
-  --num-nodes 1
-
-# Create database
-doctl databases db create chatwoot-db-id chatwoot_production
-
-# Create user
-doctl databases user create chatwoot-db-id chatwoot
-```
-
-#### Managed Redis
-
-```bash
-# Create managed Redis cluster
-doctl databases create chatwoot-redis \
-  --engine redis \
-  --version 6 \
-  --size db-s-1vcpu-1gb \
-  --region nyc3 \
-  --num-nodes 1
-```
-
-### Configuration
-
-Update Chatwoot configuration to use managed services:
-
-```bash
-# Switch to chatwoot user
-sudo -i -u chatwoot
-cd chatwoot
-
-# Edit environment file
-nano .env
-```
-
-Add managed database configuration:
-
-```bash
-# Database (from DigitalOcean dashboard)
-DATABASE_URL="postgresql://chatwoot:password@chatwoot-db-do-user-123456-0.b.db.ondigitalocean.com:25060/chatwoot_production?sslmode=require"
-
-# Redis (from DigitalOcean dashboard)
-REDIS_URL="rediss://default:password@chatwoot-redis-do-user-123456-0.b.db.ondigitalocean.com:25061"
-
-# Frontend URL
-FRONTEND_URL="https://chatwoot.yourdomain.com"
-FORCE_SSL=true
-
-# Storage (DigitalOcean Spaces)
-ACTIVE_STORAGE_SERVICE="amazon"
-S3_BUCKET_NAME="your-chatwoot-space"
-AWS_ACCESS_KEY_ID="your-spaces-key"
-AWS_SECRET_ACCESS_KEY="your-spaces-secret"
-AWS_REGION="nyc3"
-S3_ENDPOINT="https://nyc3.digitaloceanspaces.com"
-```
-
-### Load Balancer Setup
-
-```bash
-# Create load balancer
-doctl compute load-balancer create \
-  --name chatwoot-lb \
-  --forwarding-rules entry_protocol:https,entry_port:443,target_protocol:http,target_port:3000,certificate_id:your-cert-id \
-  --forwarding-rules entry_protocol:http,entry_port:80,target_protocol:http,target_port:3000 \
-  --health-check protocol:http,port:3000,path:/api,check_interval_seconds:10,response_timeout_seconds:5,healthy_threshold:3,unhealthy_threshold:3 \
-  --region nyc3 \
-  --droplet-ids droplet-id-1,droplet-id-2
-```
-
-## App Platform Deployment
-
-### App Spec Configuration
-
-Create `app.yaml`:
-
-```yaml
-name: chatwoot-app
-services:
-- name: web
-  source_dir: /
-  github:
-    repo: your-username/chatwoot-fork
-    branch: main
-  run_command: bundle exec rails server -b 0.0.0.0 -p $PORT
-  environment_slug: ruby
-  instance_count: 1
-  instance_size_slug: basic-xxs
-  envs:
-  - key: RAILS_ENV
-    value: production
-  - key: DATABASE_URL
-    value: ${chatwoot-db.DATABASE_URL}
-  - key: REDIS_URL
-    value: ${chatwoot-redis.REDIS_URL}
-  - key: FRONTEND_URL
-    value: ${APP_URL}
-  - key: FORCE_SSL
-    value: "true"
-  http_port: 8080
-
-- name: worker
-  source_dir: /
-  github:
-    repo: your-username/chatwoot-fork
-    branch: main
-  run_command: bundle exec sidekiq -C config/sidekiq.yml
-  environment_slug: ruby
-  instance_count: 1
-  instance_size_slug: basic-xxs
-  envs:
-  - key: RAILS_ENV
-    value: production
-  - key: DATABASE_URL
-    value: ${chatwoot-db.DATABASE_URL}
-  - key: REDIS_URL
-    value: ${chatwoot-redis.REDIS_URL}
-
-databases:
-- name: chatwoot-db
-  engine: PG
-  version: "13"
-  size: db-s-dev-database
-
-- name: chatwoot-redis
-  engine: REDIS
-  version: "6"
-  size: db-s-dev-database
-
-static_sites:
-- name: assets
-  source_dir: /public
-  github:
-    repo: your-username/chatwoot-fork
-    branch: main
-  build_command: bundle exec rails assets:precompile
-```
-
-### Deploy with App Platform
-
-```bash
-# Deploy using doctl
-doctl apps create --spec app.yaml
-
-# Or deploy via DigitalOcean Control Panel
-# 1. Go to App Platform
-# 2. Create App
-# 3. Connect your GitHub repository
-# 4. Configure build and run commands
-# 5. Add environment variables
-# 6. Deploy
-```
-
-## Kubernetes Deployment
-
-### Create DOKS Cluster
-
-```bash
-# Create Kubernetes cluster
-doctl kubernetes cluster create chatwoot-k8s \
-  --region nyc3 \
-  --version 1.24.4-do.0 \
-  --count 3 \
-  --size s-2vcpu-4gb \
-  --auto-upgrade=true \
-  --maintenance-window="saturday=06:00"
-
-# Get kubeconfig
-doctl kubernetes cluster kubeconfig save chatwoot-k8s
-```
-
-### Helm Deployment
-
-```bash
-# Add Chatwoot Helm repository
-helm repo add chatwoot https://chatwoot.github.io/charts
-helm repo update
-
-# Create namespace
-kubectl create namespace chatwoot
-
-# Install with DigitalOcean-specific values
-helm install chatwoot chatwoot/chatwoot \
-  --namespace chatwoot \
-  --set ingress.enabled=true \
-  --set ingress.className=nginx \
-  --set ingress.hosts[0].host=chatwoot.yourdomain.com \
-  --set postgresql.enabled=false \
-  --set redis.enabled=false \
-  --set env.DATABASE_URL="postgresql://..." \
-  --set env.REDIS_URL="redis://..."
-```
-
-### DigitalOcean-Specific Values
-
-Create `do-values.yaml`:
-
-```yaml
-# DigitalOcean Kubernetes values
-ingress:
-  enabled: true
-  className: nginx
-  annotations:
-    cert-manager.io/cluster-issuer: "letsencrypt-prod"
-    kubernetes.digitalocean.com/load-balancer-id: "your-lb-id"
-  hosts:
-    - host: chatwoot.yourdomain.com
-      paths:
-        - path: /
-          pathType: Prefix
-
-# Use DigitalOcean managed databases
-postgresql:
-  enabled: false
-
-redis:
-  enabled: false
-
-# DigitalOcean Spaces for storage
-env:
-  ACTIVE_STORAGE_SERVICE: "amazon"
-  S3_BUCKET_NAME: "your-chatwoot-space"
-  AWS_ACCESS_KEY_ID: "your-spaces-key"
-  AWS_SECRET_ACCESS_KEY: "your-spaces-secret"
-  AWS_REGION: "nyc3"
-  S3_ENDPOINT: "https://nyc3.digitaloceanspaces.com"
-
-# Resource limits for DigitalOcean
-resources:
-  limits:
-    cpu: 1000m
-    memory: 2Gi
-  requests:
-    cpu: 500m
-    memory: 1Gi
-
-# Storage class for DigitalOcean Block Storage
-persistence:
-  enabled: true
-  storageClass: "do-block-storage"
-  size: 20Gi
-```
-
-## Storage Configuration
-
-### DigitalOcean Spaces
-
-```bash
-# Create Spaces bucket
-doctl compute cdn create \
-  --origin nyc3.digitaloceanspaces.com/your-chatwoot-space \
-  --ttl 3600
-
-# Configure CORS for Spaces
-# Create cors.json:
-{
-  "CORSRules": [
-    {
-      "AllowedOrigins": ["https://chatwoot.yourdomain.com"],
-      "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
-      "AllowedHeaders": ["*"],
-      "MaxAgeSeconds": 3000
-    }
-  ]
-}
-
-# Apply CORS configuration
-s3cmd setcors cors.json s3://your-chatwoot-space
-```
-
-### Block Storage for Droplets
-
-```bash
-# Create and attach block storage
-doctl compute volume create chatwoot-storage \
-  --size 100GiB \
-  --region nyc3
-
-doctl compute volume-action attach chatwoot-storage \
-  --droplet-id your-droplet-id
-
-# Mount the volume
-sudo mkdir /mnt/chatwoot-storage
-sudo mount -o discard,defaults /dev/disk/by-id/scsi-0DO_Volume_chatwoot-storage /mnt/chatwoot-storage
-echo '/dev/disk/by-id/scsi-0DO_Volume_chatwoot-storage /mnt/chatwoot-storage ext4 defaults,nofail,discard 0 0' | sudo tee -a /etc/fstab
-```
-
-## SSL Certificate
-
-### Let's Encrypt with Certbot
-
-```bash
-# Install Certbot
-sudo apt update
-sudo apt install certbot python3-certbot-nginx
-
-# Obtain certificate
-sudo certbot --nginx -d chatwoot.yourdomain.com
-
-# Auto-renewal
-sudo crontab -e
-# Add: 0 12 * * * /usr/bin/certbot renew --quiet
-```
-
-### DigitalOcean Load Balancer SSL
-
-```bash
-# Upload certificate to DigitalOcean
-doctl compute certificate create \
-  --name chatwoot-cert \
-  --private-key-path private.key \
-  --leaf-certificate-path certificate.crt \
-  --certificate-chain-path ca_bundle.crt
-
-# Update load balancer with certificate
-doctl compute load-balancer update your-lb-id \
-  --forwarding-rules entry_protocol:https,entry_port:443,target_protocol:http,target_port:3000,certificate_id:your-cert-id
-```
-
-## Monitoring and Alerting
-
-### DigitalOcean Monitoring
-
-```bash
-# Enable monitoring for droplets
-doctl compute droplet create chatwoot-prod \
-  --enable-monitoring \
-  --enable-ipv6
-
-# Create alert policies
-doctl monitoring alert-policy create \
-  --type v1/insights/droplet/cpu \
-  --description "High CPU usage" \
-  --compare GreaterThan \
-  --value 80 \
-  --window 5m \
-  --entities droplet:your-droplet-id
-```
-
-### Custom Metrics with Prometheus
-
-```yaml
-# prometheus-config.yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: prometheus-config
-  namespace: monitoring
-data:
-  prometheus.yml: |
-    global:
-      scrape_interval: 15s
-    scrape_configs:
-    - job_name: 'chatwoot'
-      static_configs:
-      - targets: ['chatwoot-service:3000']
-      metrics_path: /metrics
-```
-
-## Backup Strategy
-
-### Database Backups
-
-```bash
-# Automated backups for managed databases are enabled by default
-# Manual backup
-doctl databases backups list chatwoot-db-id
-
-# Restore from backup
-doctl databases backups restore chatwoot-db-id backup-id
-```
-
-### Droplet Snapshots
-
-```bash
-# Create snapshot
-doctl compute droplet-action snapshot your-droplet-id \
-  --snapshot-name "chatwoot-backup-$(date +%Y%m%d)"
-
-# Schedule automated snapshots
-doctl compute droplet-action enable-backups your-droplet-id
-```
-
-### Application Data Backup
-
-```bash
-#!/bin/bash
-# backup-script.sh
-DATE=$(date +%Y%m%d_%H%M%S)
-
-# Database backup (if using managed database)
-pg_dump $DATABASE_URL | gzip > "/tmp/chatwoot_db_$DATE.sql.gz"
-
-# Upload to Spaces
-s3cmd put "/tmp/chatwoot_db_$DATE.sql.gz" s3://your-backup-space/db/
-
-# File uploads backup
-s3cmd sync s3://your-chatwoot-space/ s3://your-backup-space/files/
-
-# Cleanup local backup
-rm "/tmp/chatwoot_db_$DATE.sql.gz"
-```
-
-## Scaling and Performance
-
-### Horizontal Scaling with Load Balancer
-
-```bash
-# Create additional droplets
-for i in {2..3}; do
-  doctl compute droplet create chatwoot-prod-$i \
-    --image ubuntu-20-04-x64 \
-    --size s-2vcpu-4gb \
-    --region nyc3 \
-    --ssh-keys your-ssh-key-id \
-    --user-data-file cloud-init.yaml
-done
-
-# Add droplets to load balancer
-doctl compute load-balancer add-droplets your-lb-id \
-  --droplet-ids droplet-id-2,droplet-id-3
-```
-
-### Vertical Scaling
-
-```bash
-# Resize droplet
-doctl compute droplet-action resize your-droplet-id \
-  --size s-4vcpu-8gb \
-  --resize-disk
-```
-
-### Auto-scaling with Kubernetes
-
-```yaml
-# hpa.yaml
-apiVersion: autoscaling/v2
-kind: HorizontalPodAutoscaler
-metadata:
-  name: chatwoot-hpa
-  namespace: chatwoot
-spec:
-  scaleTargetRef:
-    apiVersion: apps/v1
-    kind: Deployment
-    name: chatwoot
-  minReplicas: 2
-  maxReplicas: 10
-  metrics:
-  - type: Resource
-    resource:
-      name: cpu
-      target:
-        type: Utilization
-        averageUtilization: 70
-  - type: Resource
-    resource:
-      name: memory
-      target:
-        type: Utilization
-        averageUtilization: 80
-```
-
-## Cost Optimization
-
-### Reserved Instances
-
-```bash
-# DigitalOcean doesn't offer reserved instances
-# But you can optimize costs by:
-
-# 1. Right-sizing droplets
-doctl compute size list
-
-# 2. Using appropriate database sizes
-doctl databases options sizes
-
-# 3. Implementing auto-scaling to scale down during low usage
-```
-
-### Cost Monitoring
-
-```bash
-# Check current usage and costs
-doctl account get
-
-# Monitor resource usage
-doctl monitoring metrics bandwidth droplet:your-droplet-id
-doctl monitoring metrics cpu droplet:your-droplet-id
-doctl monitoring metrics memory droplet:your-droplet-id
-```
-
-## Troubleshooting
-
-### Common Issues
-
-<Accordion title="Droplet connection issues">
-Check:
-- Firewall rules (ufw status)
-- DigitalOcean Cloud Firewalls
-- SSH key configuration
-- Network connectivity
-</Accordion>
-
-<Accordion title="Database connection problems">
-Verify:
-- Database cluster status
-- Connection string format
-- SSL requirements for managed databases
-- Firewall rules for database access
-</Accordion>
-
-<Accordion title="Load balancer health check failures">
-Solutions:
-- Verify health check path (/api)
-- Check application startup time
-- Ensure proper port configuration
-- Review application logs
-</Accordion>
-
-### Diagnostic Commands
-
-```bash
-# Check droplet status
-doctl compute droplet get your-droplet-id
-
-# View load balancer status
-doctl compute load-balancer get your-lb-id
-
-# Check database status
-doctl databases get chatwoot-db-id
-
-# Monitor application logs
-sudo journalctl -u chatwoot-web.1.service -f
-sudo journalctl -u chatwoot-worker.1.service -f
-```
-
-### Performance Monitoring
-
-```bash
-# System resources
-htop
-iostat -x 1
-free -h
-df -h
-
-# Network monitoring
-iftop
-netstat -tulpn
-
-# Application metrics
-curl http://localhost:3000/api
-curl http://localhost:3000/metrics
-```
-
-## Best Practices
-
-### Security
-- Enable DigitalOcean Cloud Firewalls
-- Use SSH keys instead of passwords
-- Enable automatic security updates
-- Implement fail2ban for SSH protection
-- Use managed databases for better security
-
-### Performance
-- Use DigitalOcean Spaces CDN for static assets
-- Implement Redis caching
-- Monitor with DigitalOcean Monitoring
-- Use SSD-backed droplets
-- Place resources in the same region
-
-### Reliability
-- Use multiple availability zones
-- Implement automated backups
-- Set up monitoring and alerting
-- Use load balancers for high availability
-- Test disaster recovery procedures
-
-### Cost Management
-- Right-size your resources
-- Use managed services to reduce operational overhead
-- Implement monitoring to track usage
-- Clean up unused resources regularly
-- Consider using Kubernetes for better resource utilization
-
----
-
-This DigitalOcean deployment guide provides multiple options for hosting Chatwoot on DigitalOcean's infrastructure. Choose the deployment method that best fits your technical requirements and budget constraints. 
+1. Follow the Chatwoot docs to configure your domain, email and other parameters you need.
+https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm#configure-the-required-environment-variables 

developer-docs/self-hosted/cloud/easypanel.mdx

@@ -0,0 +1,16 @@
+---
+title: Deploying Chatwoot on Easypanel
+description: Deploy Chatwoot using Easypanel's modern server control panel
+sidebarTitle: Easypanel
+---
+
+[Easypanel](https://easypanel.io) it's a modern server control panel. You can use it to deploy Chatwoot on your own server.
+
+[![Deploy to Easypanel](https://easypanel.io/img/deploy-on-easypanel-40.svg)](https://easypanel.io/docs/templates/chatwoot)
+
+## Instructions
+
+1. Create a VM that runs Ubuntu on your cloud provider.
+2. Install Easypanel using the instructions from the website.
+3. Create a new project.
+4. Install Chatwoot using the dedicated template. 

developer-docs/self-hosted/cloud/elestio.mdx

@@ -0,0 +1,43 @@
+---
+title: Elestio Chatwoot fully managed deployment guide
+description: Deploy Chatwoot with Elestio's fully managed platform
+sidebarTitle: Elestio
+---
+
+## Deploy to Elestio with one-click
+
+[![Deploy](https://pub-da36157c854648669813f3f76c526c2b.r2.dev/deploy-on-elestio-black.png)](https://elest.io/open-source/chatwoot)
+
+## Select the providers
+
+- Select cloud service provider of your choice.
+- Choose region of your choice
+- Select service plan. The smallest one offers 1 CPU, 2 GB RAM etc.
+- Confirm the details and hit "Next"
+
+![Elestio Setup](/self-hosted/images/elestio.png)
+
+## Configure
+
+- Select the support level
+- Name your application
+- Add admin email (You can add email you want to access your application from)
+- Click "Create Service"
+- Here you also get option to copy your terraform config (Optional)
+
+## Use Chatwoot
+
+- Click on "Display Admin UI"
+- Go to Admin Ui link provided
+- Add username and password provided on dashboard.
+
+![Elestio Dashboard](/self-hosted/images/elestio-dash.png)
+
+## Update Chatwoot
+
+- Go to Overview section in your Chatwoot service
+- Click "Change version" inside Software section
+- Choose the latest version or the version of your choice.
+- Additionally update the configs or restart the instance with single clink under same section
+
+![Elestio Change version](/self-hosted/images/elestio-version.png) 

developer-docs/self-hosted/cloud/gcp.mdx

@@ -1,745 +1,32 @@
 ---
-title: Google Cloud Platform (GCP) Deployment
-description: Deploy Chatwoot on Google Cloud Platform with Compute Engine, Cloud Run, or GKE
+title: GCP Chatwoot deployment guide
+description: Deploy Chatwoot on a single VM in GCP
 sidebarTitle: GCP
 ---
 
-# Google Cloud Platform Deployment Guide
+This guide will deploy chatwoot on a single VM in GCP.  For a cloud native deployment, use our [helm charts](https://github.com/chatwoot/charts) with Google Kubernetes Engine(GKE).
 
-Deploy Chatwoot on Google Cloud Platform using Compute Engine, Cloud Run, or Google Kubernetes Engine for a scalable, enterprise-ready solution.
+<Note>
+This guide is a work in progress and your mileage may vary.
+</Note>
 
-## Deployment Options
+## Create Compute Engine (VM)
 
-<CardGroup cols={3}>
-  <Card title="Compute Engine" icon="server" href="#compute-engine">
-    Traditional VM deployment with full control
-  </Card>
-  <Card title="Cloud Run" icon="cloud" href="#cloud-run">
-    Serverless container deployment
-  </Card>
-  <Card title="GKE" icon="kubernetes" href="#google-kubernetes-engine">
-    Managed Kubernetes deployment
-  </Card>
-</CardGroup>
+1. Navigate to VM > Compute Engine window.
+2. Create an instance with a minimum of 4vCPU and 8GB RAM.(N2 General-Purpose)
+3. Make sure to select the correct region you want to deploy.
+4. Choose `Ubuntu 20.04` as your OS with a 120GB disk.
+5. Click create.
 
-## Compute Engine Deployment
+![gcp-create-compute-engine](/self-hosted/images/gcp.png)
 
-### Prerequisites
+## Install Chatwoot
 
-```bash
-# Install and configure gcloud CLI
-curl https://sdk.cloud.google.com | bash
-exec -l $SHELL
-gcloud init
+1. SSH into the instance created.
+2. Follow the linux VM instructions at https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm.
+3. Woot! Woot! Your Chatwoot Instance is ready and can be accessed at `http://<your-instance-ip>:3000`. Or if you completed the domain setup during the installation, chatwoot should be available at `https://<your-domain>`
 
-# 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
-```
+## Configure Chatwoot
 
-### Network Setup
-
-```bash
-# Create VPC network
-gcloud compute networks create chatwoot-vpc --subnet-mode=custom
-
-# Create subnet
-gcloud compute networks subnets create chatwoot-subnet \
-  --network=chatwoot-vpc \
-  --range=10.0.1.0/24 \
-  --region=us-central1
-
-# Create firewall rules
-gcloud compute firewall-rules create chatwoot-allow-http \
-  --network=chatwoot-vpc \
-  --allow=tcp:80,tcp:443,tcp:3000 \
-  --source-ranges=0.0.0.0/0 \
-  --target-tags=chatwoot-server
-
-gcloud compute firewall-rules create chatwoot-allow-ssh \
-  --network=chatwoot-vpc \
-  --allow=tcp:22 \
-  --source-ranges=0.0.0.0/0 \
-  --target-tags=chatwoot-server
-```
-
-### Database Setup
-
-#### Cloud SQL PostgreSQL
-
-```bash
-# Create Cloud SQL instance
-gcloud sql instances create chatwoot-db \
-  --database-version=POSTGRES_13 \
-  --tier=db-g1-small \
-  --region=us-central1 \
-  --storage-type=SSD \
-  --storage-size=100GB \
-  --storage-auto-increase \
-  --backup-start-time=03:00 \
-  --enable-bin-log \
-  --maintenance-window-day=SUN \
-  --maintenance-window-hour=04
-
-# Create database
-gcloud sql databases create chatwoot_production --instance=chatwoot-db
-
-# Create user
-gcloud sql users create chatwoot \
-  --instance=chatwoot-db \
-  --password=your-secure-password
-
-# Get connection name
-gcloud sql instances describe chatwoot-db --format="value(connectionName)"
-```
-
-#### Memorystore Redis
-
-```bash
-# Create Redis instance
-gcloud redis instances create chatwoot-redis \
-  --size=1 \
-  --region=us-central1 \
-  --redis-version=redis_6_x \
-  --network=chatwoot-vpc
-```
-
-### Storage Setup
-
-```bash
-# Create Cloud Storage bucket
-gsutil mb -p your-project-id -c STANDARD -l us-central1 gs://your-chatwoot-bucket
-
-# Set bucket permissions
-gsutil iam ch allUsers:objectViewer gs://your-chatwoot-bucket
-
-# Enable CORS
-cat > cors.json << EOF
-[
-  {
-    "origin": ["https://chatwoot.yourdomain.com"],
-    "method": ["GET", "PUT", "POST", "DELETE"],
-    "responseHeader": ["Content-Type"],
-    "maxAgeSeconds": 3600
-  }
-]
-EOF
-
-gsutil cors set cors.json gs://your-chatwoot-bucket
-```
-
-### Compute Instance
-
-#### Create Instance Template
-
-```bash
-# Create startup script
-cat > startup-script.sh << 'EOF'
-#!/bin/bash
-apt-get update
-apt-get install -y wget curl
-
-# Download and install Chatwoot
-wget https://get.chatwoot.app/linux/install.sh
-chmod +x install.sh
-./install.sh --install
-
-# Configure environment
-sudo -u chatwoot bash << 'INNER_EOF'
-cd /home/chatwoot/chatwoot
-cat > .env << 'ENV_EOF'
-RAILS_ENV=production
-NODE_ENV=production
-FRONTEND_URL=https://chatwoot.yourdomain.com
-FORCE_SSL=true
-
-# Database
-DATABASE_URL=postgresql://chatwoot:password@/chatwoot_production?host=/cloudsql/your-project:us-central1:chatwoot-db
-
-# Redis
-REDIS_URL=redis://10.0.0.3:6379/0
-
-# Storage
-ACTIVE_STORAGE_SERVICE=google
-GCS_PROJECT=your-project-id
-GCS_BUCKET=your-chatwoot-bucket
-
-# Email (using SendGrid)
-MAILER_SENDER_EMAIL=noreply@yourdomain.com
-SMTP_ADDRESS=smtp.sendgrid.net
-SMTP_PORT=587
-SMTP_USERNAME=apikey
-SMTP_PASSWORD=your-sendgrid-api-key
-SMTP_AUTHENTICATION=plain
-SMTP_ENABLE_STARTTLS_AUTO=true
-ENV_EOF
-
-# Prepare database
-RAILS_ENV=production bundle exec rake db:chatwoot_prepare
-INNER_EOF
-
-# Restart services
-systemctl restart chatwoot.target
-EOF
-
-# Create instance template
-gcloud compute instance-templates create chatwoot-template \
-  --machine-type=e2-standard-2 \
-  --network-interface=network=chatwoot-vpc,subnet=chatwoot-subnet \
-  --boot-disk-size=50GB \
-  --boot-disk-type=pd-ssd \
-  --image-family=ubuntu-2004-lts \
-  --image-project=ubuntu-os-cloud \
-  --tags=chatwoot-server \
-  --metadata-from-file startup-script=startup-script.sh \
-  --service-account=chatwoot-sa@your-project-id.iam.gserviceaccount.com \
-  --scopes=https://www.googleapis.com/auth/cloud-platform
-```
-
-#### Create Managed Instance Group
-
-```bash
-# Create instance group
-gcloud compute instance-groups managed create chatwoot-ig \
-  --template=chatwoot-template \
-  --size=2 \
-  --zone=us-central1-a
-
-# Configure autoscaling
-gcloud compute instance-groups managed set-autoscaling chatwoot-ig \
-  --max-num-replicas=5 \
-  --min-num-replicas=2 \
-  --target-cpu-utilization=0.7 \
-  --zone=us-central1-a
-```
-
-### Load Balancer
-
-```bash
-# Create health check
-gcloud compute health-checks create http chatwoot-health-check \
-  --port=3000 \
-  --request-path=/api
-
-# Create backend service
-gcloud compute backend-services create chatwoot-backend \
-  --protocol=HTTP \
-  --health-checks=chatwoot-health-check \
-  --global
-
-# Add instance group to backend service
-gcloud compute backend-services add-backend chatwoot-backend \
-  --instance-group=chatwoot-ig \
-  --instance-group-zone=us-central1-a \
-  --global
-
-# Create URL map
-gcloud compute url-maps create chatwoot-map \
-  --default-service=chatwoot-backend
-
-# Create SSL certificate
-gcloud compute ssl-certificates create chatwoot-ssl \
-  --domains=chatwoot.yourdomain.com
-
-# Create HTTPS proxy
-gcloud compute target-https-proxies create chatwoot-https-proxy \
-  --url-map=chatwoot-map \
-  --ssl-certificates=chatwoot-ssl
-
-# Create global forwarding rule
-gcloud compute forwarding-rules create chatwoot-https-rule \
-  --global \
-  --target-https-proxy=chatwoot-https-proxy \
-  --ports=443
-
-# Create HTTP to HTTPS redirect
-gcloud compute url-maps create chatwoot-redirect \
-  --default-url-redirect-response-code=301 \
-  --default-url-redirect-https-redirect
-
-gcloud compute target-http-proxies create chatwoot-http-proxy \
-  --url-map=chatwoot-redirect
-
-gcloud compute forwarding-rules create chatwoot-http-rule \
-  --global \
-  --target-http-proxy=chatwoot-http-proxy \
-  --ports=80
-```
-
-## Cloud Run Deployment
-
-### Containerize Chatwoot
-
-Create `Dockerfile`:
-
-```dockerfile
-FROM chatwoot/chatwoot:latest
-
-# Set environment variables
-ENV RAILS_ENV=production
-ENV NODE_ENV=production
-ENV PORT=8080
-
-# Expose port
-EXPOSE 8080
-
-# Start command
-CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "8080"]
-```
-
-### Build and Deploy
-
-```bash
-# Build container image
-gcloud builds submit --tag gcr.io/your-project-id/chatwoot
-
-# Deploy to Cloud Run
-gcloud run deploy chatwoot \
-  --image gcr.io/your-project-id/chatwoot \
-  --platform managed \
-  --region us-central1 \
-  --allow-unauthenticated \
-  --memory 2Gi \
-  --cpu 2 \
-  --max-instances 10 \
-  --set-env-vars RAILS_ENV=production \
-  --set-env-vars DATABASE_URL="postgresql://..." \
-  --set-env-vars REDIS_URL="redis://..." \
-  --set-env-vars FRONTEND_URL="https://chatwoot.yourdomain.com"
-
-# Deploy worker service
-gcloud run deploy chatwoot-worker \
-  --image gcr.io/your-project-id/chatwoot \
-  --platform managed \
-  --region us-central1 \
-  --no-allow-unauthenticated \
-  --memory 1Gi \
-  --cpu 1 \
-  --max-instances 5 \
-  --command "bundle,exec,sidekiq,-C,config/sidekiq.yml" \
-  --set-env-vars RAILS_ENV=production \
-  --set-env-vars DATABASE_URL="postgresql://..." \
-  --set-env-vars REDIS_URL="redis://..."
-```
-
-### Custom Domain
-
-```bash
-# Map custom domain
-gcloud run domain-mappings create \
-  --service chatwoot \
-  --domain chatwoot.yourdomain.com \
-  --region us-central1
-```
-
-## Google Kubernetes Engine (GKE)
-
-### Create GKE Cluster
-
-```bash
-# Create GKE cluster
-gcloud container clusters create chatwoot-cluster \
-  --zone us-central1-a \
-  --num-nodes 3 \
-  --machine-type e2-standard-2 \
-  --disk-size 50GB \
-  --disk-type pd-ssd \
-  --enable-autoscaling \
-  --min-nodes 1 \
-  --max-nodes 5 \
-  --enable-autorepair \
-  --enable-autoupgrade \
-  --network chatwoot-vpc \
-  --subnetwork chatwoot-subnet
-
-# Get credentials
-gcloud container clusters get-credentials chatwoot-cluster --zone us-central1-a
-```
-
-### Helm Deployment
-
-```bash
-# Add Chatwoot Helm repository
-helm repo add chatwoot https://chatwoot.github.io/charts
-helm repo update
-
-# Create namespace
-kubectl create namespace chatwoot
-
-# Create values file for GCP
-cat > gcp-values.yaml << EOF
-# GCP-specific values
-ingress:
-  enabled: true
-  className: gce
-  annotations:
-    kubernetes.io/ingress.global-static-ip-name: "chatwoot-ip"
-    networking.gke.io/managed-certificates: "chatwoot-ssl"
-    kubernetes.io/ingress.allow-http: "false"
-  hosts:
-    - host: chatwoot.yourdomain.com
-      paths:
-        - path: /
-          pathType: Prefix
-
-# Use Cloud SQL and Memorystore
-postgresql:
-  enabled: false
-
-redis:
-  enabled: false
-
-env:
-  DATABASE_URL: "postgresql://chatwoot:password@/chatwoot_production?host=/cloudsql/your-project:us-central1:chatwoot-db"
-  REDIS_URL: "redis://10.0.0.3:6379/0"
-  ACTIVE_STORAGE_SERVICE: "google"
-  GCS_PROJECT: "your-project-id"
-  GCS_BUCKET: "your-chatwoot-bucket"
-
-# Resource limits
-resources:
-  limits:
-    cpu: 1000m
-    memory: 2Gi
-  requests:
-    cpu: 500m
-    memory: 1Gi
-
-# Workload Identity
-serviceAccount:
-  create: true
-  annotations:
-    iam.gke.io/gcp-service-account: chatwoot-sa@your-project-id.iam.gserviceaccount.com
-EOF
-
-# Install Chatwoot
-helm install chatwoot chatwoot/chatwoot \
-  --namespace chatwoot \
-  --values gcp-values.yaml
-```
-
-### SSL Certificate
-
-```yaml
-# managed-cert.yaml
-apiVersion: networking.gke.io/v1
-kind: ManagedCertificate
-metadata:
-  name: chatwoot-ssl
-  namespace: chatwoot
-spec:
-  domains:
-    - chatwoot.yourdomain.com
-```
-
-```bash
-kubectl apply -f managed-cert.yaml
-```
-
-## Service Account and IAM
-
-### Create Service Account
-
-```bash
-# Create service account
-gcloud iam service-accounts create chatwoot-sa \
-  --display-name="Chatwoot Service Account"
-
-# Grant necessary permissions
-gcloud projects add-iam-policy-binding your-project-id \
-  --member="serviceAccount:chatwoot-sa@your-project-id.iam.gserviceaccount.com" \
-  --role="roles/cloudsql.client"
-
-gcloud projects add-iam-policy-binding your-project-id \
-  --member="serviceAccount:chatwoot-sa@your-project-id.iam.gserviceaccount.com" \
-  --role="roles/storage.objectAdmin"
-
-gcloud projects add-iam-policy-binding your-project-id \
-  --member="serviceAccount:chatwoot-sa@your-project-id.iam.gserviceaccount.com" \
-  --role="roles/redis.editor"
-
-# Create and download key
-gcloud iam service-accounts keys create chatwoot-key.json \
-  --iam-account=chatwoot-sa@your-project-id.iam.gserviceaccount.com
-```
-
-## Monitoring and Logging
-
-### Cloud Monitoring
-
-```bash
-# Enable APIs
-gcloud services enable monitoring.googleapis.com
-gcloud services enable logging.googleapis.com
-
-# Create notification channel
-gcloud alpha monitoring channels create \
-  --display-name="Email Alerts" \
-  --type=email \
-  --channel-labels=email_address=admin@yourdomain.com
-```
-
-### Custom Metrics
-
-```yaml
-# monitoring.yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: prometheus-config
-  namespace: chatwoot
-data:
-  prometheus.yml: |
-    global:
-      scrape_interval: 15s
-    scrape_configs:
-    - job_name: 'chatwoot'
-      static_configs:
-      - targets: ['chatwoot-service:3000']
-      metrics_path: /metrics
-```
-
-### Alerting Policies
-
-```bash
-# Create alerting policy for high CPU
-gcloud alpha monitoring policies create \
-  --policy-from-file=cpu-alert-policy.yaml
-
-# cpu-alert-policy.yaml
-cat > cpu-alert-policy.yaml << EOF
-displayName: "High CPU Usage"
-conditions:
-  - displayName: "CPU usage above 80%"
-    conditionThreshold:
-      filter: 'resource.type="gce_instance"'
-      comparison: COMPARISON_GREATER_THAN
-      thresholdValue: 0.8
-      duration: 300s
-combiner: OR
-enabled: true
-notificationChannels:
-  - projects/your-project-id/notificationChannels/CHANNEL_ID
-EOF
-```
-
-## Backup and Disaster Recovery
-
-### Database Backups
-
-```bash
-# Cloud SQL automatic backups are enabled by default
-# Create on-demand backup
-gcloud sql backups create --instance=chatwoot-db
-
-# List backups
-gcloud sql backups list --instance=chatwoot-db
-
-# Restore from backup
-gcloud sql backups restore BACKUP_ID --restore-instance=chatwoot-db-restore
-```
-
-### Application Backups
-
-```bash
-#!/bin/bash
-# backup-script.sh
-DATE=$(date +%Y%m%d_%H%M%S)
-
-# Database backup
-gcloud sql export sql chatwoot-db gs://your-backup-bucket/db/chatwoot_$DATE.sql
-
-# File storage backup
-gsutil -m rsync -r -d gs://your-chatwoot-bucket gs://your-backup-bucket/files/
-
-# Kubernetes configuration backup
-kubectl get all -n chatwoot -o yaml > k8s-backup-$DATE.yaml
-gsutil cp k8s-backup-$DATE.yaml gs://your-backup-bucket/k8s/
-```
-
-## Security Best Practices
-
-### Network Security
-
-```bash
-# Create private cluster
-gcloud container clusters create chatwoot-private \
-  --enable-private-nodes \
-  --master-ipv4-cidr-block 172.16.0.0/28 \
-  --enable-ip-alias \
-  --enable-network-policy
-
-# Create firewall rules for private access
-gcloud compute firewall-rules create allow-chatwoot-private \
-  --network chatwoot-vpc \
-  --allow tcp:443,tcp:80 \
-  --source-ranges 10.0.0.0/8
-```
-
-### Secret Management
-
-```bash
-# Create secrets in Secret Manager
-gcloud secrets create database-password --data-file=db-password.txt
-gcloud secrets create redis-password --data-file=redis-password.txt
-
-# Grant access to service account
-gcloud secrets add-iam-policy-binding database-password \
-  --member="serviceAccount:chatwoot-sa@your-project-id.iam.gserviceaccount.com" \
-  --role="roles/secretmanager.secretAccessor"
-```
-
-### Binary Authorization
-
-```bash
-# Enable Binary Authorization
-gcloud container binauthz policy import policy.yaml
-
-# policy.yaml
-cat > policy.yaml << EOF
-defaultAdmissionRule:
-  requireAttestationsBy:
-  - projects/your-project-id/attestors/prod-attestor
-  enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
-globalPolicyEvaluationMode: ENABLE
-EOF
-```
-
-## Cost Optimization
-
-### Preemptible Instances
-
-```bash
-# Create preemptible node pool
-gcloud container node-pools create preemptible-pool \
-  --cluster=chatwoot-cluster \
-  --zone=us-central1-a \
-  --machine-type=e2-standard-2 \
-  --preemptible \
-  --num-nodes=2 \
-  --enable-autoscaling \
-  --min-nodes=0 \
-  --max-nodes=5
-```
-
-### Committed Use Discounts
-
-```bash
-# Purchase committed use discount
-gcloud compute commitments create chatwoot-commitment \
-  --plan=12-month \
-  --region=us-central1 \
-  --resources=type=VCPU,amount=4 \
-  --resources=type=MEMORY,amount=16
-```
-
-### Resource Optimization
-
-```yaml
-# resource-quota.yaml
-apiVersion: v1
-kind: ResourceQuota
-metadata:
-  name: chatwoot-quota
-  namespace: chatwoot
-spec:
-  hard:
-    requests.cpu: "4"
-    requests.memory: 8Gi
-    limits.cpu: "8"
-    limits.memory: 16Gi
-    persistentvolumeclaims: "4"
-```
-
-## Troubleshooting
-
-### Common Issues
-
-<Accordion title="Cloud SQL connection issues">
-Check:
-- Cloud SQL Proxy configuration
-- Service account permissions
-- Network connectivity
-- SSL requirements
-</Accordion>
-
-<Accordion title="GKE pod startup failures">
-Verify:
-- Resource quotas and limits
-- Image pull permissions
-- Service account configuration
-- Network policies
-</Accordion>
-
-<Accordion title="Load balancer health check failures">
-Solutions:
-- Verify health check path (/api)
-- Check firewall rules
-- Ensure proper backend configuration
-- Review application startup time
-</Accordion>
-
-### Diagnostic Commands
-
-```bash
-# Check Compute Engine instances
-gcloud compute instances list
-
-# View Cloud Run services
-gcloud run services list
-
-# Check GKE cluster status
-gcloud container clusters describe chatwoot-cluster --zone us-central1-a
-
-# View logs
-gcloud logging read "resource.type=gce_instance" --limit 50
-gcloud logging read "resource.type=cloud_run_revision" --limit 50
-
-# Check Cloud SQL status
-gcloud sql instances describe chatwoot-db
-```
-
-### Performance Monitoring
-
-```bash
-# View metrics
-gcloud monitoring metrics list --filter="metric.type:compute"
-
-# Create dashboard
-gcloud monitoring dashboards create --config-from-file=dashboard.json
-```
-
-## Best Practices
-
-### Security
-- Use private GKE clusters
-- Enable Workload Identity
-- Implement Binary Authorization
-- Use Secret Manager for sensitive data
-- Enable audit logging
-
-### Performance
-- Use Cloud CDN for static assets
-- Implement Cloud Memorystore for caching
-- Use SSD persistent disks
-- Enable HTTP/2 and gRPC
-- Optimize container images
-
-### Reliability
-- Deploy across multiple zones
-- Use managed services (Cloud SQL, Memorystore)
-- Implement proper health checks
-- Set up monitoring and alerting
-- Test disaster recovery procedures
-
-### Cost Management
-- Use preemptible instances for non-critical workloads
-- Implement resource quotas
-- Purchase committed use discounts
-- Monitor usage with Cloud Billing
-- Use Cloud Functions for event-driven tasks
-
----
-
-This GCP deployment guide provides comprehensive options for hosting Chatwoot on Google Cloud Platform. Choose the deployment method that best aligns with your scalability, security, and operational requirements. 
+1. Follow the Chatwoot docs to configure your domain, email and other parameters you need.
+https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm#configure-the-required-environment-variables 

developer-docs/self-hosted/cloud/heroku.mdx

@@ -1,505 +1,49 @@
 ---
-title: Heroku Deployment
-description: Deploy Chatwoot on Heroku with one-click deployment and managed services
+title: Heroku Chatwoot Production Deployment Guide
+description: Deploy Chatwoot on Heroku with one-click deployment
 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.
+# Deploying on Heroku
 
 <Note>
 Heroku has discontinued free dynos, postgres and redis. [Chatwoot will use basic/mini plans](https://blog.heroku.com/new-low-cost-plans) for all new Heroku deployments going forward.
 </Note>
 
-## Quick Deployment
-
-### One-Click Deploy
-
-The fastest way to get Chatwoot running on Heroku is using the one-click deploy button:
-
-<Card title="Deploy to Heroku" icon="heroku" href="https://heroku.com/deploy?template=https://github.com/chatwoot/chatwoot">
-  Click here to deploy Chatwoot to Heroku with one click
-</Card>
-
-### Deployment Steps
-
-1. **Click the Deploy Button**: Use the one-click deploy button above
-2. **Configure App Settings**:
-   - Choose an app name (or let Heroku generate one)
-   - Select your region (US or Europe)
-   - Review the default configuration
-
-3. **Deploy the Application**: Click "Deploy app" and wait for the build to complete
-
-4. **Enable Worker Dynos**:
-   - Go to the **Resources** tab in your Heroku app dashboard
-   - Ensure the **worker** dynos are turned on
-   - This is crucial for background job processing
-
-5. **Configure Environment Variables**:
-   - Go to **Settings** tab in Heroku app dashboard
-   - Click **Reveal Config Vars**
-   - Configure additional variables as needed
-
-6. **Access Your Installation**: Navigate to `yourapp.herokuapp.com`
-
-## Configuration
-
-### Required Environment Variables
-
-Heroku automatically sets up basic configuration, but you'll need to configure additional variables:
-
-#### Email Configuration
-
-```bash
-# SMTP Settings (required for notifications)
-MAILER_SENDER_EMAIL=noreply@yourdomain.com
-SMTP_ADDRESS=smtp.sendgrid.net
-SMTP_PORT=587
-SMTP_USERNAME=apikey
-SMTP_PASSWORD=your-sendgrid-api-key
-SMTP_AUTHENTICATION=plain
-SMTP_ENABLE_STARTTLS_AUTO=true
-```
-
-#### File Storage Configuration
-
-<Warning>
-Heroku has an "ephemeral" hard disk. Files uploaded to Chatwoot will not persist after application restarts. You must configure cloud storage.
-</Warning>
-
-**Amazon S3 Configuration:**
-
-```bash
-ACTIVE_STORAGE_SERVICE=amazon
-S3_BUCKET_NAME=your-chatwoot-bucket
-AWS_ACCESS_KEY_ID=your-access-key
-AWS_SECRET_ACCESS_KEY=your-secret-key
-AWS_REGION=us-east-1
-```
-
-**Google Cloud Storage Configuration:**
-
-```bash
-ACTIVE_STORAGE_SERVICE=google
-GCS_PROJECT=your-project-id
-GCS_BUCKET=your-chatwoot-bucket
-GOOGLE_APPLICATION_CREDENTIALS={"type":"service_account",...}
-```
-
-#### Frontend URL
-
-```bash
-FRONTEND_URL=https://yourapp.herokuapp.com
-FORCE_SSL=true
-```
-
-### Setting Environment Variables
-
-#### Via Heroku Dashboard
-
-1. Go to your app's **Settings** tab
-2. Click **Reveal Config Vars**
-3. Add each variable name and value
-4. Click **Add** for each variable
-
-#### Via Heroku CLI
-
-```bash
-# Install Heroku CLI
-npm install -g heroku
-
-# Login to Heroku
-heroku login
-
-# Set environment variables
-heroku config:set MAILER_SENDER_EMAIL=noreply@yourdomain.com -a your-app-name
-heroku config:set SMTP_ADDRESS=smtp.sendgrid.net -a your-app-name
-heroku config:set SMTP_PORT=587 -a your-app-name
-
-# Set storage configuration
-heroku config:set ACTIVE_STORAGE_SERVICE=amazon -a your-app-name
-heroku config:set S3_BUCKET_NAME=your-bucket -a your-app-name
-heroku config:set AWS_ACCESS_KEY_ID=your-key -a your-app-name
-heroku config:set AWS_SECRET_ACCESS_KEY=your-secret -a your-app-name
-```
-
-## Add-ons and Services
-
-### Database (PostgreSQL)
-
-Heroku automatically provisions a PostgreSQL database:
-
-```bash
-# Check database info
-heroku pg:info -a your-app-name
-
-# Access database console
-heroku pg:psql -a your-app-name
-
-# Create database backup
-heroku pg:backups:capture -a your-app-name
-
-# Download backup
-heroku pg:backups:download -a your-app-name
-```
-
-### Redis
-
-Heroku automatically provisions Redis for caching and background jobs:
-
-```bash
-# Check Redis info
-heroku redis:info -a your-app-name
-
-# Access Redis CLI
-heroku redis:cli -a your-app-name
-
-# Monitor Redis
-heroku redis:monitor -a your-app-name
-```
-
-### Email Service (SendGrid)
-
-Add SendGrid for email delivery:
-
-```bash
-# Add SendGrid add-on
-heroku addons:create sendgrid:starter -a your-app-name
-
-# Get SendGrid credentials
-heroku config:get SENDGRID_USERNAME -a your-app-name
-heroku config:get SENDGRID_PASSWORD -a your-app-name
-```
-
-## Updating Your Deployment
-
-### Method 1: GitHub Integration (Recommended)
-
-1. **Connect GitHub Repository**:
-   - Go to the **Deploy** tab in your Heroku app dashboard
-   - Choose **GitHub** as the deployment method
-   - Connect the `chatwoot/chatwoot` repository
-
-2. **Enable Automatic Deploys** (Optional):
-   - Enable automatic deploys from the `master` branch
-   - This will automatically deploy when new releases are available
-
-3. **Manual Deploy**:
-   - Go to **Manual deploy** section
-   - Choose `master` branch
-   - Click **Deploy Branch**
-
-### Method 2: Heroku CLI
-
-```bash
-# Clone the Chatwoot repository
-git clone https://github.com/chatwoot/chatwoot.git
-cd chatwoot
-
-# Add Heroku remote
-heroku git:remote -a your-app-name
-
-# Deploy latest version
-git push heroku master
-```
-
-### Method 3: Docker Deployment
-
-```bash
-# Login to Heroku Container Registry
-heroku container:login
-
-# Build and push Docker image
-heroku container:push web -a your-app-name
-
-# Release the image
-heroku container:release web -a your-app-name
-```
-
-## Scaling and Performance
-
-### Dyno Management
-
-```bash
-# Scale web dynos
-heroku ps:scale web=2 -a your-app-name
-
-# Scale worker dynos
-heroku ps:scale worker=1 -a your-app-name
-
-# Check dyno status
-heroku ps -a your-app-name
-```
-
-### Performance Monitoring
-
-```bash
-# View application metrics
-heroku logs --tail -a your-app-name
-
-# Monitor dyno performance
-heroku ps:exec -a your-app-name
-
-# Check memory usage
-heroku logs --source app --tail -a your-app-name | grep "Memory usage"
-```
-
-## Monitoring and Logging
-
-### Application Logs
-
-```bash
-# View recent logs
-heroku logs -a your-app-name
-
-# Tail logs in real-time
-heroku logs --tail -a your-app-name
-
-# Filter logs by source
-heroku logs --source app -a your-app-name
-heroku logs --source heroku -a your-app-name
-```
-
-### Add Monitoring Services
-
-#### Papertrail (Log Management)
-
-```bash
-# Add Papertrail
-heroku addons:create papertrail:choklad -a your-app-name
-
-# View logs in Papertrail
-heroku addons:open papertrail -a your-app-name
-```
-
-#### New Relic (Application Monitoring)
-
-```bash
-# Add New Relic
-heroku addons:create newrelic:wayne -a your-app-name
-
-# Configure New Relic
-heroku config:set NEW_RELIC_APP_NAME="Chatwoot Production" -a your-app-name
-
-# Open New Relic dashboard
-heroku addons:open newrelic -a your-app-name
-```
-
-## Security Configuration
-
-### SSL/TLS
-
-Heroku automatically provides SSL certificates for custom domains:
-
-```bash
-# Add custom domain
-heroku domains:add chatwoot.yourdomain.com -a your-app-name
-
-# Check SSL certificate status
-heroku certs -a your-app-name
-
-# Enable Automated Certificate Management
-heroku certs:auto:enable -a your-app-name
-```
-
-### Environment Security
-
-```bash
-# Rotate database credentials
-heroku pg:credentials:rotate -a your-app-name
-
-# Rotate Redis credentials
-heroku redis:credentials:rotate -a your-app-name
-
-# Review security settings
-heroku config -a your-app-name
-```
-
-## Backup and Recovery
-
-### Database Backups
-
-```bash
-# Schedule automatic backups
-heroku pg:backups:schedule DATABASE_URL --at '02:00 America/Los_Angeles' -a your-app-name
-
-# Create manual backup
-heroku pg:backups:capture -a your-app-name
-
-# List all backups
-heroku pg:backups -a your-app-name
-
-# Restore from backup
-heroku pg:backups:restore b001 DATABASE_URL -a your-app-name
-```
-
-### File Storage Backups
-
-Since Heroku has ephemeral storage, ensure your cloud storage has backup policies:
-
-**For S3:**
-```bash
-# Enable versioning on S3 bucket
-aws s3api put-bucket-versioning \
-  --bucket your-chatwoot-bucket \
-  --versioning-configuration Status=Enabled
-
-# Set up lifecycle policy for old versions
-aws s3api put-bucket-lifecycle-configuration \
-  --bucket your-chatwoot-bucket \
-  --lifecycle-configuration file://lifecycle.json
-```
-
-## Troubleshooting
-
-### Common Issues
-
-<Accordion title="Application not starting">
-**Symptoms**: App crashes on startup, H10 errors
-
-**Solutions**:
-- Check that worker dynos are enabled in Resources tab
-- Verify all required environment variables are set
-- Check application logs: `heroku logs --tail -a your-app-name`
-- Ensure database migrations have run: `heroku run rails db:migrate -a your-app-name`
-</Accordion>
-
-<Accordion title="File uploads not working">
-**Symptoms**: Files upload but disappear after app restart
-
-**Solutions**:
-- Configure cloud storage (S3, GCS, etc.)
-- Verify storage credentials are correct
-- Check CORS settings on your storage bucket
-- Test storage configuration: `heroku run rails console -a your-app-name`
-</Accordion>
-
-<Accordion title="Email notifications not sending">
-**Symptoms**: Users not receiving email notifications
-
-**Solutions**:
-- Verify SMTP configuration in config vars
-- Check SendGrid add-on status
-- Test email configuration: `heroku run rails console -a your-app-name`
-- Review email logs in SendGrid dashboard
-</Accordion>
-
-<Accordion title="Build version shows as unknown">
-**Symptoms**: Settings page shows "unknown" build version
-
-**Solution**:
-Enable runtime dyno metadata:
-```bash
-heroku labs:enable runtime-dyno-metadata -a your-app-name
-```
-</Accordion>
-
-### Performance Issues
-
-<Accordion title="Slow response times">
-**Solutions**:
-- Scale up web dynos: `heroku ps:scale web=2 -a your-app-name`
-- Upgrade to higher performance dynos
-- Monitor database performance with `heroku pg:diagnose -a your-app-name`
-- Check Redis performance with `heroku redis:info -a your-app-name`
-</Accordion>
-
-<Accordion title="Background jobs not processing">
-**Solutions**:
-- Ensure worker dynos are running: `heroku ps -a your-app-name`
-- Scale worker dynos if needed: `heroku ps:scale worker=1 -a your-app-name`
-- Check Sidekiq logs: `heroku logs --source app --tail -a your-app-name | grep sidekiq`
-</Accordion>
-
-### Diagnostic Commands
-
-```bash
-# Check app status
-heroku ps -a your-app-name
-
-# View configuration
-heroku config -a your-app-name
-
-# Check add-ons
-heroku addons -a your-app-name
-
-# Run Rails console
-heroku run rails console -a your-app-name
-
-# Run database migrations
-heroku run rails db:migrate -a your-app-name
-
-# Check database status
-heroku pg:info -a your-app-name
-
-# Check Redis status
-heroku redis:info -a your-app-name
-```
+Deploy Chatwoot on Heroku through the following steps:
+
+1. Click on the [one click deploy button](https://heroku.com/deploy?template=https://github.com/chatwoot/chatwoot/tree/master) and deploy your app.
+2. Go to the **Resources** tab in the Heroku app dashboard and ensure the worker dynos is turned on.
+3. Head over to **Settings** tab in Heroku app dashboard and click **Reveal Config Vars**.
+4. Configure the environment variables for [mailer](/self-hosted/configuration/environment-variables#configure-emails) and [storage](/self-hosted/deployment/storage/supported-providers) as per the [documentation](/self-hosted/configuration/environment-variables).
+5. Head over to `yourapp.herokuapp.com` and enjoy using Chatwoot.
+
+<iframe 
+  frameBorder="0" 
+  scrolling="no" 
+  marginHeight="0" 
+  marginWidth="0"
+  width="100%" 
+  height="443" 
+  type="text/html" 
+  src="https://www.youtube-nocookie.com/embed/iN2Dl0QkvEg?autoplay=0&fs=0&iv_load_policy=3&showinfo=1&rel=0&cc_load_policy=0&start=0&end=0&origin=https://youtubeembedcode.com">
+</iframe>
+
+## Updating the deployment on Heroku
+
+Whenever a new version is out for Chatwoot, you update your Heroku deployment through following steps:
+
+1. In the **Deploy** tab, choose `GitHub` as the deployment option.
+2. Connect Chatwoot repo to the app.
+3. Head over to the manual deploy option, choose `master` branch and hit **Deploy**.
 
 ## Known Limitations
 
-### Platform Limitations
+1. **Dyno Sleep**: If you are on a free tier and you don't access the application for a while Heroku will put your dynos to sleep. You can fix this by upgrading the dynos to paid tier.
 
-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
+2. **Ephemeral Storage**: Heroku has an "ephemeral" hard disk. The files uploaded to Chatwoot would not persist after the application is restarted. By default, Chatwoot uses local disk as the upload destination. To overcome this problem, you will have to [configure a cloud storage](/self-hosted/deployment/storage/supported-providers).
 
-### 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). 
+3. **Build Version**: If the build version is shown as unknown on the settings page, enable the runtime dyno metadata feature. To enable, use:
+   ```bash
+   heroku labs:enable runtime-dyno-metadata -a <app-name>
+   ``` 

developer-docs/self-hosted/cloud/restack.mdx

@@ -0,0 +1,101 @@
+---
+title: Restack Chatwoot production deployment guide
+description: Deploy Chatwoot on AWS with Restack's managed Kubernetes platform
+sidebarTitle: AWS with Restack
+---
+
+## Getting Started
+
+To deploy Chatwoot with Restack:
+
+- [Sign up for a Restack account](#sign-up-for-a-restack-account).
+- [Add AWS credentials with AdministratorAccess](#add-aws-credentials-with-administratoraccess).
+- [One-click cluster creation with Restack](#one-click-cluster-creation-with-restack).
+- [Deploy Chatwoot on Restack](#deploy-chatwoot-on-restack).
+- [Start using Chatwoot](#start-using-chatwoot).
+- [Deploy multiple instances of Chatwoot](#deploy-multiple-instances-of-chatwoot).
+
+<Note>
+This is a community contributed installation setup. This will only have community support for any issues in future.
+</Note>
+
+## Sign up for a Restack account
+
+To Sign up for a Restack account, visit [www.restack.io/signup](https://www.restack.io/signup). You can sign up with your corporate email address or your GitHub profile. You do not need a credit card to sign up.
+
+![restack-signup](/self-hosted/images/restack-sign-up.png)
+
+If you already have an account, go ahead and login to Restack at [www.restack.io/login](https://www.restack.io/login).
+
+## Add AWS credentials with AdministratorAccess
+
+To deploy Chatwoot in your own AWS infrastructure with Restack, you will need to add your credentials as the next step.
+
+Make sure that this account has *AdministratorAccess*. This is how Restack can ensure an end-to-end cluster creation and cluster management process.
+
+1. Navigate to *Clusters* in the left-hand navigation menu.
+2. Select the *Credentials* tab.
+3. Click *Add credential*.
+
+![add-credentials](/self-hosted/images/Add_credentials.png)
+
+4. Give a suitable title to your credentials for managing them later.
+5. Enter your *AWS Access Key ID* and *AWS Secret Access key*.
+6. Click *Add credential*.
+
+![add-aws-credentials](/self-hosted/images/Add_AWS_Creds.png)
+
+<Tip>
+[How to get your AWS Access key ID and AWS Secret Access Key](https://docs.aws.amazon.com/accounts/latest/reference/root-user-access-key.html)
+</Tip>
+
+## One-click cluster creation with Restack
+
+<Tip>
+Why do I need a cluster?<br/>
+Running your application on a Kubernetes cluster lets you deploy, scale and monitor the application reliably.
+</Tip>
+
+Once you have added your credentials,
+
+1. Navigate to the *Clusters* tab on the same page and click on *Create cluster*.
+
+![create-cluster](/self-hosted/images/Create_cluster.png)
+
+2. Give a suitable name to your cluster.
+3. Select the region you want to deploy the cluster in.
+4. Select the AWS credentials you added in the previous step.
+
+![cluster-details](/self-hosted/images/Cluster_details.png)
+
+The cluster creation process will start automatically. Once the cluster is ready, you will get an email on the email id connected with your account.<br/>Creating a cluster is a one-time process. From here you can add other open source tools or multiple instances of Chatwoot in the same cluster.
+
+![creating-cluster](/self-hosted/images/Creating_cluster.png)
+
+![cluster-created](/self-hosted/images/Cluster_created.png)
+
+Any application you deploy in your cluster will be accessible via a free **restack domain**.<br/>Contact the Restack team via chat to set a custom domain for your Chatwoot instances.
+
+## Deploy Chatwoot on Restack
+
+1. Click *Add application* from the Cluster description or go to the Applications tab in the left hand side navigation.
+2. Click *Chatwoot*.
+
+![select-chatwoot](/self-hosted/images/Select_Chatwoot.png)
+
+3. Select the cluster you have already provisioned.
+4. Click *Add application*.
+
+## Start using Chatwoot
+
+Chatwoot will be deployed on your cluster and you can access it using the link under the *URL* tab.
+
+![chatwoot-deployed](/self-hosted/images/Chatwoot_deployed.png)
+
+You can also check the workloads and volumes that are deployed within Chatwoot.
+
+![access-chatwoot](/self-hosted/images/Chatwoot_access.png)
+
+## Deploy multiple instances of Chatwoot
+
+Restack makes it easier to deploy multiple instances of Chatwoot on the same or multiple clusters.<br/>So you can test the latest version before upgrading or have a dedicated instance for development and for production. 

developer-docs/self-hosted/configuration/environment-variables.mdx

@@ -4,745 +4,261 @@ description: Complete reference for Chatwoot environment variables and configura
 sidebarTitle: Environment Variables
 ---
 
-# Environment Variables Reference
+## The .env File
 
-Chatwoot uses environment variables for configuration. This guide provides a comprehensive reference for all available environment variables and their usage.
+We use the `dotenv-rails` gem to manage the environment variables. There is a file called `env.example` in the root directory of this project with all the environment variables set to empty values. You can set the correct values as per the following options. Once you set the values, you should rename the file to `.env` before you start the server.
 
-## Core Application Settings
+## Configure frontend URL (domain)
 
-### Basic Configuration
+Provide your chatwoot domain as frontend URL.
+
+```bash
+FRONTEND_URL='https://your-chatwoot-domain.tld'
+```
+
+## Rails production variables
+
+For production deployment, you have to set the following variables
 
 ```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
+SECRET_KEY_BASE=replace_with_your_own_secret_string
 ```
 
-### Application Behavior
-
-```bash
-# Enable/disable account signup
-ENABLE_ACCOUNT_SIGNUP=false
-
-# Auto-assign conversations to online agents
-AUTO_ASSIGN_CONVERSATIONS=true
-
-# Enable conversation continuity (link conversations across sessions)
-CONVERSATION_CONTINUITY=true
-
-# Maximum file upload size (in MB)
-MAXIMUM_FILE_UPLOAD_SIZE=40
-
-# Enable IP-based rate limiting
-ENABLE_IP_RATE_LIMIT=true
-
-# Rate limit per IP (requests per minute)
-IP_RATE_LIMIT=100
-```
-
-## Database Configuration
-
-### PostgreSQL
-
-```bash
-# Database URL (primary configuration method)
-DATABASE_URL=postgresql://username:password@hostname:port/database_name
-
-# Alternative: Individual components
-POSTGRES_HOST=localhost
-POSTGRES_PORT=5432
-POSTGRES_USERNAME=chatwoot
-POSTGRES_PASSWORD=your-password
-POSTGRES_DATABASE=chatwoot_production
-
-# Database pool size
-DATABASE_POOL_SIZE=5
-
-# Database timeout (seconds)
-DATABASE_TIMEOUT=5000
-
-# Enable prepared statements
-DATABASE_PREPARED_STATEMENTS=true
-```
-
-### Database SSL Configuration
-
-```bash
-# SSL Mode (disable, allow, prefer, require, verify-ca, verify-full)
-DATABASE_SSL_MODE=require
-
-# SSL Certificate paths (for verify-ca and verify-full modes)
-DATABASE_SSL_CERT=/path/to/client-cert.pem
-DATABASE_SSL_KEY=/path/to/client-key.pem
-DATABASE_SSL_ROOT_CERT=/path/to/ca-cert.pem
-```
-
-## Redis Configuration
-
-### Basic Redis Settings
-
-```bash
-# Redis URL (primary configuration method)
-REDIS_URL=redis://localhost:6379/0
-
-# Alternative: Individual components
-REDIS_HOST=localhost
-REDIS_PORT=6379
-REDIS_DB=0
-REDIS_PASSWORD=your-redis-password
-
-# Redis connection pool size
-REDIS_POOL_SIZE=5
-
-# Redis timeout (seconds)
-REDIS_TIMEOUT=1
-```
-
-### Redis SSL Configuration
-
-```bash
-# Enable SSL for Redis
-REDIS_SSL=true
-
-# Redis SSL certificate verification
-REDIS_SSL_VERIFY=true
-
-# Redis SSL certificate paths
-REDIS_SSL_CERT=/path/to/redis-client.crt
-REDIS_SSL_KEY=/path/to/redis-client.key
-REDIS_SSL_CA=/path/to/redis-ca.crt
-```
-
-### Sidekiq Configuration
-
-```bash
-# Sidekiq concurrency (number of worker threads)
-SIDEKIQ_CONCURRENCY=10
-
-# Sidekiq Redis namespace
-SIDEKIQ_REDIS_NAMESPACE=chatwoot_sidekiq
-
-# Sidekiq log level
-SIDEKIQ_LOG_LEVEL=info
-
-# Enable Sidekiq web UI
-SIDEKIQ_WEB_UI=true
-
-# Sidekiq web UI username/password
-SIDEKIQ_WEB_USERNAME=admin
-SIDEKIQ_WEB_PASSWORD=your-password
-```
-
-## Email Configuration
-
-### SMTP Settings
-
-```bash
-# Sender email address
-MAILER_SENDER_EMAIL=noreply@yourdomain.com
-
-# SMTP server configuration
-SMTP_ADDRESS=smtp.gmail.com
-SMTP_PORT=587
-SMTP_USERNAME=your-email@gmail.com
-SMTP_PASSWORD=your-app-password
-SMTP_AUTHENTICATION=plain
-SMTP_ENABLE_STARTTLS_AUTO=true
-SMTP_OPENSSL_VERIFY_MODE=peer
-
-# SMTP domain (for HELO command)
-SMTP_DOMAIN=yourdomain.com
-
-# Force TLS
-SMTP_TLS=true
-```
-
-### Email Provider Examples
-
-<Tabs>
-  <Tab title="Gmail">
-    ```bash
-    SMTP_ADDRESS=smtp.gmail.com
-    SMTP_PORT=587
-    SMTP_USERNAME=your-email@gmail.com
-    SMTP_PASSWORD=your-app-password
-    SMTP_AUTHENTICATION=plain
-    SMTP_ENABLE_STARTTLS_AUTO=true
-    ```
-  </Tab>
-  
-  <Tab title="SendGrid">
-    ```bash
-    SMTP_ADDRESS=smtp.sendgrid.net
-    SMTP_PORT=587
-    SMTP_USERNAME=apikey
-    SMTP_PASSWORD=your-sendgrid-api-key
-    SMTP_AUTHENTICATION=plain
-    SMTP_ENABLE_STARTTLS_AUTO=true
-    ```
-  </Tab>
-  
-  <Tab title="Mailgun">
-    ```bash
-    SMTP_ADDRESS=smtp.mailgun.org
-    SMTP_PORT=587
-    SMTP_USERNAME=postmaster@mg.yourdomain.com
-    SMTP_PASSWORD=your-mailgun-password
-    SMTP_AUTHENTICATION=plain
-    SMTP_ENABLE_STARTTLS_AUTO=true
-    ```
-  </Tab>
-  
-  <Tab title="AWS SES">
-    ```bash
-    SMTP_ADDRESS=email-smtp.us-east-1.amazonaws.com
-    SMTP_PORT=587
-    SMTP_USERNAME=your-ses-username
-    SMTP_PASSWORD=your-ses-password
-    SMTP_AUTHENTICATION=plain
-    SMTP_ENABLE_STARTTLS_AUTO=true
-    ```
-  </Tab>
-</Tabs>
-
-### Email Templates
-
-```bash
-# Custom email template path
-CUSTOM_EMAIL_TEMPLATE_PATH=/path/to/custom/templates
-
-# Email template language
-EMAIL_TEMPLATE_LANGUAGE=en
-
-# Enable email tracking
-EMAIL_TRACKING_ENABLED=true
-
-# Email delivery method (smtp, sendmail, test)
-EMAIL_DELIVERY_METHOD=smtp
-```
-
-## File Storage Configuration
-
-### Local Storage
-
-```bash
-# Active storage service
-ACTIVE_STORAGE_SERVICE=local
-
-# Local storage path
-LOCAL_STORAGE_PATH=/home/chatwoot/chatwoot/storage
-```
-
-### Amazon S3
-
-```bash
-# Active storage service
-ACTIVE_STORAGE_SERVICE=amazon
-
-# S3 configuration
-S3_BUCKET_NAME=your-chatwoot-bucket
-AWS_ACCESS_KEY_ID=your-access-key
-AWS_SECRET_ACCESS_KEY=your-secret-key
-AWS_REGION=us-east-1
-
-# S3 endpoint (for S3-compatible services)
-S3_ENDPOINT=https://s3.amazonaws.com
-
-# S3 force path style (for MinIO and other S3-compatible services)
-S3_FORCE_PATH_STYLE=false
-
-# S3 public URL (for CDN)
-S3_PUBLIC_URL=https://cdn.yourdomain.com
-```
-
-### Google Cloud Storage
-
-```bash
-# Active storage service
-ACTIVE_STORAGE_SERVICE=google
-
-# GCS configuration
-GCS_PROJECT=your-project-id
-GCS_BUCKET=your-chatwoot-bucket
-
-# GCS credentials (JSON key file path)
-GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
-
-# GCS public URL (for CDN)
-GCS_PUBLIC_URL=https://cdn.yourdomain.com
-```
-
-### Azure Blob Storage
-
-```bash
-# Active storage service
-ACTIVE_STORAGE_SERVICE=azure
-
-# Azure configuration
-AZURE_STORAGE_ACCOUNT_NAME=your-storage-account
-AZURE_STORAGE_ACCESS_KEY=your-access-key
-AZURE_STORAGE_CONTAINER=your-container-name
-
-# Azure public URL (for CDN)
-AZURE_PUBLIC_URL=https://cdn.yourdomain.com
-```
-
-## Third-Party Integrations
-
-### Facebook
-
-```bash
-# Facebook App ID and Secret
-FB_APP_ID=your-facebook-app-id
-FB_APP_SECRET=your-facebook-app-secret
-
-# Facebook Verify Token
-FB_VERIFY_TOKEN=your-verify-token
-
-# Facebook API Version
-FB_API_VERSION=v13.0
-```
-
-### Twitter
-
-```bash
-# Twitter API credentials
-TWITTER_APP_ID=your-twitter-app-id
-TWITTER_CONSUMER_KEY=your-consumer-key
-TWITTER_CONSUMER_SECRET=your-consumer-secret
-TWITTER_ENVIRONMENT=your-twitter-environment
-```
-
-### Slack
-
-```bash
-# Slack App credentials
-SLACK_CLIENT_ID=your-slack-client-id
-SLACK_CLIENT_SECRET=your-slack-client-secret
-```
-
-### Google OAuth
-
-```bash
-# Google OAuth credentials
-GOOGLE_OAUTH_CLIENT_ID=your-google-client-id
-GOOGLE_OAUTH_CLIENT_SECRET=your-google-client-secret
-```
-
-### Microsoft OAuth
-
-```bash
-# Microsoft OAuth credentials
-MICROSOFT_APP_ID=your-microsoft-app-id
-MICROSOFT_APP_SECRET=your-microsoft-app-secret
-```
-
-## Push Notifications
-
-### FCM (Firebase Cloud Messaging)
-
-```bash
-# FCM Server Key
-FCM_SERVER_KEY=your-fcm-server-key
-
-# FCM Project ID
-FCM_PROJECT_ID=your-firebase-project-id
-
-# FCM credentials file
-GOOGLE_APPLICATION_CREDENTIALS=/path/to/firebase-service-account.json
-```
-
-### Vapid Keys (Web Push)
-
-```bash
-# Vapid public and private keys
-VAPID_PUBLIC_KEY=your-vapid-public-key
-VAPID_PRIVATE_KEY=your-vapid-private-key
-
-# Vapid subject (email or URL)
-VAPID_SUBJECT=mailto:admin@yourdomain.com
-```
-
-## Analytics and Monitoring
-
-### Application Monitoring
-
-```bash
-# Enable application metrics
-ENABLE_METRICS=true
-
-# Metrics endpoint path
-METRICS_PATH=/metrics
-
-# Prometheus exporter
-PROMETHEUS_EXPORTER=true
-PROMETHEUS_EXPORTER_PORT=9394
-
-# New Relic
-NEW_RELIC_LICENSE_KEY=your-newrelic-license-key
-NEW_RELIC_APP_NAME=Chatwoot
-
-# Sentry error tracking
-SENTRY_DSN=your-sentry-dsn
-```
-
-### Google Analytics
-
-```bash
-# Google Analytics tracking ID
-GOOGLE_ANALYTICS_ID=UA-XXXXXXXXX-X
-
-# Google Tag Manager ID
-GOOGLE_TAG_MANAGER_ID=GTM-XXXXXXX
-```
-
-### Hotjar
-
-```bash
-# Hotjar site ID
-HOTJAR_SITE_ID=your-hotjar-site-id
-```
-
-## Security Configuration
-
-### Authentication
-
-```bash
-# JWT secret key
-JWT_SECRET_KEY=your-jwt-secret-key
-
-# Session timeout (in seconds)
-SESSION_TIMEOUT=86400
-
-# Password minimum length
-PASSWORD_MIN_LENGTH=8
-
-# Enable two-factor authentication
-ENABLE_2FA=true
-
-# TOTP issuer name
-TOTP_ISSUER_NAME=Chatwoot
-```
-
-### CORS Configuration
-
-```bash
-# Allowed origins for CORS
-CORS_ORIGINS=https://yourdomain.com,https://www.yourdomain.com
-
-# Enable CORS credentials
-CORS_CREDENTIALS=true
-```
-
-### Content Security Policy
-
-```bash
-# Enable CSP
-ENABLE_CSP=true
-
-# CSP report URI
-CSP_REPORT_URI=/csp-report
-
-# CSP directives
-CSP_DEFAULT_SRC='self'
-CSP_SCRIPT_SRC='self' 'unsafe-inline' 'unsafe-eval'
-CSP_STYLE_SRC='self' 'unsafe-inline'
-```
-
-## Performance Configuration
-
-### Caching
-
-```bash
-# Enable caching
-ENABLE_CACHING=true
-
-# Cache store (memory_store, redis_cache_store)
-CACHE_STORE=redis_cache_store
-
-# Cache namespace
-CACHE_NAMESPACE=chatwoot_cache
-
-# Cache TTL (seconds)
-CACHE_TTL=3600
-```
-
-### Rate Limiting
-
-```bash
-# Enable rate limiting
-ENABLE_RATE_LIMITING=true
-
-# Rate limit store (memory_store, redis_store)
-RATE_LIMIT_STORE=redis_store
-
-# API rate limit (requests per minute)
-API_RATE_LIMIT=100
-
-# Login rate limit (attempts per minute)
-LOGIN_RATE_LIMIT=5
-```
-
-### Asset Configuration
-
-```bash
-# Asset host (for CDN)
-ASSET_HOST=https://cdn.yourdomain.com
-
-# Enable asset compression
-ENABLE_ASSET_COMPRESSION=true
-
-# Asset cache TTL (seconds)
-ASSET_CACHE_TTL=31536000
-```
-
-## Development and Testing
-
-### Development Settings
-
-```bash
-# Enable development features
-ENABLE_DEVELOPMENT_FEATURES=false
-
-# Development email delivery
-DEVELOPMENT_EMAIL_DELIVERY=true
-
-# Development file storage
-DEVELOPMENT_FILE_STORAGE=local
-
-# Enable SQL logging
-ENABLE_SQL_LOGGING=false
-```
-
-### Testing Configuration
-
-```bash
-# Test database URL
-TEST_DATABASE_URL=postgresql://username:password@localhost/chatwoot_test
-
-# Test Redis URL
-TEST_REDIS_URL=redis://localhost:6379/1
-
-# Enable test coverage
-ENABLE_TEST_COVERAGE=true
-
-# Test email delivery
-TEST_EMAIL_DELIVERY=test
-```
-
-## Logging Configuration
-
-### Log Settings
-
-```bash
-# Log level (debug, info, warn, error, fatal)
-LOG_LEVEL=info
-
-# Log format (text, json)
-LOG_FORMAT=text
-
-# Log to stdout
-LOG_TO_STDOUT=true
-
-# Log file path
-LOG_FILE_PATH=/var/log/chatwoot/chatwoot.log
-
-# Log rotation
-LOG_ROTATION=daily
-LOG_RETENTION=30
-```
-
-### Structured Logging
-
-```bash
-# Enable structured logging
-ENABLE_STRUCTURED_LOGGING=true
-
-# Log correlation ID
-LOG_CORRELATION_ID=true
-
-# Log request ID
-LOG_REQUEST_ID=true
-
-# Log user context
-LOG_USER_CONTEXT=true
-```
-
-## Feature Flags
-
-### Experimental Features
-
-```bash
-# Enable experimental features
-ENABLE_EXPERIMENTAL_FEATURES=false
-
-# Feature flags
-FEATURE_FLAG_CONVERSATION_CONTINUITY=true
-FEATURE_FLAG_AUTO_RESOLVE=false
-FEATURE_FLAG_CUSTOM_ATTRIBUTES=true
-FEATURE_FLAG_TEAM_MANAGEMENT=true
-```
-
-## Webhook Configuration
-
-```bash
-# Webhook URL for external integrations
-WEBHOOK_URL=https://your-webhook-endpoint.com/chatwoot
-
-# Webhook secret for verification
-WEBHOOK_SECRET=your-webhook-secret
-
-# Webhook timeout (seconds)
-WEBHOOK_TIMEOUT=30
-
-# Webhook retry attempts
-WEBHOOK_RETRY_ATTEMPTS=3
-```
-
-## Custom Branding
-
-```bash
-# Custom brand name
-BRAND_NAME=Your Company
-
-# Custom logo URL
-BRAND_LOGO_URL=https://yourdomain.com/logo.png
-
-# Custom favicon URL
-BRAND_FAVICON_URL=https://yourdomain.com/favicon.ico
-
-# Custom primary color
-BRAND_PRIMARY_COLOR=#1f93ff
-
-# Custom secondary color
-BRAND_SECONDARY_COLOR=#f0f0f0
-```
-
-## Environment-Specific Examples
-
-### Production Environment
-
-```bash
-# Production .env example
-RAILS_ENV=production
-NODE_ENV=production
-FRONTEND_URL=https://chat.yourcompany.com
-FORCE_SSL=true
-SECRET_KEY_BASE=your-production-secret-key
-
-# Database
-DATABASE_URL=postgresql://chatwoot:secure-password@db.yourcompany.com:5432/chatwoot_production
-
-# Redis
-REDIS_URL=redis://redis.yourcompany.com:6379/0
-
-# Email
-MAILER_SENDER_EMAIL=noreply@yourcompany.com
-SMTP_ADDRESS=smtp.yourcompany.com
-SMTP_PORT=587
-SMTP_USERNAME=noreply@yourcompany.com
-SMTP_PASSWORD=your-smtp-password
-
-# Storage
-ACTIVE_STORAGE_SERVICE=amazon
-S3_BUCKET_NAME=yourcompany-chatwoot
-AWS_ACCESS_KEY_ID=your-aws-key
-AWS_SECRET_ACCESS_KEY=your-aws-secret
-AWS_REGION=us-east-1
-
-# Security
-ENABLE_2FA=true
-ENABLE_RATE_LIMITING=true
-CORS_ORIGINS=https://yourcompany.com
-
-# Monitoring
-SENTRY_DSN=your-sentry-dsn
-NEW_RELIC_LICENSE_KEY=your-newrelic-key
-```
-
-### Development Environment
-
-```bash
-# Development .env example
-RAILS_ENV=development
-NODE_ENV=development
-FRONTEND_URL=http://localhost:3000
-FORCE_SSL=false
-
-# Database
-DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
-
-# Redis
-REDIS_URL=redis://localhost:6379/0
-
-# Email (development)
-MAILER_SENDER_EMAIL=dev@localhost
-EMAIL_DELIVERY_METHOD=test
-
-# Storage (local)
-ACTIVE_STORAGE_SERVICE=local
-
-# Development features
-ENABLE_DEVELOPMENT_FEATURES=true
-ENABLE_SQL_LOGGING=true
-LOG_LEVEL=debug
-```
-
-## Validation and Best Practices
-
-### Required Variables
-
-<Warning>
-These environment variables are required for Chatwoot to function properly:
-- `FRONTEND_URL`
-- `SECRET_KEY_BASE`
-- `DATABASE_URL` or individual database components
-- `REDIS_URL` or individual Redis components
-</Warning>
-
-### Security Best Practices
-
-<Tip>
-**Security Recommendations:**
-- Use strong, unique passwords for all services
-- Enable SSL/TLS for all external connections
-- Use environment-specific secret keys
-- Enable rate limiting and CORS protection
-- Regularly rotate API keys and passwords
-- Use managed services for databases when possible
-</Tip>
-
-### Performance Optimization
+You can generate `SECRET_KEY_BASE` using `rake secret` command from the project root folder. If you dont have rails installed, use `head /dev/urandom | tr -dc A-Za-z0-9 | head -c 63 ; echo ''`.
 
 <Note>
-**Performance Tips:**
-- Adjust `SIDEKIQ_CONCURRENCY` based on your server resources
-- Use Redis for caching and session storage
-- Configure CDN for static assets
-- Enable compression and caching
-- Monitor and adjust database pool sizes
+SECRET_KEY_BASE should be alphanumeric. Avoid special characters or symbols.
 </Note>
 
----
+## Database configuration
 
-This comprehensive environment variables reference covers all aspects of Chatwoot configuration. Customize these settings based on your specific deployment requirements and infrastructure setup. 
+Postgres can be configured in two ways: via `DATABASE_URL` or setting up independent Postgres variables.
+
+### Configure Postgres
+
+Set the `DATABASE_URL` variable with value as Postgres connection URI to connect to the database.
+
+The URI is of the format
+
+```bash
+postgresql://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]
+```
+
+Or you can set the following environment variables to configure Postgres. Replace the values here with yours. Skip this
+if you have configured `DATABASE_URL`.
+
+```bash
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_DATABASE=chatwoot_production
+POSTGRES_USERNAME=admin
+POSTGRES_PASSWORD=password
+```
+
+### Configure Redis
+
+For development, you can use the following URL to connect to Redis. For production, configure your Redis URL.
+
+```bash
+REDIS_URL='redis://127.0.0.1:6379'
+```
+
+To authenticate Redis connections made by the app server and sidekick, if it's protected by a password, use the following environment variable to set the password.
+
+```bash
+REDIS_PASSWORD=
+```
+
+## Configure emails
+
+For development, you don't need an email provider. Chatwoot uses the [letter-opener](https://github.com/ryanb/letter_opener) gem to test emails locally
+
+For production use, please configure the following variables.
+
+```bash
+# could user either `email@yourdomain.com` or `BrandName <email@yourdomain.com>`
+MAILER_SENDER_EMAIL=
+```
+
+and based on your SMTP server the following variables
+
+```bash
+SMTP_ADDRESS=
+SMTP_USERNAME=
+SMTP_PASSWORD=
+SMTP_TLS=
+SMTP_SSL=
+```
+
+### Postfix
+
+Follow these steps if you want to use a selfhosted mail server with Chatwoot. This is the default behavior starting from `v2.12.0` and relies on `SMTP_ADDRESS` environment variable not being set.
+
+```
+sudo apt install -y postfix
+```
+
+Choose internet-site when prompted and enter the domain name you used with Chatwoot setup for `System mail name`.
+
+<Note>
+By default, all major cloud provider have blocked port 25 used for sending emails as part of their spam combat effects. Please raise a support ticket with your cloud provider to enable outbound access on port 25 for this to work. Refer [AWS](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle), [GCP](https://cloud.google.com/compute/docs/tutorials/sending-mail), [Azure](https://learn.microsoft.com/en-us/azure/virtual-network/troubleshoot-outbound-smtp-connectivity) and [DigitalOcean](https://www.digitalocean.com/blog/smtp-restricted-by-default) for more details.
+</Note>
+
+Also please add MX and PTR records for your domain. If your emails are being flagged by `Gmail` and `Outlook`, setup [SPF and DKIM records](https://www.linuxbabe.com/mail-server/setting-up-dkim-and-spf) for your domain as well. This should improve your email reputation.
+
+### Amazon SES
+
+```bash
+SMTP_ADDRESS=email-smtp.<region>.amazonaws.com
+SMTP_AUTHENTICATION=plain
+SMTP_ENABLE_STARTTLS_AUTO=true
+SMTP_USERNAME=<Your SMTP username>
+SMTP_PASSWORD=<Your SMTP password>
+```
+
+### SendGrid
+
+<Info>
+For clarification, the `SMTP_USERNAME` should be set to the literal text apikey—this is not the actual API key. SendGrid uses 'apikey' as the standard username for its services.
+</Info>
+
+```bash
+SMTP_ADDRESS=smtp.sendgrid.net
+SMTP_AUTHENTICATION=plain
+SMTP_DOMAIN=<your verified domain>
+SMTP_ENABLE_STARTTLS_AUTO=true
+SMTP_PORT=587
+SMTP_USERNAME=apikey
+SMTP_PASSWORD=<your Sendgrid API key>
+```
+
+### MailGun
+
+```bash
+SMTP_ADDRESS=smtp.mailgun.org
+SMTP_AUTHENTICATION=plain
+SMTP_DOMAIN=<Your domain, this has to be verified in Mailgun>
+SMTP_ENABLE_STARTTLS_AUTO=true
+SMTP_PORT=587
+SMTP_USERNAME=<Your SMTP username, view under Domains tab>
+SMTP_PASSWORD=<Your SMTP password, view under Domains tab>
+```
+
+### Mandrill
+
+If you would like to use Mailchimp to send your emails, use the following environment variables:
+
+<Note>
+Mandrill is the transactional email service for Mailchimp. You need to enable transactional email and login to mandrillapp.com.
+</Note>
+
+```bash
+SMTP_ADDRESS=smtp.mandrillapp.com
+SMTP_AUTHENTICATION=plain
+SMTP_DOMAIN=<Your verified domain in Mailchimp>
+SMTP_ENABLE_STARTTLS_AUTO=true
+SMTP_PORT=587
+SMTP_USERNAME=<Your SMTP username displayed under Settings -> SMTP & API info>
+SMTP_PASSWORD=<Any valid API key, create an API key under Settings -> SMTP & API Info>
+```
+
+## Configure default language
+
+```bash
+DEFAULT_LOCALE='en'
+```
+
+## Configure storage
+
+Chatwoot uses [active storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) for storing attachments. The default storage option is the local storage on your server.
+
+But you can change it to use any of the cloud providers like amazon s3, microsoft azure, google gcs etc. Refer [configuring cloud storage](/docs/self-hosted/deployment/storage/supported-providers) for additional environment variables required.
+
+```bash
+ACTIVE_STORAGE_SERVICE=local
+```
+
+When `local` storage is used the files are stored under `/storage` directory in the chatwoot root folder.
+
+<Warning>
+It is recommended to use a cloud provider for your chatwoot storage to ensure proper backup of the stored attachments and prevent data loss.
+</Warning>
+
+## Rails Logging Variables
+
+By default, Chatwoot will capture `info` level logs in production. Ref [rails docs](https://guides.rubyonrails.org/debugging_rails_applications.html#log-levels) for the additional log-level options.
+We will also retain 1 GB of your recent logs and your last shifted log file.
+You can fine-tune these settings using the following environment variables
+
+```bash
+# possible values: 'debug', 'info', 'warn', 'error', 'fatal' and 'unknown'
+LOG_LEVEL=
+# value in megabytes
+LOG_SIZE= 1024
+```
+
+## Configure FB Channel
+
+To use FB Channel, you have to create a Facebook app in the developer portal. You can find more details about creating FB channels [here](https://developers.facebook.com/docs/apps/#register)
+
+```bash
+FB_VERIFY_TOKEN=
+FB_APP_SECRET=
+FB_APP_ID=
+```
+
+## Using CDN for asset delivery
+
+With the release v1.8.0, we are enabling CDN support for Chatwoot. If you have a high traffic website, we recommend to setup a CDN for your asset delivery. Read setting up [CloudFront as your CDN](/docs/self-hosted/deployment/performance/cloudfront-cdn) guide.
+
+## Enable new account signup
+
+By default, Chatwoot will not allow users to create an account[multi-tenancy] from the login page. However, if you are setting up a public server, you can enable signup using:
+
+```bash
+ENABLE_ACCOUNT_SIGNUP=true
+```
+
+## Enable direct upload to storage cloud
+
+By default, Chatwoot will upload the files to the application server and then it will push them to the cloud storage. We have introduced the direct upload functionality so that we can upload the file directly to the cloud storage. This has been built according to rails new direct upload functionality documented [here](https://edgeguides.rubyonrails.org/active_storage_overview.html#direct-uploads). Set below environment variable to true to use the direct upload feature.
+
+Make sure to follow [this guide](https://edgeguides.rubyonrails.org/active_storage_overview.html#cross-origin-resource-sharing-cors-configuration) and set the appropriate CORS configuration on your cloud storage after setting `DIRECT_UPLOADS_ENABLED` to true.
+
+```bash
+DIRECT_UPLOADS_ENABLED=true
+```
+
+## Google OAuth
+
+To enable Google OAuth in Chatwoot, you need to provide the client ID, client secret, and callback URL. You can find the instructions to generate the details [here](https://support.google.com/cloud/answer/6158849).
+
+Set the `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` environment variables in your Chatwoot installation using the values you copied from the Google API Console. Set the `GOOGLE_OAUTH_CALLBACK_URL` environment variable to the callback URL you used in the Google API Console. Here's an example of the same
+
+```bash
+GOOGLE_OAUTH_CLIENT_ID=369777777777-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
+GOOGLE_OAUTH_CLIENT_SECRET=ABCDEF-GHijklmnoPqrstuvwX-yz1234567
+GOOGLE_OAUTH_CALLBACK_URL=https://<your-server-domain>/omniauth/google_oauth2/callback
+```
+
+<Warning>
+The callback URL should comply with the format in the example above. This endpoint cannot be changed at the moment.
+</Warning>
+
+After setting these environment variables, restart your Chatwoot server to apply the changes. Now, users will be able to sign in using their Google accounts.
+
+## LogRocket
+
+To enable LogRocket in Chatwoot, you need to provide the project ID from LogRocket. Here are the steps to follow:
+
+1. Open the LogRocket [website](https://logrocket.com/) and create an account or sign in to your existing account. 
+2. After signing in, create a new project in LogRocket by clicking on "Create new project". 
+3. Enter a name for your project, and save the project ID.
+4. Set the `LOG_ROCKET_PROJECT_ID` environment variable in your `.env` file with the project ID you copied from LogRocket. 
+
+```bash
+LOG_ROCKET_PROJECT_ID=abcd12/pineapple-on-pizza
+```
+
+After setting this environment variable, restart your Chatwoot server to apply the changes. Now, LogRocket will start capturing user sessions on your Chatwoot installation. 

developer-docs/self-hosted/configuration/features/email-channel/azure-app-setup.mdx

@@ -0,0 +1,93 @@
+---
+title: Outlook & Microsoft 365 Email
+description: Configure an OAuth app for Outlook & Microsoft 365 emails
+sidebarTitle: Azure App Setup
+---
+
+Microsoft no longer permits the use of username and password to retrieve emails from Outlook & Microsoft 365 accounts. They have deprecated the basic auth option. To enable the Outlook/Microsoft 365 email channel in your self-hosted instance, you must configure an OAuth app.
+
+This guide helps you set up an Entra ID App (formerly Azure Active Directory) and use the credentials in Chatwoot. By doing so, you can authenticate your Outlook/Microsoft 365 account as an email channel.
+
+## Register the app
+
+<Note>
+For a more detailed guide on how to set up the Microsoft Identity platform, please refer to the [here](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
+</Note>
+
+To access the Microsoft Entra Admin Center, go to [entra.microsoft.com](https://entra.microsoft.com/) and log in with your Microsoft account. Once logged in, navigate to the Identity section on the left-hand sidebar. In the Identity section, locate the "Applications" menu and click on "App Registrations" from the submenu. On the "App Registrations" page, click on the "New Registration" option. You will be able to see a page as shown below.
+
+![register-an-app](/self-hosted/images/entra/register-an-app.png)
+
+There are three options for supported account types. Ideally, you only need to select "Accounts in any organizational directory" as Chatwoot is generally used for business emails only. However, if you are connecting a personal account, select the second option. If you are using the applications outside your organization, you would need to register your account as a verified publisher.
+
+To configure a redirect URI with the Web platform, use the following URL: `https://<your-instance-url>/microsoft/callback`. Click on register, and your app will be created. You will see a screen as shown below.
+
+![registration-complete](/self-hosted/images/entra/registration-complete.png)
+
+Save the Application (Client) ID. We will configure this as `AZURE_APP_ID` in Chatwoot later.
+
+## Configure the application
+
+To ensure proper functionality of Chatwoot, we need to configure the permissions and update the token configuration as follows.
+
+### API permissions
+
+Click on the "API Permissions" menu under the "Manage" section. By default, this will have [User.Read](http://user.read/) permission.
+
+Click on the "Add permissions" button and add the following permissions from the Delegated permissions menu on Microsoft Graph APIs.
+
+- **email**: To view the user's email address.
+- **profile**: To view the name and picture etc.
+- **offline_access**: To retrieve the emails even when you are not using the application.
+- **SMTP.Send, Mail.Send:** Send emails using the SMTP AUTH when you reply to customers from the Chatwoot dashboard.
+- **IMAP.AccessAsUser.All, Mail.ReadWrite:** Read and write access to mailboxes via IMAP.
+- **openid:** Sign users in
+
+![permissions](/self-hosted/images/entra/permissions.png)
+
+### Token Configuration
+
+Now, let's proceed to the Token Configuration to set up "optional claims". Optional claims are a feature in Entra ID that enables you to specify additional pieces of information (claims) to include in the security tokens issued to the application.
+
+In Chatwoot, we use optional claims to minimize duplicate calls and retrieve some information in advance. Click on "Add optional claim" and add the following claims to the application.
+
+![optional-claims.png](/self-hosted/images/entra/optional-claims.png)
+
+### Configure Client Secret
+
+Go to the Certificates & Secrets section to create a Client Secret. Click on the "New Client Secret" button and provide a description. You can also select an expiry time.
+
+<Warning>
+Remember that you will need to regenerate the secret and update it in the Chatwoot environment variables once it expires.
+</Warning>
+
+![add-client-secret](/self-hosted/images/entra/add-client-secret.png)
+
+After clicking on the Add button, a client secret will be generated as shown below.
+
+![client-secret-value](/self-hosted/images/entra/client-secret-value.png)
+
+Save the value somewhere save as you cannot see it after refreshing the page. This would be used `AZURE_APP_SECRET` in Chatwoot.
+
+## Configure environment variables in Chatwoot
+
+After creating the Entra application, you need to configure the application credentials in Chatwoot. There are 2 variables that you need to configure, as shown in the steps above.
+
+- **AZURE_APP_ID:** As seen in the register the app step, use the Application (Client) ID here.
+- **AZURE_APP_SECRET:** Use the value obtained in the step configuring the client secret.
+
+After updating the environment variables, restart the Chatwoot service for the changes to take effect. Now, verify if the channel is enabled in the Inbox creation flow. If everything is configured properly, you will see "Microsoft" listed as an email provider in the flow.
+
+![microsoft-channel](/self-hosted/images/entra/microsoft-channel.png)
+
+Voila! That's it you can now receive the emails in your Chatwoot instance.
+
+## Thoughts on multi-tenancy and going for production
+
+Note that the setup will not work for other emails under a different tenant until you have completed the Microsoft publisher verification process. During the authorization prompt, you will see "unverified" until the application is verified for production.
+
+To test the changes before the app is verified for production, use the Entra ID app registration email address in the Chatwoot channel.
+
+Publisher verification provides app users and organization admins with information about the authenticity of the developer's organization that publishes an app integrating with the Microsoft identity platform. If an app has a verified publisher, it means that Microsoft has verified the authenticity of the organization that publishes the app.
+
+Read the publishing guidelines [here](https://learn.microsoft.com/en-us/entra/identity-platform/howto-convert-app-to-be-multi-tenant). 

developer-docs/self-hosted/configuration/features/email-channel/conversation-continuity-using-sendgrid.mdx

@@ -0,0 +1,83 @@
+---
+title: SendGrid Guide
+description: Guide to setting up Conversation Continuity with SendGrid
+sidebarTitle: SendGrid Guide
+---
+
+This doc will help you set up [Conversation continuity](https://www.chatwoot.com/docs/self-hosted/configuration/features/email-channel/conversation-continuity) with SendGrid.
+
+## Installation
+
+This example is based on a Heroku installation of Chatwoot, and using SendGrid for outgoing email. For more information about installing Chatwoot, go [here](https://www.chatwoot.com/docs/self-hosted#deployment).
+
+## Configuring inbound reply emails
+
+Firstly, we need to tell our Chatwoot instance what mailer we're using to handle incoming emails. We do that with a config var. Go to your Heroku dashboard, click on your Chatwoot instance and click settings.
+
+![Screenshot_95](https://user-images.githubusercontent.com/34171640/128574548-7f2d6521-e79d-47bc-8f8d-6e8d7ca28ae1.png)
+
+Then scroll until you see two blank fields with an add button. There, enter:
+
+```javascript
+RAILS_INBOUND_EMAIL_SERVICE=sendgrid
+```
+
+![Screenshot_96](https://user-images.githubusercontent.com/34171640/128575349-493efe35-86b9-48ea-84ff-cab7020fd832.jpg)
+
+Next, we're going to set a password. We'll use this later on with SendGrid. For this example, we'll use something simple - like ```potatosalad```, but like all passwords - you should always use a secure mixture of letters, numbers and symbols.
+
+![Screenshot_97](https://user-images.githubusercontent.com/34171640/128575151-9a3fe484-7f1d-43f9-968f-c9841c4d10d1.jpg)
+
+## SendGrid
+
+Now we're going to set up the domain we're using for inbound emails. Because you're most likely going to have an email service like Google Workspace or Microsoft 365 for Business, you should use a subdomain for your inbound emails to Chatwoot.
+
+For example, let's say we used support.example.com as our domain. In this instance, we'd add an MX record pointing support.example.com to ```mx.sendgrid.net``` with a priority of ```10```.
+
+You should wait a while (usually an hour will do). You can use [mxtoolbox.com](https://mxtoolbox.com) to check if the MX record has been propogated. If you see something like this, you can move onto the next step:
+
+![Screenshot_98](https://user-images.githubusercontent.com/34171640/128576943-7f8267b5-d81a-4583-8a40-4941c7700d2b.png)
+
+Now, go to the SendGrid dashboard at [app.sendgrid.com](https://app.sendgrid.com). Select Settings, and Inbound Parse.
+
+![Screenshot_99](https://user-images.githubusercontent.com/34171640/128578295-f62fed61-3401-4a4b-a564-f61f282b8c07.png)
+
+Then click "Add Host & URL".
+
+![Screenshot_100](https://user-images.githubusercontent.com/34171640/128581269-2728e8d4-9c5f-4361-ba4f-3543a0f9a9d8.png)
+
+**Receiving Subdomain** should be the domain you set up the MX record for earlier.
+
+![Screenshot_101](https://user-images.githubusercontent.com/34171640/128581298-1271781f-6985-48b2-9ef9-e210ed5b6ecb.png)
+
+Then add your **Destination URL**. Your Destination URL should look something like this:
+
+```https://actionmailbox:potatosalad@chatwoot.example.com/rails/action_mailbox/sendgrid/inbound_emails```
+
+``potatosalad`` is the password we set earlier, and ``chatwoot.example.com`` is the URL of our Chatwoot instance. Everything else should stay the same.
+
+![Screenshot_102](https://user-images.githubusercontent.com/34171640/128581410-52834258-e826-4c2f-9868-a6c21c9a1ff9.png)
+
+<Warning>
+Make sure to check "POST the raw, full MIME message". In order to function correctly, Action Mailbox needs the raw MIME message.
+</Warning>
+
+![Screenshot_103](https://user-images.githubusercontent.com/34171640/128581457-ff5e385c-4d7e-4ebb-8f87-28fd5a243798.png)
+
+## Setting the inbound domain variable in Heroku
+
+Finally, we need to tell our Chatwoot installation what domain we're using with SendGrid.
+
+Your variable should look like this:
+
+```javascript
+MAILER_INBOUND_EMAIL_DOMAIN=support.example.com
+```
+
+You should change ``support.example.com`` to the domain you used with SendGrid.
+
+![Screenshot_104](https://user-images.githubusercontent.com/34171640/128582096-766a2835-04b9-47f0-8662-c602742e11f9.jpg)
+
+## Next steps
+
+You're done! Next, you should [enable the email channel](https://www.chatwoot.com/docs/self-hosted/configuration/features/email-channel/setup). 

developer-docs/self-hosted/configuration/features/email-channel/conversation-continuity.mdx

@@ -0,0 +1,124 @@
+---
+title: Conversation Continuity
+description: Configure Conversation Continuity with Email
+sidebarTitle: Conversation Continuity
+---
+
+## Conversation continuity
+
+![101382999-9b0abf00-38de-11eb-845d-1bb1f52306df@2x](https://user-images.githubusercontent.com/73185/109548415-a1ca5c00-7af2-11eb-9b1d-fd636cf5189c.png)
+
+## Configuring inbound reply emails
+
+<Note>
+Conversation Continuity requires your chatwoot installation to have a [cloud storage configured](/docs/self-hosted/deployment/storage/supported-providers)
+</Note>
+
+There are a couple of email infrastructure service providers to handle the incoming emails that we support at the moment. They are
+Sendgrid, Mandrill, Mailgun, Exim, Postfix, Qmail and Postmark.
+
+Step 1 : We have to set the inbound email service used as an environment variable.
+
+```bash
+# Set this to appropriate ingress service for which the options are :
+# "relay" for Exim, Postfix, Qmail
+# "mailgun" for Mailgun
+# "mandrill" for Mandrill
+# "postmark" for Postmark
+# "sendgrid" for Sendgrid
+RAILS_INBOUND_EMAIL_SERVICE=relay
+```
+If you wish to use the same local relaying server (for example postfix) to send outbound mail as you are using to relay inbound messages and you opt not to use an external authentication mechanism like SASL which may be the case if the server is handling it own emails only. The upstream SMTP platform Action Mailer attempts to use a default authentication method if the configuration options `SMTP_AUTHENTICATION`, `SMTP_USERNAME` and `SMTP_PASSWORD` are present in your .env file. To disable this behaviour either comment out or delete these lines from your configuration. This will allow you to send outbound messages from the same server without a premium service. Please note many ISP's do not allow email servers to be run from their networks. It is your responsibility to ensure adequate access control preventing yourself becoming an open relay and ensuring your server is able to get past your recipients spam filters for example SPF, DKIM & DMARC dns records.
+
+This configures the ingress service for the app. Now we have to set the password for the ingress service that we use.
+
+```bash
+# Use one of the following based on the email ingress service
+
+# Set this if you are using Sendgrid, Exim, Postfix, Qmail or Postmark
+RAILS_INBOUND_EMAIL_PASSWORD=
+# Set this if you are Mailgun
+MAILGUN_INGRESS_SIGNING_KEY=
+# Set this if you are Mandrill
+MANDRILL_INGRESS_API_KEY=
+```
+
+### Mailgun
+If you are using Mailgun as your email service, in the Mailgun dashboard configure it to forward your inbound emails to `https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime` if `example.com` is where you have hosted the application.
+
+#### Getting Mailgun Ingress Key
+![mailgun-ingress-key](/self-hosted/images/mailgun-ingress-key.gif)
+
+### Sendgrid
+
+Ensure to set up the proper MX records for `your-domain.com` pointed towards Sendgrid
+
+Configure SendGrid Inbound Parse to forward inbound emails to forward your inbound emails to `/rails/action_mailbox/sendgrid/inbound_emails` with the username `actionmailbox` and the password you previously generated. If the deployed application was hosted at `example.com`, you can configure the following URL as the forward route.
+
+```bash
+https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails
+```
+
+When configuring your SendGrid Inbound Parse webhook, be sure to check the box labeled "Post the raw, full MIME message." Action Mailbox needs the raw MIME message to work.
+
+### Mandrill
+If you are configuring Mandrill as your email service, configure Mandrill to route your inbound emails to `https://example.com/rails/action_mailbox/mandrill/inbound_emails` if `example.com` is where you have hosted the application.
+
+If you want to know more about configuring other services visit [Action Mailbox Basics](https://edgeguides.rubyonrails.org/action_mailbox_basics.html#configuration)
+
+### IMAP via getmail
+Chatwoot receives inbound emails through the [Action Mailbox](https://edgeguides.rubyonrails.org/action_mailbox_basics.html) feature of Ruby on Rails. Action Mailbox supports various 'ingresses' by default. They are defined in [here](https://github.com/rails/rails/blob/main/actionmailbox/lib/tasks/ingress.rake) and can be executed through `bin/rails`. For example
+```bash
+cat my_incoming_message | ./bin/rails action_mailbox:ingress:postfix \
+  RAILS_ENV=production \
+  URL=http://localhost:3000/rails/action_mailbox/postfix/inbound_emails \
+  INGRESS_PASSWORD=...
+```
+would import the contents of the file `my_incoming_message` into a Chatwoot instance running on `localhost` - assuming `my_incoming_message` contains an [RFC 822](https://datatracker.ietf.org/doc/html/rfc822) compliant message.
+
+The ingress tasks provided by Action Mailbox are a thin layer around an HTTP endpoint exposed by Action Mailbox. An alternative to using those tasks is to talk to the http endpoint directly. The following script achieves the same.
+```bash
+INGRESS_PASSWORD=...
+URL=http://localhost:3000/rails/action_mailbox/relay/inbound_emails
+
+curl -sS -u "actionmailbox:$INGRESS_PASSWORD" \
+ -A "Action Mailbox curl relayer" \
+ -H "Content-Type: message/rfc822" \
+ --data-binary @- \
+ $URL
+```
+
+The popular mail retrieval system [getmail6](https://github.com/getmail6/getmail6) can be used to fetch mails and import them into Chatwoot. If the curl script above is stored in `/home/chatwoot/bin/import_mail_to_chatwoot`, a configuration for doing so from an IMAP inbox is as follows.
+```
+[retriever]
+type = SimpleIMAPSSLRetriever
+server = ...
+username = ...
+password = ...
+
+[destination]
+type = MDA_external
+path = /home/chatwoot/bin/import_mail_to_chatwoot
+
+[options]
+verbose = 0
+read_all = false
+delete = false
+delivered_to = false
+received = false
+message_log = /home/chatwoot/logs/import_imap.log
+message_log_syslog = false
+message_log_verbose = true
+```
+
+For mail to be imported you'll need to execute `getmail` regularly, for example using a cron job. For `IMAP` you can also run it constantly using `getmail --idle INBOX`, though that will need some care to deal with interrupted connections, etc.
+
+## Configure inbound email domain environment variable
+
+Add the following environment variable with the value `your-domain.com`, where `your-domain.com` is the domain for which you set up MX records in the previous step.
+
+```bash
+MAILER_INBOUND_EMAIL_DOMAIN=
+```
+
+After finishing the set up, the mail sent from Chatwoot will have a `replyto:` in the following format `reply+<random-hex>@<your-domain.com>` and reply to those would get appended to your conversation. 

developer-docs/self-hosted/configuration/features/email-channel/email-channel-setup.mdx

@@ -0,0 +1,38 @@
+---
+title: Email Channel Setup
+description: Setting up Email Channel in Chatwoot
+sidebarTitle: Email Channel Setup
+---
+
+## Configure Email Channel
+
+<Note>
+Email channels require [conversation continuity configured](/docs/self-hosted/configuration/features/email-channel/conversation-continuity)
+</Note>
+
+1. Enable `channel_email` (Login to rails console and execute the following)
+
+```bash
+account = Account.find(1)
+account.enabled_features // This would list enabled features.
+account.enable_features('channel_email')
+account.save!
+```
+
+2. Now head over to inboxes page and create an email inbox with the support email as care@your-domain.com
+![mail-channel-step1](/self-hosted/images/mail-channel-step1.png)
+3. Now Add Agents who can have access to the email channel box.
+4. Now you will get the email channel box address in the last step.
+![mail-channel-step2](/self-hosted/images/mail-channel-step2.png)
+5. Now create a forward rule in your care@your-domain.com inbox to forward emails to the address obtained at inbox creation step.
+![set-forwarder-email](/self-hosted/images/set-forwarder-email.png)
+6. You should be able to receive emails in your newly created email inbox in chatwoot.
+![mail-channel-box](/self-hosted/images/mail-channel-box.png)
+
+### Sendgrid
+
+You can send out emails only from a verified email address in SendGrid. For sending emails from wildcard domain, do verification at domain level instead of individual email.
+
+### Testing On Local
+
+You can visit `http://localhost:3000/rails/conductor/action_mailbox/inbound_emails/new` to send inbound mails from local to chatwoot inbox. 

developer-docs/self-hosted/configuration/features/email-channel/google-workspace-setup.mdx

@@ -0,0 +1,64 @@
+---
+title: Google Workspace
+description: Configure an OAuth app for Gmail
+sidebarTitle: Google Workspace
+---
+
+At present, Gmail integration operates through [less-secure](https://support.google.com/accounts/answer/6010255?hl=en) apps. However, as of June 15, 2024, Google Workspace will [cease to support](https://workspaceupdates.googleblog.com/2023/09/winding-down-google-sync-and-less-secure-apps-support.html) these less-secure apps. This will affect the Gmail integration in Chatwoot. To ensure that your Gmail integration continues to work, you will need to set up an OAuth app in Google Workspace.
+
+<Note>
+Existing setups will continue to work until September 30, 2024. However, we recommend setting up an OAuth app as soon as possible to avoid any disruptions.
+</Note>
+
+This guide will walk you through the process of setting up an OAuth app in Google Workspace.
+
+## Register the app
+
+To enable Google OAuth in Chatwoot, you need to provide the client ID, client secret, and callback URL. You can find the instructions to generate these details [here](https://support.google.com/cloud/answer/6158849). Once you have followed these steps, you will be able to get a Client ID and Secret.
+
+![register-an-app](/self-hosted/images/google/oauth-app-setup.png)
+
+Use the callback URL `https://<your-instance-url>/google/callback` when registering the app. This URL is used to redirect the user back to the Chatwoot instance after authentication.
+
+Set the `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` environment variables in your Chatwoot installation using the values you copied from the Google API Console.
+
+```bash
+GOOGLE_OAUTH_CLIENT_ID=369777777777-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
+GOOGLE_OAUTH_CLIENT_SECRET=ABCDEF-GHijklmnoPqrstuvwX-yz1234567
+```
+
+<Note>
+If you have already setup [Google OAuth login flow](https://www.chatwoot.com/docs/self-hosted/configuration/environment-variables#google-oauth) You can use the same app, by simply adding the new callback URL. **Do not remove the previous callback URL.**
+</Note>
+
+After setting these environment variables, restart your Chatwoot server to apply the changes. Now, users will be able to sign in using their Google accounts.
+
+You will notice that the app you are using is in testing mode; we will cover that later in the guide. For now, you can ignore it.
+
+## Configure the application
+
+To fetch the emails from the client inbox, you need to configure the correct scopes. The following scopes are required:
+
+- `https://mail.google.com/`: To read, send, delete, and manage your email.
+- `email`: To view the user's email address.
+- `profile`: To view the name and picture etc.
+
+You can configure the scopes in the Google API Console by following the steps below:
+
+1. Go to the [Google API Console](https://console.developers.google.com/).
+2. Select the project you created earlier.
+3. Click on the "OAuth consent screen" tab and click on the "Edit App" button.
+4. Add the required scopes in the "Scopes for Google APIs" section.
+5. Click on the "Save" button.
+
+Here's a demo showing how to add the `https://mail.google.com/` scope:
+
+![Demo add scope](/self-hosted/images/google/add-scope-demo.gif)
+
+## Publishing the app
+
+If you're using Chatwoot within an organization with fewer than 100 users, you can continue to use the app in testing mode. However, if you're using Chatwoot in an organization with more than 100 users or using the app to serve multiple clients, you will need to publish the app to make it available to all users.
+
+To publish the app, you need to go through the verification process since we use a restricted scope. You can find the instructions to verify the app [here](https://support.google.com/cloud/answer/9110914).
+
+It's important to note that the verification process can take a few days to complete. Once the app is verified, you can publish it and make it available to all users. 

developer-docs/self-hosted/configuration/help-center.mdx

@@ -0,0 +1,52 @@
+---
+title: Help Center
+description: Set up a public-facing help center portal with custom domain and SSL certificate
+sidebarTitle: Help Center
+---
+
+Help center allows you to create a portal and add articles from the chatwoot app dashboard. You can point to these help center portal articles from your main site and display them as your public-facing help center.
+
+## How to get SSL certificate for your custom domain
+
+### Create a Portal in Chatwoot's dashboard
+
+Follow these step to create your Portal. Refer to [this guide.](https://www.chatwoot.com/hc/user-guide/articles/1677861202-how-to-setup-a-help-center)
+
+### Point your custom domain to your Chatwoot domain
+
+1. Go to your DNS provider and add a new CNAME record.
+   - For the above example, add docs as a CNAME record and point it to the your selfhosted chatwoot domain(FRONTEND_URL).
+
+2. This will ensure that your CNAME record points to the selfhosted Chatwoot installation. For your custom domain, we have your portal information. In this case, `docs.example.com`
+
+### Setting up SSL
+
+1. Use certbot to generate SSL certificates for your custom domain.
+
+```bash
+certbot certonly --agree-tos --nginx -d "docs.example.com"
+```
+
+2. Create a new nginx config to route requests to this domain to Chatwoot. Make a copy of `/etc/nginx/sites-available/nginx_chatwoot.conf` and make necessary changes for the new domain.
+
+3. Restart nginx server.
+
+```bash
+sudo systemctl restart nginx
+```
+
+Voila!
+
+`docs.yourdomain.com` is live with a secure connection, and your portal data is visible.
+
+### How does this work?
+
+These are the engineering details to understand `How does docs.yourdomain.com` gets the portal data with SSL certificate.
+
+1. `docs.yourdomain.com` resolves by customers nameserver and redirects to your Chatwoot domain.
+2. Chatwoot check for the portal record with custom-domain `docs.yourdomain.com`
+3. Redirects to the portal records for the domain `docs.yourdomain.com`
+
+Yaay!!
+
+Now you can have your own help-center, product-documentation related portal saved at Chatwoot dashboard and served at your domain with SSL certificate. 

developer-docs/self-hosted/configuration/integrations/facebook-channel-setup.mdx

@@ -0,0 +1,163 @@
+---
+title: Setting Up Facebook
+description: Configure Facebook Messenger integration for Chatwoot
+sidebarTitle: Facebook
+---
+
+To use Facebook Channel, you have to create a Facebook app in the developer portal. You can find more details about creating Facebook apps [here](https://developers.facebook.com/docs/apps/#register).
+
+## Prerequisites
+
+1. A valid facebook account.
+2. A valid facebook page.
+
+## Register A Facebook App
+
+1. Go to [Facebook developer portal](https://developers.facebook.com/apps/) and click on the "Create App" button
+
+![facebook_create_app](/self-hosted/images/facebook/facebook-create-app.png)
+
+2. Select the option "Other".
+
+![facebook_other_app](/self-hosted/images/facebook/facebook_other_app.png)
+
+3. For the app type, choose "Business".
+
+![facebook_business](/self-hosted/images/facebook/facebook_business.png)
+
+3. Enter basic details like the app name and email.
+
+![facebook_business_details](/self-hosted/images/facebook/facebook_business_details.png)
+
+Once you register your Facebook App, you will have to obtain the `App Id` and `App Secret`. These values will be available in the app settings and will be required while setting up Chatwoot environment variables.
+
+![facebook_app_id](/self-hosted/images/facebook/facebook_app_id.png)
+
+## Configuring the Environment Variables in Chatwoot
+
+Configure the following Chatwoot environment variables with the values you obtained during the Facebook app setup. The `FB_VERIFY_TOKEN` should be a unique and secure string that you provide when configuring the Facebook app. Generate a random string and set it as the `FB_VERIFY_TOKEN`. Facebook will include this string in all verification requests.
+
+Restart the Chatwoot server after updating the environment variables
+
+```bash
+FB_VERIFY_TOKEN=
+FB_APP_SECRET=
+FB_APP_ID=
+```
+
+## Configure Facebook Login
+
+1. Add the Facebook Login product via the Facebook app dashboard.
+
+![facebook_app_login](/self-hosted/images/facebook/facebook_app_login.png)
+
+2. Enable `Web OAuth Login`, `Login with Javascript SDK` and add your self-hosted domain to the `Allowed Domains for the JavaScript SDK` input.
+
+![facebook_sdk_login](/self-hosted/images/facebook/facebook_sdk_login.png)
+
+## Configure the Facebook App
+
+1. In the app settings, add your `Chatwoot installation domain` as your app domain.
+
+![facebook_app_domain](/self-hosted/images/facebook/facebook_app_domain.png)
+
+2. In the products section in your app settings page, Add "Messenger"
+
+![facebook_messenger_product](/self-hosted/images/facebook/facebook_messenger_product.png)
+
+3. Go to the Messenger settings and configure the call back URL
+
+![Alt text](/self-hosted/images/facebook/facebook_messenger_section.png)
+
+4. Provide the Callback URL as `{your_chatwoot_installation_url}/bot` and the Verify token as `FB_VERIFY_TOKEN` from your environment variable.
+
+![facebook_callback_url](/self-hosted/images/facebook/facebook_callback_url.png)
+
+5. Head over to Chatwoot and create a Messenger inbox. Choose a page for which your Facebook developer account has admin access to. Please refer to this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677778588-how-to-setup-a-facebook-channel) for more details on creating a Messenger inbox in Chatwoot.
+
+## Testing the Facebook channel
+
+Until the application is approved for production, Facebook wouldn't send the new messages on your page to Chatwoot.
+
+To test the changes until the app is approved for production. Follow the steps
+
+1. Head over to the messenger section in your app settings page, in Facebook developers.
+
+![facebook_messenger_settings](/self-hosted/images/facebook/facebook_messenger_settings.png)
+
+2. Click `Add or remove pages` and connect the page which you choose while creating the Chatwoot Messenger inbox.
+
+![facebook_callback_pages](/self-hosted/images/facebook/facebook_callback_pages.png)
+
+3. After connecting the pages, Click on `Add subscriptions` from the connected page.
+
+![facebook_page_config](/self-hosted/images/facebook/facebook_page_config.png)
+
+4. Subscribe to the following fields and save the subscription.
+
+```
+messages
+messaging_postbacks
+message_deliveries
+message_reads
+message_echoes
+```
+
+![facebook_page_subscription](/self-hosted/images/facebook/facebook_page_subscription.png)
+
+4. Send a message to the connected page from your Facebook account and it should appear in Chatwoot now.
+
+## Going into production.
+
+Before you can start using your Facebook app in production, you will have to get it verified by Facebook. Refer to the [docs](https://developers.facebook.com/docs/apps/review/) on getting your app verified.
+
+Obtain advanced access to the required permissions mentioned below for your Facebook app
+
+```
+pages_messaging
+pages_show_list
+pages_manage_metadata
+business_management
+pages_read_engagement
+```
+
+<Warning>
+Make sure your facebook app subscription version is 17.0, we have updated the FB subscription with the latest version, so change the permission subscription version under the facebook app webhooks option.
+</Warning>
+
+## Developing or Testing Facebook Integration in your machine
+
+Install [ngrok](https://ngrok.com/docs) on your machine. This will be required since Facebook Messenger API's will only communicate via https.
+
+```bash
+brew cask install ngrok
+```
+
+Configure ngrok to route to your Rails server port.
+
+```bash
+ngrok http 3000
+```
+
+Go to the Facebook developers page and navigate into your app settings. In the app settings, add `localhost` as your app domain.
+In the Messenger settings page, configure the callback url with the following value.
+
+```bash
+{your_ngrok_url}/bot
+```
+
+Update verify token in your Chatwoot environment variables.
+
+You will also have to add a Facebook page to your `Access Tokens` section in your Messenger settings page.
+Restart the Chatwoot local server. Your Chatwoot setup will be ready to receive Facebook messages.
+
+## Facebook API version
+
+We support facebook API version v13.0 going forward, which you can update in the facebook app advanced settings.
+![fb_api_version](/self-hosted/images/facebook/fb_api_version.png)
+
+## Test your local Setup
+
+1. After finishing the set-up above, [create a Facebook inbox](https://www.chatwoot.com/hc/user-guide/articles/1677778588-how-to-setup-a-facebook-channel) after logging in to your Chatwoot Installation.
+2. Send a message to your page from Facebook.
+3. Wait and confirm incoming requests to `/bot` endpoint in your ngrok screen. 

developer-docs/self-hosted/configuration/integrations/instagram-channel-setup.mdx

@@ -0,0 +1,219 @@
+---
+title: Instagram via Facebook Login
+description: Set up Instagram integration using Facebook Login authentication
+sidebarTitle: Instagram via Facebook Login
+---
+
+<Note>
+We recommend Instagram Business Login as the preferred authentication method, as it provides simpler configuration and a better developer experience. Please refer to this [guide](./instagram-via-instagram-business-login) for more details. We will be stopping the support for Instagram via Facebook Login in the future from v4.1 onwards.
+</Note>
+
+## Prerequisites
+
+1. A valid facebook account.
+2. A valid facebook page.
+3. A valid instagram professional account.
+
+## Register A Facebook App
+
+To use Instagram Channel, you have to create a Facebook app in the developer portal. You can find more details about creating Facebook developer app [here](./facebook-channel-setup).
+
+1. Click on the "Create App" button
+
+![facebook_create_app](/self-hosted/images/facebook/facebook-create-app.png)
+
+2. Select the option "Other".
+
+![facebook_other_app](/self-hosted/images/facebook/facebook_other_app.png)
+
+3. For the app type, choose "Business"
+
+![facebook_business](/self-hosted/images/facebook/facebook_business.png)
+
+3. Enter basic details like the app name and email.
+
+![facebook_business_details](/self-hosted/images/facebook/facebook_business_details.png)
+
+Once you register your Facebook App, you will have to obtain the `App Id` and `App Secret`. These values will be available in the app settings and will be required while setting up Chatwoot environment variables.
+
+![facebook_app_id](/self-hosted/images/facebook/facebook_app_id.png)
+
+## Configuring the Environment Variables in Chatwoot
+
+Configure the following Chatwoot environment variables with the values you obtained during the Facebook app setup. The `IG_VERIFY_TOKEN` should be a unique and secure string that you provide when configuring the Instagram app.
+
+Restart the Chatwoot server after updating the environment variables
+
+```bash
+IG_VERIFY_TOKEN=
+FB_APP_SECRET=
+FB_APP_ID=
+```
+
+## Configure the Facebook App
+
+1. In the app settings, add your "Chatwoot installation domain" as your app domain.
+![facebook_app_domain](/self-hosted/images/facebook/facebook_app_domain.png)
+2. Add the "Instagram Graph API" product via the Facebook app dashboard.
+![instagram_product](/self-hosted/images/instagram/instagram_product.png)
+3. Go to the app settings and select "Webhooks". From there, choose Instagram and click on the "Subscribe to this object" button.
+![instagram_webhooks](/self-hosted/images/instagram/instagram_webhooks.png)
+4. Provide the Callback URL as `{your_Chatwoot_installation_url}/webhooks/instagram` and the Verify token as `IG_VERIFY_TOKEN` from your environment variable.
+![instagram_webhook_url](/self-hosted/images/instagram/instagram_webhook_url.png)
+
+## Connect the facebook page with instagram account
+
+1. Go to [Facebook pages](https://www.facebook.com/pages/?category=your_pages) and select your page and open the settings
+
+![facebook_page_settings](/self-hosted/images/instagram/facebook_page_settings.png)
+
+2. Go to "Linked accounts" and connect your instagram professional account.
+
+![facebook_connect_instagram](/self-hosted/images/instagram/facebook_connect_instagram.png)
+
+3. Select the option "Business"
+![instagram_connect_facebook](/self-hosted/images/instagram/instagram_connect_facebook.png)
+
+4. Select the instgram account category
+
+![select_category_instagram](/self-hosted/images/instagram/select_category_instagram.png)
+
+5. If everything is okay, you will see the message "Instagram connected."
+
+![instagram_connect_success](/self-hosted/images/instagram/instagram_connect_success.png)
+
+## Create Instagram Inbox in Chatwoot
+
+1. Head over to Chatwoot and create a Messenger inbox. Please refer to this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677829420-how-to-setup-an-instagram-channel) for more details on creating a Messenger inbox in Chatwoot.
+
+So whenever you receive any message on Instagram, it will redirect to your Facebook page.
+
+## Testing the Instagram channel
+
+Until the application is approved for production, Facebook wouldn't send the new messages on your instagram to Chatwoot.
+To test the changes until the app is approved for production. Follow the steps
+
+1. Create a Test app for your app.
+
+![facebook_instagram_test](/self-hosted/images/instagram/facebook_instagram_test.png)
+
+2. Add the `Instagram Graph API` product via the Facebook app dashboard.
+![instagram_product](/self-hosted/images/instagram/instagram_product.png)
+
+3. Go to the app settings and select "Webhooks". From there, choose Instagram and click on the "Subscribe to this object" button.
+![instagram_webhooks](/self-hosted/images/instagram/instagram_webhooks.png)
+
+4. Provide the Callback URL as `{your_chatwoot_installation_url}/webhooks/instagram` and the Verify token as `IG_VERIFY_TOKEN` from your environment variable.
+![instagram_webhook_url](/self-hosted/images/instagram/instagram_webhook_url.png)
+
+5. Open the test app and add extra product for the test app: Instagram Basic Display
+
+![instagram_basic_display](/self-hosted/images/instagram/instagram_basic_display.png)
+
+6. In the app settings, add the platform "Website" and give `Site URL` as your installation URL.
+
+![instagram_app_platform](/self-hosted/images/instagram/instagram_app_platform.png)
+
+7. Head over to the Instagram Basic Display section and create a new app.
+
+![instagram_basic_display_settings](/self-hosted/images/instagram/instagram_basic_display_settings.png)
+
+8. Add Instagram Testers by clicking "Add or Remove Instagram Testers" button.
+
+![instagram_testers](/self-hosted/images/instagram/instagram_testers.png)
+
+9. Make sure that you have selected the role `Instagram Tester` while creating a new tester.
+
+![instagram_tester_list](/self-hosted/images/instagram/instagram_tester_list.png)
+
+10. Click on Edit subscriptions under Webhook > Instagram and subscribe to the following,
+
+```
+message_reactions
+messages
+messaging_seen
+```
+
+![instagram_subscription](/self-hosted/images/instagram/instagram_subscription.png)
+
+<Note>
+You should do this step for both normal and test apps.
+</Note>
+
+1. Head over to Chatwoot and create a Messenger inbox. Please refer to this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677829420-how-to-setup-an-instagram-channel) for more details on creating a Messenger inbox in Chatwoot.
+2. Send a message to the connected Instagram account from Instagram Testers, and it should appear in Chatwoot now
+
+## Going into production.
+
+Before you can start using your Facebook app in production, you will have to get it verified by Facebook. Refer to the [docs](https://developers.facebook.com/docs/messenger-platform/instagram/app-review) on getting your app verified.
+
+Obtain advanced access to the required permissions mentioned below for your Facebook app
+```
+instagram_manage_messages
+instagram_basic
+pages_show_list
+pages_manage_metadata
+pages_messaging
+business_management
+```
+
+<Note>
+If your facebook app's version is more than 7.0 then you will need extra permission according to facebook's updated policy. Make sure you get permission for.
+```
+pages_read_engagement
+```
+</Note>
+
+## Developing or Testing Facebook Integration in your machine
+
+Install [ngrok](https://ngrok.com/docs) on your machine. This will be required since Facebook Messenger APIs will only communicate via https.
+
+```bash
+brew cask install ngrok
+```
+
+Configure ngrok to route to your Rails server port.
+
+```bash
+ngrok http 3000
+```
+
+Go to the Facebook developers page and navigate into your app settings. Add `localhost` as your app domain and add a privacy policy URL in the app settings.
+In the Webhook > Instagram settings shown in the above image, configure the callback url with the following value.
+
+```bash
+{your_ngrok_url}/webhooks/instagram
+```
+
+Update verify token in your Chatwoot environment variables.
+
+You will also have to add a Facebook page to your `Access Tokens` section in your Messenger settings page.
+Restart the Chatwoot local server. Then, your Chatwoot setup will be ready to receive Facebook messages.
+
+## Test your local Setup
+
+1. After finishing the setup above, [create a Messenger inbox](https://www.chatwoot.com/hc/user-guide/articles/1677778588-how-to-setup-a-facebook-channel) after logging in to your Chatwoot Installation.
+2. Send a message to your Facebook Page from your Instagram account.
+3. Wait and confirm incoming requests to `/webhooks/instagram` endpoint in your ngrok screen.
+4. You can also verify your callback URL by clicking on Test for the subscribed Instagram fields.
+Go to webhook Instagram and click on Test with `v11.0`
+![subscribe](/self-hosted/images/instagram/subscribe.png)
+
+<Note>
+You can have only one app connected to the Chatwoot for Instagram and Facebook combined as the Messenger platform is common. But suppose you want to have separate channels for Instagram and Facebook. In that case, you can have multiple Facebook pages inside your app that would be connected to Facebook users and Instagram users separately and then connected to the different inbox in the Chatwoot page.
+</Note>
+
+## Checklist
+
+1. Integrate the Facebook test app and Send a message from the Instagram tester to the connected account.
+2. Make sure your Instagram account is a business account.
+3. If the Instagram test account can receive the message and forward it to the webhook URL, then submit it for review.
+4. If the Instagram test account is not able to receive the message and forward it to the webhook URL
+   - Check the logs if you are receiving the message to `{your-app-url}/webhooks/Instagram`
+   - If the logs are present for the above endpoint, if there are any errors, then reach out to us. We will help you out.
+   - If the logs aren't present for the above endpoint, then raise a bug for the Facebook team or follow this bug https://developers.facebook.com/support/bugs/468852858104743/
+5. If you are not facing the above issue and can get the message, but the review isn't passing, then reach out to the reviewer.
+   - When your app gets rejected, open the rejected submission. You can see the messenger icon in the bottom right corner to support you with your rejected review.
+   - You can talk to the support team and ask your questions about the submission and the reason for the rejection.
+6. If your test app passed the review, it's good to go into production.
+7. If you face an issue on production that you cannot receive the messages, then reach out to us with the error logs. 

developer-docs/self-hosted/configuration/integrations/instagram-via-instagram-business-login.mdx

@@ -0,0 +1,110 @@
+---
+title: Instagram via Instagram Business Login
+description: Set up Instagram integration using Instagram Business Login authentication (recommended method)
+sidebarTitle: Instagram via Instagram Business Login
+---
+
+<Note>
+Please ensure you have installed version v4.1 or above. If not, please refer to this [guide](./instagram-channel-setup) for the Facebook Login method.
+</Note>
+
+## Prerequisites
+
+1. A valid facebook account.
+2. A valid instagram professional account.
+
+## Register A Facebook App
+
+To use Instagram Channel, you have to create a Facebook app in the developer portal. You can find more details about creating Facebook apps [here](./facebook-channel-setup).
+
+1. Click on the "Create App" button
+
+![facebook_create_app](/self-hosted/images/facebook/facebook-create-app.png)
+
+2. Select the option "Other".
+
+![facebook_other_app](/self-hosted/images/facebook/facebook_other_app.png)
+
+3. For the app type, choose "Business"
+
+![facebook_business](/self-hosted/images/facebook/facebook_business.png)
+
+4. Add app name and connect business account
+
+![facebook_business_details](/self-hosted/images/facebook/facebook_business_details.png)
+
+5. Add Instagram product from the Home page.
+
+![instagram_product](/self-hosted/images/instagram/instagram_product.png)
+
+## Configure Instagram settings for Chatwoot
+
+1. Copy Instagram app ID and Instagram app secret
+
+![instagram_app_id](/self-hosted/images/instagram/instagram_app_id.png)
+
+2. Add the Instagram app ID and Instagram app secret to your app config via `{Chatwoot installation url}/super_admin/app_config?config=instagram`
+
+![instagram_app_config](/self-hosted/images/instagram/instagram_app_config.png)
+
+3. Configure Webhooks
+
+Set the callback URL to `{your_chatwoot_url}/webhooks/instagram`. The verify token should match your `INSTAGRAM_VERIFY_TOKEN`, which can be configured through `app_config`
+
+![instagram_webhooks](/self-hosted/images/instagram/instagram_webhook.png)
+
+Subscribe to `messages`, `messaging_seen`, and `message_reactions` events.
+
+![instagram_webhooks_subscribe](/self-hosted/images/instagram/instagram_webhooks_subscribe.png)
+
+<Note>
+To receive web hooks, app mode should be set to "Live".
+</Note>
+
+4. Set up Instagram business login
+
+Set Redirect URL as `{your_chatwoot_url}/instagram/callback`
+
+![instagram_business_login](/self-hosted/images/instagram/instagram_business_login.png)
+
+5. Create a new Instagram tester account
+
+## Create Instagram Inbox
+
+Head over to Chatwoot and create a Instagram inbox. Please refer to this [guide](https://chatwoot.help/hc/user-guide/articles/1744361165-how-to-setup-an-instagram-channel-via-instagram-login) for more details on creating a Instagram inbox in Chatwoot.
+
+## How to test the Instagram before going to live
+
+1. Add Instagram Testers by clicking "Add People" button.
+
+![facebook_instagram_test](/self-hosted/images/instagram/instagram-testers-list.png)
+
+2. Make sure that you have selected the role Instagram Tester while creating a new tester.
+
+![instagram_tester_list](/self-hosted/images/instagram/instagram-add-tester.png)
+
+## Going into production.
+
+Before you can start using your Facebook app in production, you will have to get it verified by Facebook. Refer to the [docs](https://developers.facebook.com/docs/messenger-platform/instagram/app-review) on getting your app verified.
+
+## Troubleshooting & Common Errors
+
+### Insufficient Developer Role Error
+
+Ensure the Instagram user is added as a developer: `Meta Dashboard → App Roles → Roles → Add People → Enter Instagram ID`
+
+### API Access Deactivated
+
+Ensure the **Privacy Policy URL** is valid and correctly set.
+
+### Invalid request: Request parameters are invalid: Invalid redirect_uri
+
+Please configure the Frontend URL. The Frontend URL does not match the authorization URL.
+
+### Instagram Channel creation Error: Failed to exchange token
+
+Please make sure that tester account has been added to the facebook app settings.
+
+### 400: Session Invalid when connecting the instagram channel
+
+This might be issue from facebook side. Please try again after some time. 

developer-docs/self-hosted/configuration/integrations/linear-integration-setup.mdx

@@ -0,0 +1,43 @@
+---
+title: Setting Up Linear Integration
+description: Configure Linear integration to track issues and features from Chatwoot
+sidebarTitle: Linear
+---
+
+Setting up Chatwoot Linear integration involves 5 steps.
+
+1. Create a Linear app in the [developer portal](https://linear.app/settings/api/applications/new).
+2. Add necessary details and save the app.
+3. Configure Chatwoot with the `Client ID` and `Signing Secret` obtained from the Linear app.
+4. Open Chatwoot UI, navigate to integrations, select Linear, and click connect.
+5. Voila! You should now be able to use Linear in your Chatwoot account.
+
+## Register and configure the Linear app
+
+To use Linear Integration, you need to create a Linear app in the developer portal. You can find more details about creating Linear apps at the [Linear developer portal](https://developers.linear.app/docs/oauth/authentication).
+
+1. Create a Linear app.
+2. Obtain the `Client ID` and `Client Secret` for the app and configure it in your app config via `{Chatwoot installation url}/super_admin/app_config?config=linear`
+3. The callback URL should be `{Chatwoot installation url}/linear/callback`.
+4. Toggle the `Public` switch to make the app public.
+
+![linear_app_domain](/self-hosted/images/linear/create-app.png)
+
+## Configure Linear app config
+
+Obtain the `Client ID` and `Client Secret` for the app and configure it in your app config via `{Chatwoot installation url}/super_admin/app_config?config=linear`. These values will be available when you create the app in the developer portal.
+
+```bash
+LINEAR_CLIENT_ID=
+LINEAR_SIGNING_SECRET=
+```
+
+Restart the Chatwoot server.
+
+<Note>
+Linear will only show up in the integrations section once you have configured these values and restarted the server.
+</Note>
+
+## Connect Chatwoot with your Linear account
+
+Follow this [guide](https://chatwoot.help/hc/user-guide/articles/1739949089-how-to-track-issues-and-features-with-linear-integration) to complete the Linear integration. 

developer-docs/self-hosted/configuration/integrations/shopify-integration-setup.mdx

@@ -0,0 +1,37 @@
+---
+title: Setting Up Shopify Integration
+description: Configure Shopify integration to track orders and customer information from Chatwoot
+sidebarTitle: Shopify
+---
+
+Setting up Chatwoot Shopify integration involves 5 steps.
+
+1. Create a Shopify app in the [shopify partner dashboard](https://partners.shopify.com/).
+2. Add necessary details and save the app.
+3. Configure Chatwoot with the `Client ID` and `Client secret` obtained from the Shopify app.
+4. Open Chatwoot UI, navigate to integrations, select Shopify, and click connect.
+5. Voila! You should now be able to use Shopify in your Chatwoot account.
+
+## Register and configure the Shopify app
+
+To use Shopify Integration, you need to create a Shopify app in the [shopify partner dashboard](https://partners.shopify.com/). You can find more details about creating Shopify apps at the [Shopify developer portal](https://shopify.dev/docs/apps/build).
+
+1. Create a Shopify app.
+
+![shopify_app_create](/self-hosted/images/shopify/create-app.png)
+
+2. Obtain the `Client ID` and `Client Secret` for the app and configure it in your app config via `{Chatwoot installation url}/super_admin/app_config?config=shopify`
+
+![shopify_app_domain](/self-hosted/images/shopify/configure-app.png)
+
+3. Configure the redirect URL as `{Chatwoot installation url}/shopify/callback` in app configuration.
+
+![shopify_app_redirect](/self-hosted/images/shopify/callback.png)
+
+<Note>
+Shopify will only show up in the integrations section once you have configured these values.
+</Note>
+
+## Connect Chatwoot with your Shopify account
+
+Follow this [guide](https://chatwoot.help/hc/user-guide/articles/1742395545-how-to-track-orders-with-shopify-integration) to complete the Shopify integration. 

developer-docs/self-hosted/configuration/integrations/slack-integration-setup.mdx

@@ -0,0 +1,79 @@
+---
+title: Setting Up Slack Integration
+description: Configure Slack integration to receive Chatwoot conversations in Slack channels
+sidebarTitle: Slack
+---
+
+Setting up Chatwoot Slack integration involves 5 steps.
+
+1. Create a slack app in the developer portal.
+2. Add necessary permissions for the slack app.
+3. Configure Chatwoot with the `client ID` and `client Secret` obtained from the slack app.
+4. Open Chatwoot UI, navigate to integrations, Slack and click connect.
+5. Voila! You should be receiving new conversations in the #customer-conversations channel in Slack.
+
+## Register a Slack app
+
+To use Slack Integration, you have to create a Slack app in the developer portal. You can find more details about creating Slack apps at the [Slack developer portal](https://api.slack.com/).
+
+Once you register your Slack App, you will have to obtain the `Client Id` and `Client Secret`. These values will be available in the app settings and will be required while setting up Chatwoot environment variables.
+
+## Configure the Slack app
+
+1. Create a Slack app and add it to your development workspace.
+2. Obtain the `Client Id` and `Client Secret` for the app and configure it in your Chatwoot [environment variables](/docs/self-hosted/configuration/environment-variables).
+3. Head over to the `OAuth & permissions` section under `features` tab.
+4. In the redirect URLs, Add your Chatwoot installation base URL.
+5. In the scopes section configure the given scopes for bot token scopes:
+  - `channels:history`
+  - `channels:join`
+  - `channels:manage`
+  - `channels:read`
+  - `chat:write`
+  - `chat:write.customize`
+  - `commands`
+  - `files:read`
+  - `files:write`
+  - `groups:history`
+  - `groups:write`
+  - `im:history`
+  - `im:write`
+  - `links:read`
+  - `links:write`
+  - `mpim:history`
+  - `mpim:write`
+  - `users:read`
+  - `users:read.email`
+7. In the user access token section subscribe to: `files:read`, `files:write`, `remote_files:share`
+8. Head over to the `Events Subscriptions` section in the `Features` tab.
+9. Enable events and configure the given request url `{Chatwoot installation url}/api/v1/integrations/webhooks`
+10. Subscribe to the following bot events: `link_shared`, `message.channels`, `message.groups`, `message.im`, `message.mpim`.
+11. Add the installation URL as `domain` under the `App unfurl domains section` to display meta information about the conversation when the conversation URL is shared.
+12. Connect Slack integration on Chatwoot app and get productive.
+
+## Configure the environment variables in Chatwoot
+
+Obtain the `Client ID` and `Client Secret` for the app and configure it in your Chatwoot [environment variables](/docs/self-hosted/configuration/environment-variables).These values will be available under `Settings` > `Basic Information`.
+
+```bash
+SLACK_CLIENT_ID=
+SLACK_CLIENT_SECRET=
+```
+
+Restart the Chatwoot server.
+
+<Note>
+Slack will only show up in the integrations section once you have configured these values and restarted the server.
+</Note>
+
+## Connect Chatwoot with your Slack workspace
+
+Follow this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677774874-how-to-answer-conversations-from-slack) to complete the Slack integration.
+
+## Testing your setup
+
+1. Create a new conversation.
+2. Ensure that you are receiving the Chatwoot messages in the connected slack channel.
+3. Add a message to that thread and ensure that it is coming back on to Chatwoot.
+4. Add `note:` or `private:` in front of the Slack message to see if it is coming out as private notes.
+5. If your Slack member's email matches their email on Chatwoot, the messages will be associated with their Chatwoot user account. 

developer-docs/self-hosted/configuration/monitoring/apm-and-tracing.mdx

@@ -0,0 +1,54 @@
+---
+title: APM and Tracing
+description: Configure APM and error monitoring tools for Chatwoot
+sidebarTitle: APM and Tracing
+---
+
+Chatwoot supports various APM and monitoring tools.
+You can enable them by configuring the given environment variables.
+
+## [Sentry](https://sentry.io/)
+
+Provide your `sentry dsn`.
+
+```bash
+SENTRY_DSN=
+```
+
+## [Scout](https://scoutapm.com)
+Provide values for the following environment variables. Refer [scout documentation](https://scoutapm.com/docs/ruby/configuration) for additional options.
+```bash
+## https://scoutapm.com/docs/ruby/configuration
+# SCOUT_KEY=YOURKEY
+# SCOUT_NAME=YOURAPPNAME (Production)
+# SCOUT_MONITOR=true
+```
+
+## [NewRelic](https://newrelic.com/)
+Enable Newrelic by configuring the license key. Refer [newrelic documentation](https://docs.newrelic.com/docs/agents/ruby-agent/configuration/ruby-agent-configuration/) for additional options.
+
+```bash
+# https://docs.newrelic.com/docs/agents/ruby-agent/configuration/ruby-agent-configuration/
+# NEW_RELIC_LICENSE_KEY=
+```
+
+## [DataDog](https://www.datadoghq.com/)
+
+Datadog requires an agent running on the host machine to which the tracing library can send data. Chatwoot ruby code contains the tracing library, but you need to configure the agent in your host machine/docker environment for the integration to work.
+
+Enable Datadog in chatwoot by configuring the `trace agent url`.
+
+```bash
+## https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#environment-variables
+# DD_TRACE_AGENT_URL=http://localhost:8126
+```
+
+### Running Datadog agent in local via docker
+```bash
+# to run in your local machine binding to port 8126
+# replace <dd API key> and dd_site as required
+
+docker run -d --name dd-agent -v /var/run/docker.sock:/var/run/docker.sock:ro -v /proc/:/host/proc/:ro -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro -p 8126:8126  -e DD_API_KEY=<dd api key> -e DD_SITE="datadoghq.com" gcr.io/datadoghq/agent:7
+```
+
+Refer Datadog documentation to install the agent in specific environments like [Ubuntu](https://docs.datadoghq.com/agent/basic_agent_usage/ubuntu/?tab=agentv6v7), [Docker](https://docs.datadoghq.com/agent/docker/?tab=standard), [kubernetes](https://docs.datadoghq.com/agent/kubernetes/?tab=helm) etc. 

developer-docs/self-hosted/configuration/monitoring/rate-limiting.mdx

@@ -0,0 +1,38 @@
+---
+title: Rate Limiting
+description: Configure rate limiting to protect your Chatwoot installation from abuse
+sidebarTitle: Rate Limiting
+---
+
+To protect the system from abusive requests, Chatwoot makes use of [`rack_attack`](https://github.com/rack/rack-attack) gem.
+You could customize the configuration to suit your needs by updating, [`config/initializers/rack_attack.rb`](https://github.com/chatwoot/chatwoot/blob/develop/config/initializers/rack_attack.rb)
+
+## Default Rate Limits
+
+- Chatwoot will throttles requests by IP at `60rpm`, Unless the request is from an allowed IP `['127.0.0.1', '::1']`
+- Signup Requests are limited by IP at `5 requests` per `5 minutes`.
+- SignIn Requests are limited by IP at `5 requests` per `20 seconds`.
+- SignIn Requests are limited by email address at `20 requests` per `5 minutes` for a specific email.
+- Reset Password Requests are limited at `5 requests` per `1 hour` for a specific email.
+
+## Attachment Restrictions 
+
+- `Contact/Inbox Avatar` attachment file types are limited to jpeg, gif and png.
+- `Contact/Inbox Avatar` attachment file size is limited to 15MB.
+- `Website Channel` message attachments are limited to types ['image/png', 'image/jpeg', 'image/gif', 'image/bmp', 'image/tiff', 'application/pdf', 'audio/mpeg', 'video/mp4', 'audio/ogg', 'text/csv']
+- `Website Channel` message attachments are limited to 40MB size limit.
+
+## Disabling Rack attack on your instance 
+
+You can control the behaviour of rack attack in your instance via the following environment variables.
+
+```bash
+## Rack Attack configuration
+## To prevent and throttle abusive requests.
+# Disable if you are getting too many request errors for custom use cases
+# ENABLE_RACK_ATTACK=true
+# Control the allowed number of requests
+# RACK_ATTACK_LIMIT=300
+# Control whether you want to enable rack attack for widget APIs
+# ENABLE_RACK_ATTACK_WIDGET_API=true
+```

developer-docs/self-hosted/configuration/monitoring/super-admin-console.mdx

@@ -0,0 +1,41 @@
+---
+title: Super Admin Console
+description: Guide to accessing and using the Super Admin Console and Sidekiq monitoring
+sidebarTitle: Super Admin Console
+---
+
+You will need a user account with super admin privileges to access the super admin console and Sidekiq console. 
+
+<Note>
+The first user created during onboarding is a `super admin`.
+</Note>
+
+## Access superadmin console
+
+- Access `<chatwoot-installation-url>/super_admin`. 
+
+## Creating new super admins
+
+- Use the super admin console and navigate to the user's section
+- Click on the new user button, fill in the details, and select the type to be `super admin`
+
+## Access Sidekiq via the super admin console
+
+- Access `<chatwoot-installation-url>/super_admin`.
+- Authenticate using the admin credentials created during the installation.
+- You can access the Sidekiq option on the sidebar.
+
+## Access Rails console
+
+Run the following command in your console from the root folder of your Chatwoot Rails app.
+
+```bash
+RAILS_ENV=production bundle exec rails c
+```
+If you have `cwctl`, use `cwctl --console`.
+
+- If you running Chatwoot in a Docker container, you would need to access the shell inside your container first.
+- If you are running Chatwoot on Caprover, use the following command to access the command line.
+```bash
+docker exec -it $(docker ps --filter name=srv-captain--chatwoot-web -q) /bin/sh
+``` 

developer-docs/self-hosted/configuration/performance/cloudfront-cdn.mdx

@@ -0,0 +1,99 @@
+---
+title: Cloudfront CDN
+description: Configure Cloudfront as a CDN for Chatwoot assets
+sidebarTitle: Cloudfront CDN
+---
+
+This document helps you to configure Cloudfront as the asset host for Chatwoot. If you have a high traffic website, we would recommend setting up a CDN for Chatwoot.
+
+## Configure a Cloudfront distribution
+
+**Step 1**: Create a Cloudfront distribution.
+
+![create-distribution](/self-hosted/images/cloudfront/create-distribution.png)
+
+**Step 2**: Select "Web" as delivery method for your content.
+
+![web-delivery-method](/self-hosted/images/cloudfront/web-delivery-method.png)
+
+**Step 3**: Configure the Origin Settings as the following.
+
+![origin-settings](/self-hosted/images/cloudfront/origin-settings.png)
+
+- Provide your Chatwoot Installation URL under Origin Domain Name.
+- Select "Origin Protocol Policy" as Match Viewer.
+
+**Step 4**: Configure Cache behaviour.
+
+![cache-behaviour](/self-hosted/images/cloudfront/cache-behaviour.png)
+
+- Configure **Allowed HTTP methods** to use *GET, HEAD, OPTIONS*.
+- Configure **Cache and origin request settings** to use *Use legacy cache settings*.
+- Select **Whitelist** for *Cache Based on Selected Request Headers*.
+- Add the following headers to the **Whitelist Headers**.
+![extra-headers](/self-hosted/images/cloudfront/extra-headers.png)
+  - **Access-Control-Request-Headers**
+  - **Access-Control-Request-Method**
+  - **Origin**
+- Set the **Response headers policy** to **CORS-With-Preflight**
+
+**Step 5**: Click on **Create Distribution**. You will be able to see the distribution as shown below. Use the **Domain name** listed in the details as the **ASSET_CDN_HOST** in Chatwoot.
+
+![cdn-distribution-settings](/self-hosted/images/cloudfront/cdn-distribution-settings.png)
+
+## Add ASSET_CDN_HOST in Chatwoot
+
+Your Cloudfront URL will be of the format `<distribution>.cloudfront.net`.
+
+Set
+
+```bash
+ASSET_CDN_HOST=<distribution>.cloudfront.net
+```
+
+in the environment variables.
+
+## Benefits of Using CDN
+
+<Tip>
+Using a CDN provides several benefits for your Chatwoot installation:
+</Tip>
+
+1. **Faster Asset Loading**: Assets are served from edge locations closer to users
+2. **Reduced Server Load**: Static assets are served from CDN, reducing load on your application server
+3. **Better User Experience**: Faster page load times improve user experience
+4. **Global Availability**: Assets are cached globally for users worldwide
+5. **Bandwidth Savings**: Reduces bandwidth usage on your origin server
+
+## Troubleshooting
+
+### CORS Issues
+
+If you encounter CORS issues after setting up CloudFront:
+
+1. Ensure the CORS headers are properly configured in CloudFront
+2. Verify that your `CORS_ORIGINS` environment variable includes your CDN domain:
+
+```bash
+CORS_ORIGINS=https://yourdomain.com,https://d1234567890.cloudfront.net
+```
+
+### Cache Invalidation
+
+To invalidate CloudFront cache after updating assets:
+
+1. Go to CloudFront console
+2. Select your distribution
+3. Create an invalidation for `/*` to clear all cached assets
+
+### SSL Certificate
+
+For custom domain names with CloudFront:
+
+1. Request an SSL certificate in AWS Certificate Manager (ACM)
+2. Configure the certificate in your CloudFront distribution
+3. Update your DNS to point to the CloudFront distribution
+
+<Note>
+SSL certificates for CloudFront must be requested in the US East (N. Virginia) region regardless of where your distribution is located.
+</Note> 

developer-docs/self-hosted/configuration/performance/optimizing-configurations.mdx

@@ -0,0 +1,108 @@
+---
+title: Optimizing Configurations
+description: Performance optimization guide for Chatwoot self-hosted deployments
+sidebarTitle: Optimizing Configurations
+---
+
+This document helps you to fine-tune various configuration values available in Chatwoot to extract the maximum performance out of your Chatwoot Installation. 
+
+## Puma
+Chatwoot uses [Puma](https://puma.io/) as its Webserver. So let's start with a brief introduction to Puma workers and threads.
+
+Puma is a popular web server for Ruby on Rails applications, and it uses multiple workers and threads to handle incoming requests. Each Worker runs its own instance of the application, and each thread within a worker can handle a single request at a time.
+
+Now, let's move on to how you can configure Puma workers and threads using environment variables.
+
+
+### Workers
+Each Puma worker is a separate process that runs an instance of the Ruby application. Each Worker has its own event loop that can handle incoming requests concurrently using multiple threads. 
+
+When the Puma server receives a request, it is assigned to a worker process in a round-robin fashion. Once a worker receives a request, it assigns the request to an available thread within its process. Each thread then handles the request, including any required database queries, calculations, and other processing tasks. Using multiple worker processes allows Puma to handle multiple requests concurrently without blocking other requests or causing a bottleneck.
+
+#### Configuring the number of workers
+
+The `WEB_CONCURRENCY` environment variable can be used to configure the number of workers in Puma. It's important to consider the number of available CPU cores and aim for a ratio of workers to cores that allows the server to run at maximum capacity without causing performance issues. It's recommended to have a number of workers that matches or is slightly less than the number of available CPU cores to avoid competition for CPU time, which can lead to performance issues.
+
+
+```
+WEB_CONCURRENCY=2
+```
+
+<Note>
+The default configuration in Chatwoot for `WEB_CONCURRENCY` is `0`. I.e. it runs one Worker. This is to ensure the application works on machines with a lower configuration. If you run Chatwoot on machines with higher specs, fine-tune this configuration accordingly.
+</Note>
+
+
+### Threads
+
+Each Puma thread is a lightweight execution context that can handle a single request at a time. When a worker process receives a request, it is assigned to an available thread within that process. Each thread then handles the request, including any required database queries, calculations, and other processing tasks.
+
+Using multiple threads can increase concurrency and performance, but balancing the number of threads with the available CPU resources is essential to avoid competition for CPU time. The number of threads can be configured using the following environment variables. 
+
+```
+# Only required to configure if absolutely necessary
+# Defaults to Max threads value by default
+# RAILS_MIN_THREADS=5
+RAILS_MAX_THREADS=5
+```
+
+<Note>
+The default configuration in Chatwoot for `RAILS_MAX_THREADS` values is `5`. You can fine-tune it based on your requirements. The value of `RAILS_MIN_THREADS` defaults to `RAILS_MAX_THREADS` unless a specific value is provided.
+</Note>
+
+### Fine-tuning
+
+TLDR: You can configure `WEB_CONCURRENCY` to the number of CPU cores and then fine-tune the number of `RAILS_MAX_THREADS` based on the available `memory` and `CPU` resources. While running the sidekiq and rails server on a single machine, consider the sidekiq configuration while determining these numbers.
+
+
+References: 
+
+- https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server
+- https://www.speedshop.co/2017/10/12/appserver.html
+- https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts#puma
+
+
+## Sidekiq
+
+Sidekiq is a popular job processing library for Ruby on Rails applications. Chatwoot uses it as a simple and efficient way to execute background jobs asynchronously in the Rails application.
+
+Sidekiq uses Redis to manage a job queue, allowing you to run multiple workers in parallel, each processing jobs from the queue. This makes it easy to distribute workloads and handle large volumes of jobs without bogging down your Rails application's main thread.
+
+You can configure the number of sidekiq workers using the following environment variables.
+
+```
+# the default value in Chatwoot is 10 
+SIDEKIQ_CONCURRENCY=10
+```
+
+<Note>
+If you are running sidekiq on dedicated pods, you can fine-tune the `SIDEKIQ_CONCURRENCY` number to extract the maximum performance of the available CPU resources.
+</Note>
+
+
+## Database Connections
+
+When a Ruby on Rails application is launched, it creates a pool of database connections that are stored in memory. These connections are established with the database server at the beginning of the application and are kept open throughout the life of the application. When a request is made to the application that requires access to the database, the application server will retrieve a connection from the pool and use it to process the request. Once the request is complete, the connection is returned to the pool to be used for future requests.
+
+The size of the database pool in Chatwoot is configured automatically based on the values of `RAILS_MAX_THREADS` and `SIDEKIQ_CONCURRENCY`
+```
+https://github.com/chatwoot/chatwoot/blob/4d719a8fe33bed72ec57812e174dab1874315340/config/database.yml#L7
+```
+
+Ref: 
+- https://stackoverflow.com/questions/40412611/in-puma-how-do-i-calculate-db-connections
+
+<Note>
+If you have a database server with higher resources available, you can leverage it by bumping up the number of rails and sidekiq pods so that more of the connection limit is being used.
+</Note>
+
+
+### FAQ
+
+## Getting `ActiveRecord::ConnectionTimeoutError` errors. 
+
+There is a potential bug with Chatwoot's implementation of `rack-timeout`, in specific installations, which results in connections not being released properly. For the time being, you can set the following environment variable to disable `rack-timeout` if you are experiencing this. 
+
+```
+RACK_TIMEOUT_SERVICE_TIMEOUT=0
+``` 

developer-docs/self-hosted/configuration/storage/gcs-bucket.mdx

@@ -0,0 +1,85 @@
+---
+title: GCS Bucket
+description: Configure Google Cloud Storage bucket as storage in Chatwoot
+sidebarTitle: GCS Bucket
+---
+
+Chatwoot supports Google Cloud storage as the storage provider. To enable GCS in Chatwoot, follow the below mentioned steps.
+
+Set google as the active storage service in the environment variables
+
+```bash
+ACTIVE_STORAGE_SERVICE='google'
+```
+
+## Get project ID variable
+
+Login to your Google Cloud console. On your home page of your project you will be able to see the project id and project name as follows.
+
+![get-your-project-id](/self-hosted/images/get-your-project-id.png)
+
+```bash
+GCS_PROJECT=your-project-id
+```
+
+## Setup GCS Bucket
+
+Go to Storage -> Browser. Click on "Create Bucket". You will be presented with a screen as shown below. Select the default values and continue.
+
+![create-a-bucket](/self-hosted/images/create-a-bucket.png)
+
+Once this is done you will get the bucket name. Set this as GCS_BUCKET.
+
+```bash
+GCS_BUCKET=your-bucket-name
+```
+
+## Setup a service account
+
+Go to `Identity & Services -> Identity -> Service Accounts`. Click on "Create Service Account".
+
+Provice a name and an ID for the service account, click on create. You will be asked to "Grant this service account access to the project" Select Cloud Storage -> Storage Admin as shown below.
+
+![storage-admin](/self-hosted/images/storage-admin.png)
+
+## Add service account to the bucket
+
+Go to Storage -> Browser -> Your bucket -> Permissions. Click on add. On "New members" field select the service account you just created.
+
+Select role as `Cloud Storage -> Storage Admin` and save.
+
+![permissions](/self-hosted/images/permissions.png)
+
+## Generate a key for the service account
+
+Go to `Identity & Services -> Identity -> Service Accounts -> Your service account`. There is a section called **Keys**. Click on **Add Key**. You will be presented with an option like the one below. Select JSON from the option.
+
+![json](/self-hosted/images/json.png)
+
+Copy the json file content and set it as GCS_CREDENTIALS
+
+A sample credential file is of the following format.
+
+```json
+{
+  "type": "service_account",
+  "project_id": "",
+  "private_key_id": "",
+  "private_key": "",
+  "client_email": "",
+  "client_id": "",
+  "auth_uri": "",
+  "token_uri": "",
+  "auth_provider_x509_cert_url": "",
+  "client_x509_cert_url": ""
+}
+```
+
+When pasting the credentials to the ENV file, make sure to remove the new lines and paste it into a single line. 
+```bash
+GCS_CREDENTIALS={"type": "service_account","project_id": "","private_key_id": "","private_key": "","client_email": "","client_id": "","auth_uri": "","token_uri": "","auth_provider_x509_cert_url": "","client_x509_cert_url": ""}
+```
+
+<Note>
+If you are running Chatwoot v2.17+, make sure to wrap `GCS_CREDENTIALS` in single quotes.
+</Note> 

developer-docs/self-hosted/configuration/storage/s3-bucket.mdx

@@ -0,0 +1,103 @@
+---
+title: S3 Bucket
+description: Configure Amazon S3 bucket as storage in Chatwoot
+sidebarTitle: S3 Bucket
+---
+
+## Using Amazon S3
+
+You can get started with [Creating an S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [Create an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) to configure the following details.
+
+Configure the following env variables.
+
+```bash
+ACTIVE_STORAGE_SERVICE='amazon'
+S3_BUCKET_NAME=
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_REGION=
+```
+
+## S3 Bucket policy
+
+Inorder to use S3 bucket in Chatwoot, a policy has to be set with the correct credentials. A sample policy is given below, as the listed actions are required for the storage to work.
+
+```json
+{
+    "Version": "2012-10-17",
+    "Id": "Policyxxx",
+    "Statement": [
+        {
+            "Sid": "Stmtxxx",
+            "Effect": "Allow",
+            "Principal": {
+                "AWS": "your-user-arn"
+            },
+            "Action": [
+                "s3:DeleteObject",
+                "s3:GetObject",
+                "s3:ListBucket",
+                "s3:PutObject"
+            ],
+            "Resource": [
+                "arn:aws:s3:::your-bucket-name",
+                "arn:aws:s3:::your-bucket-name/*"
+            ]
+        }
+    ]
+}
+```
+
+Replace your *bucket name* in the appropriate places.
+
+**User ARN** can be found using the following steps:
+
+1. Login to AWS Console. Go to IAM, and click on Users from the left sidebar. You will be to see the list of users as follows.
+
+![s3-users-list](/self-hosted/images/s3-users-list.png)
+
+2. Click on the user, you will be to see a screen as shown below. Copy the User ARN and paste it in the above policy.
+
+![user-arn](/self-hosted/images/user-arn.png)
+
+**Add CORS Configuration on your S3 buckets**
+
+You need to configure CORS settings to the respective storage cloud to support Direct file uploads from the widget and the Chatwoot dashboard.
+
+Refer to this link for more information: https://edgeguides.rubyonrails.org/active_storage_overview.html#cross-origin-resource-sharing-cors-configuration
+
+To make CORS configuration changes on S3:
+
+1. Go to your S3 bucket
+2. Click on the permissions tab.
+3. Scroll to Cross-origin resource sharing (CORS) and click on `Edit` and add the respective changes shown below.
+
+![aws-cors-setup](/self-hosted/images/aws-cors-setup.png)
+
+Add your Chatwoot URL to the `AllowedOrigin` as shown below.
+
+```json
+[
+  {
+    "AllowedHeaders": [
+      "*"
+    ],
+    "AllowedMethods": [
+      "PUT",
+      "POST",
+      "DELETE",
+      "GET"
+    ],
+    "AllowedOrigins": [
+      "<add-your-domain-here eg: https://app.chatwoot.com>"
+    ],
+    "ExposeHeaders": [
+      "Origin",
+      "Content-Type",
+      "Content-MD5",
+      "Content-Disposition"
+    ],
+    "MaxAgeSeconds": 3600
+  }
+]
+``` 

developer-docs/self-hosted/configuration/storage/supported-providers.mdx

@@ -0,0 +1,92 @@
+---
+title: Supported Providers
+description: Configure cloud storage providers for Chatwoot file storage
+sidebarTitle: Supported Providers
+---
+
+# Configure Cloud Storage
+
+Chatwoot uses [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) for storing attachments. The default storage option is local storage on your server, but you can configure cloud providers for better scalability and backup.
+
+<Tip>
+It is recommended to use a cloud provider for your Chatwoot storage to ensure proper backup of stored attachments and prevent data loss.
+</Tip>
+
+## Using Amazon S3
+
+You can get started with [Creating an S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [Create an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) to configure the following details.
+
+Configure the following env variables.
+
+```bash
+ACTIVE_STORAGE_SERVICE=amazon
+S3_BUCKET_NAME=
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_REGION=
+```
+
+## Using Google GCS
+
+<Note>
+Starting with version 2.17+, wrap the `GCS_CREDENTIALS` environment variable in single quotes.
+</Note>
+
+Configure the following env variables.
+
+```bash
+ACTIVE_STORAGE_SERVICE=google
+GCS_PROJECT=
+GCS_CREDENTIALS=
+GCS_BUCKET=
+```
+
+The value of the `GCS_CREDENTIALS` should be a json formatted string containing the following keys.
+
+```bash
+{
+  "type": "service_account",
+  "project_id" : "",
+  "private_key_id" : "",
+  "private_key" : "",
+  "client_email" : "",
+  "client_id" : "",
+  "auth_uri" : "",
+  "token_uri" : "",
+  "auth_provider_x509_cert_url" : "",
+  "client_x509_cert_url" : ""
+}
+```
+When pasting the credentials to the ENV file, make sure to remove the new lines and paste it into a single line.
+
+```bash
+GCS_CREDENTIALS={"type": "service_account","project_id": "","private_key_id": "","private_key": "","client_email": "","client_id": "","auth_uri": "","token_uri": "","auth_provider_x509_cert_url": "","client_x509_cert_url": ""}
+```
+
+## Using Microsoft Azure
+
+Configure the following env variables.
+
+```bash
+ACTIVE_STORAGE_SERVICE=microsoft
+AZURE_STORAGE_ACCOUNT_NAME=
+AZURE_STORAGE_ACCESS_KEY=
+AZURE_STORAGE_CONTAINER=
+```
+
+## Using Amazon S3 Compatible Service
+
+To use an s3 compatible service such as [DigitalOcean Spaces](https://www.digitalocean.com/docs/spaces/resources/s3-sdk-examples/#configure-a-client), Minio etc..
+
+Configure the following env variables.
+
+```bash
+ACTIVE_STORAGE_SERVICE=s3_compatible
+STORAGE_BUCKET_NAME=
+STORAGE_ACCESS_KEY_ID=
+STORAGE_SECRET_ACCESS_KEY=
+STORAGE_REGION=nyc3
+STORAGE_ENDPOINT=https://nyc3.digitaloceanspaces.com
+#set force_path_style to true if using minio
+#STORAGE_FORCE_PATH_STYLE=true
+```

developer-docs/self-hosted/deployment/chatwoot-ctl.mdx

@@ -1,416 +1,100 @@
 ---
-title: Chatwoot CTL (cwctl)
-description: Command-line tool for managing Chatwoot installations with ease
+title: Chatwoot CTL
+description: CLI tool to install and manage a self hosted Chatwoot Linux installation
 sidebarTitle: Chatwoot CTL
 ---
 
-# Chatwoot CTL (cwctl)
+## Introduction
 
-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.
+Chatwoot CTL(`cwctl`) is CLI tool to install and manage a self hosted Chatwoot Linux installation.
 
-## Installation
+`cwctl` aims to abstract away the common bash interactions with a Chatwoot installation and provide an easy to use syntax. This is not intended to be a full replacement.
 
-### Automatic Installation
+If you are running a Chatwoot v2.7.0 instance or later, `cwctl` would have been already installed for you as part of installation.
 
-`cwctl` is automatically installed when you use the Linux installation script (v2.7.0+):
+Check if `cwctl` is already installed by
 
 ```bash
-wget https://get.chatwoot.app/linux/install.sh
-chmod +x install.sh
-./install.sh --install
+cwctl --version
 ```
 
-### Manual Installation
+If `cwctl` is not present, follow the steps below to install Chatwoot CTL.
 
-If you have an older installation or need to install `cwctl` separately:
+### Install or Upgrade Chatwoot CTL
+
+If you used an older version of install script(< 2.0), you will not have `cwctl` in your PATH. To install/upgrade Chatwoot CTL,
 
 ```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
+wget https://get.chatwoot.app/linux/install.sh -O /usr/local/bin/cwctl && chmod +x /usr/local/bin/cwctl
 cwctl --help
 ```
 
 <Note>
-The manual installation requires root access to install `cwctl` to `/usr/local/bin`.
+The above command requires root access to install `cwctl` to `/usr/local/bin`.
 </Note>
 
-## Available Commands
+### Help
 
-### Help and Version
+To learn more about the options supported by `cwctl`,
 
 ```bash
-# Display help information
-cwctl --help
-cwctl -h
-
-# Show version information
-cwctl --version
-cwctl -v
+sudo cwctl --help
 ```
 
-### Installation Management
+### Upgrading to a newer version of Chatwoot
+
+Whenever a new version of Chatwoot is released, use the following steps to upgrade your instance.
 
 ```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
+sudo cwctl --upgrade
 ```
 
-### Console and Debugging
+<Note>
+This will upgrade your Chatwoot instance to the latest stable release. If you are running a custom branch in production do not use this to upgrade.
+</Note>
+
+### Setup Nginx with SSL after installation
+
+To set up Nginx with SSL after initial setup(if you answered `no` to webserver/SSL setup during the first install)
+
+<Note>
+Please add an A record pointing to your Chatwoot instance IP before proceeding.
+</Note>
 
 ```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
+sudo cwctl --webserver
 ```
 
-### Service Management
+### Restart Chatwoot
 
 ```bash
-# Check service status
-cwctl --status
-cwctl -s
-
-# Stop Chatwoot services
-cwctl --stop
-
-# Start Chatwoot services
-cwctl --start
-```
-
-## Detailed Command Usage
-
-### Upgrading Chatwoot
-
-The upgrade command handles the complete upgrade process:
-
-```bash
-cwctl --upgrade
-```
-
-This command performs the following steps:
-1. Switches to the chatwoot user
-2. Navigates to the Chatwoot directory
-3. Pulls the latest code from the master branch
-4. Updates Ruby version if needed
-5. Installs/updates dependencies (bundle, pnpm)
-6. Precompiles assets
-7. Runs database migrations
-8. Updates systemd service files
-9. Restarts services
-
-<Warning>
-Always backup your database before upgrading:
-```bash
-# Create a backup before upgrading
-sudo -u postgres pg_dump chatwoot_production > chatwoot_backup_$(date +%Y%m%d).sql
-```
-</Warning>
-
-### Console Access
-
-Access the Rails console for debugging and administration:
-
-```bash
-cwctl --console
-```
-
-This opens an interactive Ruby console where you can:
-
-```ruby
-# Check application version
-Rails.application.config.version
-
-# List all accounts
-Account.all
-
-# Find a specific user
-User.find_by(email: 'admin@example.com')
-
-# Check system statistics
-Account.count
-User.count
-Conversation.count
-
-# Clear cache
-Rails.cache.clear
-```
-
-### Log Management
-
-View real-time logs for troubleshooting:
-
-```bash
-# Web server logs (Rails application)
-cwctl -l web
-
-# Worker logs (Sidekiq background jobs)
-cwctl -l worker
-
-# All logs (both web and worker)
-cwctl -l
-```
-
-### Service Management
-
-Control Chatwoot services:
-
-```bash
-# Check if services are running
-cwctl --status
-
-# Restart all services (web + worker)
-cwctl --restart
-
-# Stop all services
-cwctl --stop
-
-# Start all services
-cwctl --start
-```
-
-## Configuration
-
-### Environment Variables
-
-`cwctl` respects the same environment variables as your Chatwoot installation. Key variables include:
-
-```bash
-# Chatwoot installation directory
-CHATWOOT_DIR="/home/chatwoot/chatwoot"
-
-# Rails environment
-RAILS_ENV="production"
-
-# Database configuration
-DATABASE_URL="postgresql://..."
-
-# Redis configuration
-REDIS_URL="redis://..."
-```
-
-### Custom Installation Paths
-
-If Chatwoot is installed in a non-standard location, you can specify the path:
-
-```bash
-# Set custom Chatwoot directory
-export CHATWOOT_DIR="/opt/chatwoot"
-cwctl --restart
-```
-
-## Troubleshooting
-
-### Common Issues
-
-<Accordion title="cwctl command not found">
-If `cwctl` is not found, ensure it's installed and in your PATH:
-
-```bash
-# Check if cwctl exists
-which cwctl
-
-# If not found, install it
-wget https://get.chatwoot.app/linux/install.sh -O /usr/local/bin/cwctl
-chmod +x /usr/local/bin/cwctl
-
-# Add to PATH if needed
-echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
-source ~/.bashrc
-```
-</Accordion>
-
-<Accordion title="Permission denied errors">
-Ensure you have the necessary permissions:
-
-```bash
-# Run with sudo if needed
 sudo cwctl --restart
-
-# Or ensure your user is in the chatwoot group
-sudo usermod -a -G chatwoot $USER
 ```
-</Accordion>
 
-<Accordion title="Service restart failures">
-If services fail to restart, check the logs:
+### Running Rails Console
 
 ```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
+sudo cwctl --console
 ```
-</Accordion>
 
-### Debug Mode
+### Viewing Logs
 
-For verbose output during operations:
+For Chatwoot web(rails) server logs use,
 
 ```bash
-# Enable debug mode
-export CWCTL_DEBUG=1
-cwctl --upgrade
+sudo cwctl --logs web
 ```
 
-### Manual Operations
-
-If `cwctl` fails, you can perform operations manually:
+For Chatwoot worker(sidekiq) server logs use,
 
 ```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
+sudo cwctl --logs worker
 ```
 
-## Best Practices
+### Version
 
-### Regular Maintenance
+To check the version of Chatwoot CTL,
 
 ```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. 
+sudo cwctl --version
+``` 

developer-docs/self-hosted/deployment/docker.mdx

@@ -1,572 +1,205 @@
 ---
-title: Docker Deployment Guide
-description: Complete guide to deploy Chatwoot using Docker containers for production environments.
+title: Docker Chatwoot Production deployment guide
+description: 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.
+## Pre-requisites
 
-## Prerequisites
+Before proceeding, make sure you have the latest version of `docker` and `docker-compose` installed.
 
-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:
+As of now [at the time of writing this doc], we recommend a version equal to or higher than the following.
 
 ```bash
 $ docker --version
-Docker version 25.0.4, build 1a576c5
-
+Docker version 20.10.10, build b485636
 $ docker compose version
-Docker Compose version v2.24.7
+Docker Compose version v2.14.1
 ```
 
 <Note>
-Container names use dashes instead of underscores by default with newer Docker Compose versions. If using an older version, replace `-` with `_` and use `docker-compose` instead of `docker compose`.
+Container name uses dashes instead of underscores by default with new docker/compose versions. If you are using an older version of docker/compose, replace `-` with `_`. Also, use `docker-compose` instead of `docker compose`.
 </Note>
 
-## Quick Start
+## Steps to deploy Chatwoot using docker-compose
 
-### 1. Install Docker
+### 1. Install Docker on your VM
 
-**Ubuntu/Debian:**
 ```bash
-# Update package index
-apt-get update && apt-get upgrade -y
-
-# Install Docker
+# example in ubuntu
+apt-get update
+apt-get upgrade
 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
+### 2. Download the required files
 
 ```bash
-# Create project directory
-mkdir chatwoot && cd chatwoot
-
-# Download environment template
+# Download the env file template
 wget -O .env https://raw.githubusercontent.com/chatwoot/chatwoot/develop/.env.example
-
-# Download Docker Compose configuration
+# Download the Docker compose template
 wget -O docker-compose.yaml https://raw.githubusercontent.com/chatwoot/chatwoot/develop/docker-compose.production.yaml
 ```
 
-### 3. Configure Environment
+### 3. Configure environment variables
 
-Edit the `.env` file with your settings:
+Tweak the `.env` and `docker-compose.yaml` according to your preferences. Refer to the available [environment variables](/docs/self-hosted/configuration/environment-variables). You could also remove the dependant services like `Postgres`, `Redis` etc., in favor of managed services configured via environment variables.
 
 ```bash
+# update redis and postgres passwords
 nano .env
+# update docker-compose.yaml same postgres pass
+nano docker-compose.yaml
 ```
 
-**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
+### 4. Prepare the database
 
 ```bash
-# Prepare the database
 docker compose run --rm rails bundle exec rails db:chatwoot_prepare
 ```
 
-### 6. Start Services
+### 5. Start the services
 
 ```bash
-# Start all services in background
 docker compose up -d
-
-# Check service status
-docker compose ps
 ```
 
-### 7. Verify Installation
+### 6. Access your installation
+
+Your Chatwoot installation is complete. Please note that the containers are not exposed to the internet and they only bind to the localhost. Setup something like Nginx or any other proxy server to proxy the requests to the container.
+
+If you want to verify whether the installation is working, try `curl -I localhost:3000/api` to see if it returns `200`. Also, you could temporarily drop the `127.0.0.1:3000:3000` for rails to `3000:3000` in the compose file to access your instance at `http://<your-external-ip>:3000`. It's recommended to revert this change back and use Nginx or some proxy server in the front.
+
+## Additional Steps
+
+1. Have an `Nginx` web server acting as a reverse proxy for Chatwoot installation. So that you can access Chatwoot from `https://chat.yourdomain.com`
+2. Run `docker compose run --rm rails bundle exec rails db:chatwoot_prepare` whenever you decide to update the Chatwoot images to handle the migrations.
+
+### Configure Nginx and Let's Encrypt
+
+#### 1. Configure Nginx to serve as a frontend proxy
 
 ```bash
-# Check if Chatwoot is responding
-curl -I localhost:3000/api
-
-# Should return: HTTP/1.1 200 OK
+sudo apt-get install nginx
+cd /etc/nginx/sites-enabled
+nano yourdomain.com.conf
 ```
 
-## Production Configuration
+#### 2. Use the following Nginx config
 
-### 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`:
+Use the following Nginx config after replacing the `yourdomain.com` in `server_name`.
 
 ```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;
+  server_name <yourdomain.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
+  # Make sure that the config is set to on.
+  underscores_in_headers on;
+  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; # Optional
+
+    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;
+
+    client_max_body_size 0;
+    proxy_read_timeout 36000s;
+    proxy_redirect off;
+  }
+  listen 80;
 }
 ```
 
-Enable the site and configure SSL:
+#### 3. Verify and reload Nginx config
 
 ```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
+nginx -t
+systemctl reload nginx
 ```
 
-## Advanced Configuration
+#### 4. Run Let's Encrypt to configure SSL certificate
 
-### Environment Variables
-
-Key environment variables for production:
+```bash
+apt install certbot
+apt-get install python3-certbot-nginx
+mkdir -p /var/www/ssl-proof/chatwoot/.well-known
+certbot --webroot -w /var/www/ssl-proof/chatwoot/ -d yourdomain.com -i nginx
+```
 
-```env
-# Application
-RAILS_ENV=production
-NODE_ENV=production
-SECRET_KEY_BASE=generate_64_character_secret
-FRONTEND_URL=https://your-domain.com
+#### 5. Access your installation
 
-# Database
-DATABASE_URL=postgresql://postgres:password@postgres:5432/chatwoot
-REDIS_URL=redis://redis:6379/0
-REDIS_PASSWORD=your_redis_password
+Your Chatwoot installation should be accessible from the `https://yourdomain.com` now.
 
-# 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
+## Steps to build images yourself
 
-# 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
+We publish our base images to the Docker hub. You should be able to build your Chatwoot web/worker images from these base images.
 
-# Security
-FORCE_SSL=true
-RAILS_LOG_TO_STDOUT=true
+### Web
 
-# Performance
-RAILS_MAX_THREADS=5
-WEB_CONCURRENCY=2
+```dockerfile
+FROM chatwoot/chatwoot:latest
+RUN chmod +x docker/entrypoints/rails.sh
+ENTRYPOINT ["docker/entrypoints/rails.sh"]
+CMD bundle exec bundle exec rails s -b 0.0.0.0 -p 3000
 ```
-
-### 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
+### Worker
 
-  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
+```dockerfile
+FROM chatwoot/chatwoot:latest
+RUN chmod +x docker/entrypoints/rails.sh
+ENTRYPOINT ["docker/entrypoints/rails.sh"]
+CMD bundle exec sidekiq -C config/sidekiq.yml
 ```
 
-### Logging Configuration
+The app servers will run available on port `3000`. Ensure the images connect to the same database and Redis servers. Provide the configuration for these services via [environment variables](/docs/self-hosted/configuration/environment-variables).
 
-Configure centralized logging:
+### Initial database setup
 
-```yaml
-services:
-  rails:
-    logging:
-      driver: "json-file"
-      options:
-        max-size: "10m"
-        max-file: "3"
+To set up the database for the first time, you must run `rails db:chatwoot_prepare`. You may get errors if you try to run `rails db:migrate` at this point.
 
-  sidekiq:
-    logging:
-      driver: "json-file"
-      options:
-        max-size: "10m"
-        max-file: "3"
-```
+## Upgrading
 
-## Maintenance Operations
+If you're not using the `latest` or `latest-ce` tag, you first need to change the desired tag in your docker-compose file.
 
-### Upgrading Chatwoot
+After that you can pull the new image and start using them:
 
 ```bash
-# Pull latest images
 docker compose pull
-
-# Stop services
-docker compose down
-
-# Start with new images
 docker compose up -d
+```
 
-# Run database migrations
+Finally you may need to update the database:
+
+```bash
 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
+## Running Rails Console
 
 ```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"
+docker exec -it $(basename $(pwd))-rails-1 sh -c 'RAILS_ENV=production bundle exec rails c'
 ```
 
-## Troubleshooting
+## Chatwoot CE edition docker images
 
-### Common Issues
-
-**1. Permission Issues:**
-```bash
-# Fix file permissions
-sudo chown -R 1000:1000 ./data/
-```
-
-**2. Database Connection Issues:**
-```bash
-# Check database connectivity
-docker compose exec rails bundle exec rails db:version
-```
-
-**3. Memory Issues:**
-```bash
-# Check memory usage
-docker stats --no-stream
-```
-
-**4. SSL Certificate Issues:**
-```bash
-# Renew certificates
-sudo certbot renew --dry-run
-```
-
-### Performance Optimization
-
-**1. Database Optimization:**
-```sql
--- Connect to database
-docker compose exec postgres psql -U postgres chatwoot
-
--- Check slow queries
-SELECT query, mean_time, calls 
-FROM pg_stat_statements 
-ORDER BY mean_time DESC 
-LIMIT 10;
-```
-
-**2. Redis Optimization:**
-```bash
-# Check Redis memory usage
-docker compose exec redis redis-cli info memory
-```
-
-### Security Hardening
-
-**1. Network Security:**
-```yaml
-# Add to docker-compose.yaml
-networks:
-  chatwoot:
-    driver: bridge
-    internal: true
-
-services:
-  rails:
-    networks:
-      - chatwoot
-      - default  # Only rails needs external access
-```
-
-**2. Secrets Management:**
-```bash
-# Use Docker secrets for sensitive data
-echo "your_secret_password" | docker secret create postgres_password -
-```
-
-## Community Edition vs Enterprise
-
-This guide covers Chatwoot Community Edition (CE). For Enterprise features:
-
-**CE Docker Tags:**
-- `chatwoot/chatwoot:latest-ce` (latest CE)
-- `chatwoot/chatwoot:v2.3.2-ce` (specific version CE)
-
-**Enterprise Features:**
-- Advanced reporting and analytics
-- SAML SSO integration
-- Advanced automation rules
-- Priority support
-
----
-
-<Warning>
-Always test upgrades in a staging environment before applying to production. Keep regular backups of your database and file storage.
-</Warning>
-
-<Note>
-For high-availability deployments, consider using Docker Swarm or Kubernetes instead of Docker Compose.
-</Note> 
+If you want to run Chatwoot CE edition, replace the docker image tag with equivalent foss version tag. Docker tag for current `master` would be `latest-ce`. Version specific tags would follow the pattern `v*-ce`. For example the docker ce edition tag for Chatwoot `v2.3.2` would be `v2.3.2-ce`. 

developer-docs/self-hosted/deployment/kubernetes.mdx

@@ -1,537 +1,234 @@
 ---
-title: Kubernetes Deployment
-description: Deploy Chatwoot on Kubernetes using Helm charts for scalable, production-ready installations
+title: Deploy Chatwoot on Kubernetes using Helm Charts
+description: Deploy Chatwoot on Kubernetes using our official Helm charts
 sidebarTitle: Kubernetes
 ---
 
-# Kubernetes Deployment Guide
+This guide will help you to deploy a production ready Chatwoot instance with Helm Charts.
 
-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
+To quickly try out the charts, follow the two steps below. For a production deployment, please make sure to pass in the required arguments to helm using your custom `values.yaml` file.
 
 ```bash
 helm repo add chatwoot https://chatwoot.github.io/charts
+helm install chatwoot chatwoot/chatwoot
+```
+
+<iframe frameborder="0" scrolling="no" marginheight="0" marginwidth="0"width="100%" height="443" type="text/html" src="https://www.youtube-nocookie.com/embed/o1jnYfy8CCo"></iframe>
+
+## Prerequisites
+
+- Kubernetes 1.16+
+- Helm 3.1.0+
+- PV provisioner support in the underlying infrastructure
+
+The helm installation will create 3 "Persistent Volume Claims" for redis, rails and postgres. Setup up a default "Storage Class" (for automatic PV) or create 3 "Persistent Volumes" with the size of 8GB, before installing chatwoot. If the "Persistent Volume Claims" do not claim the "Persistent Volumes", leave storageClassName blank (inside the PV .yaml files).
+
+## Installing the chart
+
+To install the chart with the release name `chatwoot`, use the following. To deploy it in `chatwoot` namespace, pass `-n chatwoot` to the command.
+
+```bash
+helm install chatwoot chatwoot/chatwoot -f <your-custom-values.yaml> #-n chatwoot
+```
+
+The command deploys Chatwoot on the Kubernetes cluster in the default configuration. The [parameters](#parameters) section lists the parameters that can be configured during installation.
+
+<Tip>
+List all releases using `helm list`
+</Tip>
+
+## Uninstalling the chart
+
+To uninstall/delete the `chatwoot` deployment:
+
+```bash
+helm delete chatwoot
+```
+
+The command removes all the Kubernetes components associated with the chart and deletes the release.
+
+<Note>
+Persistent volumes are not deleted automatically. They need to be removed manually.
+</Note>
+
+## Parameters
+
+### Chatwoot Image parameters
+
+| Name                | Description                                          | Value                  |
+| ------------------- | ---------------------------------------------------- | ---------------------- |
+| `image.repository`  | Chatwoot image repository                            | `chatwoot/chatwoot`    |
+| `image.tag`         | Chatwoot image tag (immutable tags are recommended)  | `v2.16.0`              |
+| `image.pullPolicy`  | Chatwoot image pull policy                           | `IfNotPresent`         |
+
+### Chatwoot Environment Variables
+
+| Name                                 | Type                                                                | Default Value                                              |
+| ------------------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `env.ACTIVE_STORAGE_SERVICE`         | Storage service. `local` for disk. `amazon` for s3.                 | `"local"`                                                  |
+| `env.ASSET_CDN_HOST`                 | Set if CDN is used for asset delivery.                              | `""`                                                       |
+| `env.INSTALLATION_ENV`               | Sets chatwoot installation method.                                  | `"helm"`                                                   |
+| `env.ENABLE_ACCOUNT_SIGNUP`          | `true` : default option, allows sign ups, `false` : disables all the end points related to sign ups, `api_only`: disables the UI for signup but you can create sign ups via the account apis.  | `"false"`                                                  |
+| `env.FORCE_SSL`                      | Force all access to the app over SSL, default is set to false.                  | `"false"`                                                  |
+| `env.FRONTEND_URL`                   | Replace with the URL you are planning to use for your app.                      | `"http://0.0.0.0:3000/"`                                   |
+| `env.IOS_APP_ID`                     | Change this variable only if you are using a custom build for mobile app.       | `"6C953F3RX2.com.chatwoot.app"`                            |
+| `env.ANDROID_BUNDLE_ID`              | Change this variable only if you are using a custom build for mobile app.       | `"com.chatwoot.app"`                                       |
+| `env.ANDROID_SHA256_CERT_FINGERPRINT`| Change this variable only if you are using a custom build for mobile app.       | `"AC:73:8E:DE:EB:5............"`                           |
+| `env.MAILER_SENDER_EMAIL`            | The email from which all outgoing emails are sent.                              | `""`                                                       |
+| `env.RAILS_ENV`                      | Sets rails environment.                                                         | `"production"`                                             |
+| `env.RAILS_MAX_THREADS`              | Number of threads each worker will use.                                         | `"5"`                                                      |
+| `env.SECRET_KEY_BASE`                | Used to verify the integrity of signed cookies. Ensure a secure value is set.   | `replace_with_your_super_duper_secret_key_base`            |
+| `env.SENTRY_DSN`                     | Sentry data source name.                                                        | `""`                                                       |
+| `env.SMTP_ADDRESS`                   | Set your smtp address.                                                          |`""`                                                        |
+| `env.SMTP_AUTHENTICATION`            | Allowed values: `plain`,`login`,`cram_md5`                                      | `"plain"`                                                  |
+| `env.SMTP_ENABLE_STARTTLS_AUTO`      | Defaults to true.                                                               | `"true"`                                                   |
+| `env.SMTP_OPENSSL_VERIFY_MODE`       | Can be: `none`, `peer`, `client_once`, `fail_if_no_peer_cert`                   | `"none"`                                                   |
+| `env.SMTP_PASSWORD`                  | SMTP password                                                                   | `""`                                                       |
+| `env.SMTP_PORT`                      | SMTP port                                                                       | `"587"`                                                    |
+| `env.SMTP_USERNAME`                  | SMTP username                                                                   | `""`                                                       |
+| `env.USE_INBOX_AVATAR_FOR_BOT`       | Bot customizations                                                              | `"true"`                                                   |
+
+### Email setup for conversation continuity (Incoming emails)
+
+| Name                                | Type                                                                                                                                                    | Default Value |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `env.MAILER_INBOUND_EMAIL_DOMAIN`   | This is the domain set for the reply emails when conversation continuity is enabled.                                                                    | `""`          |
+| `env.RAILS_INBOUND_EMAIL_SERVICE`   | Set this to appropriate ingress channel with regards to incoming emails. Possible values are `relay`, `mailgun`, `mandrill`, `postmark` and `sendgrid`. | `""`          |
+| `env.RAILS_INBOUND_EMAIL_PASSWORD`  | Password for the email service.                                                                                                                         | `""`          |
+| `env.MAILGUN_INGRESS_SIGNING_KEY`   | Set if using mailgun for incoming conversations.                                                                                                        | `""`          |
+| `env.MANDRILL_INGRESS_API_KEY`      | Set if using mandrill for incoming conversations.                                                                                                       | `""`          |
+
+### Postgres variables
+
+| Name                                | Type                                                                          | Default Value                                    |
+| ----------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------ |
+| `postgresql.enabled`                | Set to `false` if using external postgres and modify the below variables.     | `true`                                           |
+| `postgresql.auth.database`     | Chatwoot database name                                                        | `chatwoot_production`                            |
+| `postgresql.postgresqlHost`         | Postgres host. Edit if using external postgres.                               | `""`                                             |
+| `postgresql.auth.postgresPassword`     | Postgres password. Edit if using external postgres.                           | `postgres`                                       |
+| `postgresql.postgresqlPort`         | Postgres port                                                                 | `5432`                                           |
+| `postgresql.auth.username`     | Postgres username.                                                            | `postgres`                                       |
+
+### Redis variables
+
+| Name                                | Type                                                                       | Default Value                                       |
+| ----------------------------------- | -------------------------------------------------------------------------  | --------------------------------------------------- |
+| `redis.auth.password`               | Password used for internal redis cluster                                   | `redis`                                             |
+| `redis.enabled`                     | Set to `false` if using external redis and modify the below variables.     | `true`                                              |
+| `redis.host`                        | Redis host name                                                            | `""`                                                |
+| `redis.port`                        | Redis port                                                                 | `""`                                                |
+| `redis.password`                    | Redis password                                                             | `""`                                                |
+| `env.REDIS_TLS`                     | Set to `true` if TLS(`rediss://`) is required                              | `false`                                             |
+| `env.REDIS_SENTINELS`               | Redis Sentinel can be used by passing list of sentinel host and ports.     | `""`                                                |
+| `env.REDIS_SENTINEL_MASTER_NAME`    | Redis sentinel master name is required when using sentinel.                | `""`                                                |
+
+### Logging variables
+
+| Name                                | Type                                                                | Default Value                                              |
+| ----------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `env.RAILS_LOG_TO_STDOUT`           | string                                                              | `"true"`                                                   |
+| `env.LOG_LEVEL`                     | string                                                              | `"info"`                                                   |
+| `env.LOG_SIZE`                      | string                                                              | `"500"`                                                    |
+
+### Third party credentials
+
+| Name                                | Type                                                                 | Default Value                                              |
+| ----------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `env.S3_BUCKET_NAME`                | S3 bucket name                                                       | `""`                                                       |
+| `env.AWS_ACCESS_KEY_ID`             | Amazon access key ID                                                 | `""`                                                       |
+| `env.AWS_REGION`                    | Amazon region                                                        | `""`                                                       |
+| `env.AWS_SECRET_ACCESS_KEY`         | Amazon secret key ID                                                 | `""`                                                       |
+| `env.FB_APP_ID`                     | For facebook channel https://www.chatwoot.com/docs/facebook-setup    | `""`                                                       |
+| `env.FB_APP_SECRET`                 | For facebook channel                                                 | `""`                                                       |
+| `env.FB_VERIFY_TOKEN`               | For facebook channel                                                 | `""`                                                       |
+| `env.SLACK_CLIENT_ID`               | For slack integration                                                | `""`                                                       |
+| `env.SLACK_CLIENT_SECRET`           | For slack integration                                                | `""`                                                       |
+| `env.TWITTER_APP_ID`                | For twitter channel                                                  | `""`                                                       |
+| `env.TWITTER_CONSUMER_KEY`          | For twitter channel                                                  | `""`                                                       |
+| `env.TWITTER_CONSUMER_SECRET`       | For twitter channel                                                  | `""`                                                       |
+| `env.TWITTER_ENVIRONMENT`           | For twitter channel                                                  | `""`                                                       |
+
+### Autoscaling
+
+| Name                                | Type                                                                 | Default Value                                              |
+| ----------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `web.hpa.enabled`                   | Horizontal Pod Autoscaling for Chatwoot web                          | `false`                                                    |
+| `web.hpa.cputhreshold`              | CPU threshold for Chatwoot web                                       | `80`                                                       |
+| `web.hpa.minpods`                   | Minimum number of pods for Chatwoot web                              | `1`                                                        |
+| `web.hpa.maxpods`                   | Maximum number of pods for Chatwoot web                              | `10`                                                       |
+| `web.replicaCount`                  | No of web pods if hpa is not enabled                                 | `1`                                                        |
+| `worker.hpa.enabled`                | Horizontal Pod Autoscaling for Chatwoot worker                       | `false`                                                    |
+| `worker.hpa.cputhreshold`           | CPU threshold for Chatwoot worker                                    | `80`                                                       |
+| `worker.hpa.minpods`                | Minimum number of pods for Chatwoot worker                           | `2`                                                        |
+| `worker.hpa.maxpods`                | Maximum number of pods for Chatwoot worker                           | `10`                                                       |
+| `worker.replicaCount`               | No of worker pods if hpa is not enabled                              | `1`                                                        |
+
+## Install with custom parameters
+
+Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example,
+
+```bash
+helm install my-release \
+  --set env.FRONTEND_URL="chat.yourdomain.com"\
+    chatwoot/chatwoot
+```
+
+The above command sets the Chatwoot server frontend URL to `chat.yourdoamain.com`.
+
+Alternatively, a YAML file that specifies the values for the parameters can be provided while installing the chart. For example,
+
+```bash
+helm install my-release -f values.yaml chatwoot/chatwoot
+```
+
+<Tip>
+You can use the default `values.yaml` file.
+</Tip>
+
+## Postgres
+
+PostgreSQL is installed along with the chart if you choose the default setup. To use an external Postgres DB, please set `postgresql.enabled` to `false` and set the variables under the Postgres section above.
+
+## Redis
+
+Redis is installed along with the chart if you choose the default setup. To use an external Redis DB, please set `redis.enabled` to `false` and set the variables under the Redis section above.
+
+## Autoscaling
+
+To enable horizontal pod autoscaling, set `web.hpa.enabled` and `worker.hpa.enabled` to `true`. Also make sure to uncomment the values under, `resources.limits` and `resources.requests`. This assumes your k8s cluster is already having a metrics-server. If not, deploy metrics-server with the following command.
+
+```bash
+kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
+```
+
+## Upgrading
+
+Do `helm repo update` and check the version of charts that is going to be installed. Helm charts follows semantic versioning and so if the MAJOR version is different from your installed version, there might be breaking changes. Please refer to the changelog before upgrading.
+
+```bash
+# update helm repositories
 helm repo update
+# list your current installed version
+helm list
+# show the latest version of charts that is going to be installed
+helm search repo chatwoot
 ```
 
-### 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
+#if it is major version update, refer to the changelog before proceeding
+helm upgrade chatwoot chatwoot/chatwoot -f <your-custom-values>.yaml
 ```
 
 ## Troubleshooting
 
-### Common Issues
+### pod has unbound immediate PersistentVolumeClaims
+
+Make sure the "Persistent Volume Claims" can be satisfied. Refer to [prerequisites](#prerequisites).
+
+### ActionController::InvalidAuthenticityToken HTTP Origin header
 
-<Tip>
-**Pod Startup Issues**: Check resource limits and node capacity
-```bash
-kubectl describe pod <pod-name> -n chatwoot
-kubectl top nodes
 ```
-</Tip>
-
-<Warning>
-**Database Connection Issues**: Verify database credentials and network policies
-```bash
-kubectl logs deployment/chatwoot -n chatwoot
-kubectl exec -it deployment/chatwoot -n chatwoot -- nc -zv postgres-host 5432
-```
-</Warning>
-
-### Debug Commands
-
-```bash
-# Check pod status
-kubectl get pods -n chatwoot
-
-# View logs
-kubectl logs -f deployment/chatwoot -n chatwoot
-
-# Access pod shell
-kubectl exec -it deployment/chatwoot -n chatwoot -- /bin/bash
-
-# Check service endpoints
-kubectl get endpoints -n chatwoot
-
-# Describe ingress
-kubectl describe ingress chatwoot -n chatwoot
+ActionController::InvalidAuthenticityToken HTTP Origin header (https://mydomain.com) didn't match request.base_url (http://mydomain.com)
 ```
 
-### 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. 
+If you are recieving the above error when trying to access the superadmin panel, configure your ingress controller to forward the protocol of the origin request. For `nginx` ingress, you can do this by setting the `proxy_set_header X-Forwarded-Proto https;` config. Refer this [issue](https://github.com/chatwoot/chatwoot/issues/5506) to learn more. 

developer-docs/self-hosted/deployment/linux-vm.mdx

@@ -1,675 +1,187 @@
 ---
-title: Linux VM Deployment Guide
-description: Complete guide to deploy Chatwoot on Linux virtual machines using the automated installation script.
+title: Production deployment guide for Linux VM
+description: Deploy Chatwoot on Ubuntu 24.04 LTS 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.
+## Deploying to Linux VM
 
-## Prerequisites
+This guide will help you install **Chatwoot** on **Ubuntu 24.04 LTS**. We have prepared a deployment script for you to run. Refer to the script and feel free to make changes accordingly to the operating system if you are on a non-Ubuntu system.
 
-Before starting, ensure you have:
+<iframe width="100%" height="443" src="https://www.youtube-nocookie.com/embed/vu_61D1VFAk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
-- 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
+## Steps to install
 
-### Supported Operating Systems
+<Note>
+If you plan to use a domain with chatwoot, please add an A record before proceeding. Refer to the `Configuring the installation domain` section below.
+</Note>
 
-| 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
+### 1. Create an install.sh file
 
 ```bash
-# Download the installation script
 wget https://get.chatwoot.app/linux/install.sh
-
-# Make it executable
 chmod +x install.sh
 ```
 
-### 2. Run Installation
+### 2. Execute the script
+
+The script will take care of the initial **Chatwoot** setup.
 
 ```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. Access your installation
 
-### 3. Domain Configuration (Optional)
+**Chatwoot** Installation will now be accessible at `http://{your_ip_address}:3000` or if you opted for domain setup, it will be at `https://chatwoot.mydomain.com`.
 
-If you have a domain name:
+<Note>
+This will also install the Chatwoot CLI(`cwctl`) starting with Chatwoot v2.7.0. Use `cwctl --help` to learn more.
+</Note>
 
-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
+## Configuring The installation Domain
 
-### 4. Access Your Installation
+1. Create an `A` record for `chatwoot.mydomain.com` on your domain management system and point it towards the installation IP address.
+2. Continue with the installation script by entering `yes` when prompted about domain setup.
+3. Enter your domain. The script will take care of configuring Nginx and SSL via LetsEncrypt.
+4. Your Chatwoot installation should be accessible from `https://chatwoot.mydomain.com` now.
 
-- **With domain**: `https://your-domain.com`
-- **Without domain**: `http://your-server-ip:3000`
+## Configure the required environment variables
 
-**Default login credentials:**
-```
-URL: https://your-domain.com
-Email: john@acme.inc
-Password: Password1!
-```
+For your Chatwoot installation to properly function, you would need to configure the essential environment variables like `FRONTEND_URL`, Mailer, and a cloud storage config. Refer **[Environment variables](/docs/self-hosted/configuration/environment-variables)** for the full list.
 
-## Manual Installation
-
-For more control over the installation process, you can install manually:
-
-### 1. System Preparation
+### 1. Login as chatwoot user and edit the .env file
 
 ```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
+# Login as 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:**
+### 2. Update environment variables
 
-```env
-# Database Configuration
-DATABASE_URL=postgresql://chatwoot:your_secure_password@localhost:5432/chatwoot
+Refer **[Environment variables](/docs/self-hosted/configuration/environment-variables)** and update the required variables. Save the `.env` file.
 
-# Redis Configuration
-REDIS_URL=redis://localhost:6379/0
-REDIS_PASSWORD=your_redis_password
+### 3. Restart the Chatwoot server
 
-# 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
+<Note>
+If you have Chatwoot CLI(`cwctl`) installed, use `cwctl -r`.
+</Note>
 
 ```bash
-# Prepare the database
-RAILS_ENV=production bundle exec rails db:chatwoot_prepare
-
-# Precompile assets
-RAILS_ENV=production bundle exec rails assets:precompile
+sudo systemctl restart chatwoot.target
 ```
 
-### 6. Configure Systemd Services
+## Upgrading to a newer version of Chatwoot
 
-Create systemd service files:
+Whenever a new version of Chatwoot is released, use the following steps to upgrade your instance.
 
-**Web Service (`/etc/systemd/system/chatwoot-web.1.service`):**
-```ini
-[Unit]
-Description=Chatwoot web server
-After=network.target
+<Note>
+If you have Chatwoot CLI(`cwctl`) installed, use `cwctl --upgrade` to upgrade your Chatwoot installation.
+</Note>
 
-[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
+To install `cwctl`, refer [this](#install-or-upgrade-chatwoot-cli) section below.
 
-[Install]
-WantedBy=multi-user.target
-```
+<Note>
+If you are on an older version of Chatwoot(< 2.7), follow the manual upgrade steps below if you face errors with `cwctl`.
+</Note>
 
-**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:
+Run the following steps on your VM. Make changes based on your OS if you are on a non-Ubuntu system.
 
 ```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
+# Login as Chatwoot user
 sudo -i -u chatwoot
+
+# Navigate to the Chatwoot directory
 cd chatwoot
 
-# Pull latest changes
+# Pull the latest version of the master branch
 git checkout master && git pull
 
-# Update Ruby version if needed
+# Ensure the ruby version is upto date
 rvm install "ruby-3.3.3"
 rvm use 3.3.3 --default
 
 # Update dependencies
-bundle install
-pnpm install
+bundle
+pnpm i
 
-# Precompile assets
-RAILS_ENV=production bundle exec rails assets:precompile
+# Recompile the assets
+rake assets:precompile RAILS_ENV=production
 
-# Run database migrations
-RAILS_ENV=production bundle exec rails db:migrate
+# Migrate the database schema
+RAILS_ENV=production bundle exec rake db:migrate
 
-# Exit to root user
+# Switch back 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/
+# Copy the updated targets
+cp /home/chatwoot/chatwoot/deployment/chatwoot-web.1.service /etc/systemd/system/chatwoot-web.1.service
+cp /home/chatwoot/chatwoot/deployment/chatwoot-worker.1.service /etc/systemd/system/chatwoot-worker.1.service
+cp /home/chatwoot/chatwoot/deployment/chatwoot.target /etc/systemd/system/chatwoot.target
 
-# Reload and restart services
-sudo systemctl daemon-reload
-sudo systemctl restart chatwoot.target
+# Reload systemd files
+systemctl daemon-reload
+
+# Restart the chatwoot server
+systemctl restart chatwoot.target
 ```
 
-### Backup and Restore
+## Running Rails Console
 
-**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
+<Note>
+If you have Chatwoot CLI(`cwctl`) installed, use `cwctl -c`.
+</Note>
 
 ```bash
-# Using cwctl
-cwctl -c
-
-# Manual access
+# Login as Chatwoot user
 sudo -i -u chatwoot
+
+# Navigate to the Chatwoot directory
 cd chatwoot
-RAILS_ENV=production bundle exec rails console
+
+# start rails console
+RAILS_ENV=production bundle exec rails c
 ```
 
+## Viewing Logs
+
+<Note>
+If you have Chatwoot CLI(`cwctl`) installed, use `cwctl -l web` or `cwctl -l worker`.
+</Note>
+
+Run the following commands in your ubuntu shell
+
+```bash
+# logs from the rails server
+journalctl -u chatwoot-web.1.service -f
+
+# logs from sidekiq
+journalctl -u chatwoot-worker.1.service -f
+```
+
+## Install or Upgrade Chatwoot CLI
+
+If you used an older version of install script(< 2.0), you will not have `cwctl` in your PATH. To install/upgrade Chatwoot CLI,
+
+```bash
+wget https://get.chatwoot.app/linux/install.sh -O /usr/local/bin/cwctl && chmod +x /usr/local/bin/cwctl
+cwctl --help
+```
+
+<Note>
+The above command requires root access to install `cwctl` to `/usr/local/bin`.
+</Note>
+
 ## Troubleshooting
 
-### Common Issues
+### If precompile fails
+
+If the asset precompilation step fails with `ActionView::Template::Error (Webpacker can't find application.css in /home/chatwoot/chatwoot/public/packs/manifest.json)` or if you face issues while restarting the server, try the following command and restart the server.
 
-**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
+RAILS_ENV=production rake assets:clean assets:clobber assets:precompile
 ```
 
-**2. Database Connection Issues:**
-```bash
-# Check PostgreSQL status
-sudo systemctl status postgresql
-
-# Test database connection
-sudo -u postgres psql -c "SELECT version();"
-
-# Check database configuration
-sudo -i -u chatwoot
-cd chatwoot
-RAILS_ENV=production bundle exec rails db:version
-```
-
-**3. Permission Issues:**
-```bash
-# Fix file permissions
-sudo chown -R chatwoot:chatwoot /home/chatwoot/chatwoot/
-```
-
-**4. Service Won't Start:**
-```bash
-# Check service logs
-sudo journalctl -u chatwoot-web.1.service --no-pager
-sudo journalctl -u chatwoot-worker.1.service --no-pager
-
-# Check configuration
-sudo systemctl status chatwoot.target
-```
-
-### Performance Optimization
-
-**1. Database Optimization:**
-```sql
--- Connect to database
-sudo -u postgres psql chatwoot
-
--- Check database size
-SELECT pg_size_pretty(pg_database_size('chatwoot'));
-
--- Check slow queries (if pg_stat_statements is enabled)
-SELECT query, mean_time, calls 
-FROM pg_stat_statements 
-ORDER BY mean_time DESC 
-LIMIT 10;
-```
-
-**2. System Optimization:**
-```bash
-# Increase file limits for chatwoot user
-echo "chatwoot soft nofile 65536" | sudo tee -a /etc/security/limits.conf
-echo "chatwoot hard nofile 65536" | sudo tee -a /etc/security/limits.conf
-
-# Optimize PostgreSQL configuration
-sudo nano /etc/postgresql/*/main/postgresql.conf
-# Adjust shared_buffers, effective_cache_size, work_mem based on available RAM
-```
-
-### Security Hardening
-
-**1. Firewall Configuration:**
-```bash
-# Install and configure UFW
-sudo ufw enable
-sudo ufw default deny incoming
-sudo ufw default allow outgoing
-sudo ufw allow ssh
-sudo ufw allow 80/tcp
-sudo ufw allow 443/tcp
-```
-
-**2. Fail2ban Setup:**
-```bash
-# Install Fail2ban
-sudo apt install -y fail2ban
-
-# Configure Fail2ban for SSH
-sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
-sudo systemctl enable fail2ban
-sudo systemctl start fail2ban
-```
-
-**3. Regular Updates:**
-```bash
-# Create update script
-cat > /home/chatwoot/update_system.sh << 'EOF'
-#!/bin/bash
-sudo apt update
-sudo apt upgrade -y
-sudo apt autoremove -y
-sudo apt autoclean
-EOF
-
-chmod +x /home/chatwoot/update_system.sh
-
-# Add to crontab for weekly updates
-echo "0 2 * * 0 /home/chatwoot/update_system.sh" | sudo crontab -
-```
-
----
-
-<Warning>
-Always test upgrades in a staging environment before applying to production. Keep regular backups of your database and application files.
-</Warning>
-
-<Note>
-For high-availability deployments, consider setting up multiple servers with load balancing and database replication.
-</Note> 
+This command would clear the existing compiled assets and would recompile all the assets. Read more about it [here](https://edgeguides.rubyonrails.org/command_line.html#bin-rails-assets)