add intro documentation and user guide
This commit is contained in:
Tanmay Deep Sharma
@@ -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.
|
||||
|
||||
|
||||
|
||||
**Step 2**: Select "Web" as delivery method for your content.
|
||||
|
||||
|
||||
|
||||
**Step 3**: Configure the Origin Settings as the following.
|
||||
|
||||
|
||||
|
||||
- Provide your Chatwoot Installation URL under Origin Domain Name.
|
||||
- Select "Origin Protocol Policy" as Match Viewer.
|
||||
|
||||
**Step 4**: Configure Cache behaviour.
|
||||
|
||||
|
||||
|
||||
- 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**.
|
||||
|
||||
- **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.
|
||||
|
||||
|
||||
|
||||
## 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>
|
||||
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user