Chore: Add deployment documentation (#904)
Co-authored-by: Pranav Raj S <pranav@thoughtwoot.com>
This commit is contained in:
Sojan Jose
GitHub
parent
e769282e7f
commit
ca7554f88c
6 changed files with 274 additions and 0 deletions
|
|
@ -18,3 +18,11 @@ This guide will help you get started with Chatwoot!
|
|||
* [Environment Variables](/docs/environment-variables)
|
||||
* [Conversation Continuity with Email](/docs/conversation-continuity)
|
||||
* [Common Errors](/docs/common-errors)
|
||||
|
||||
### Deployment
|
||||
|
||||
* [Architecture](/docs/deployment/architecture)
|
||||
* [Heroku](/docs/deployment/deploy-chatwoot-with-heroku) (recommended)
|
||||
* [Caprover](/docs/deployment/deploy-chatwoot-with-caprover) (recommended)
|
||||
* [Docker](/docs/deployment/deploy-chatwoot-with-docker)
|
||||
* [Linux](/docs/deployment/deploy-chatwoot-in-linux-vm)
|
||||
|
|
|
|||
41
docs/deployment/production/architecture.md
Normal file
41
docs/deployment/production/architecture.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
path: "/docs/deployment/architecture"
|
||||
title: "Chatwoot Production deployment guide"
|
||||
---
|
||||
|
||||
This guide will help you to deploy Chatwoot to production!
|
||||
|
||||
## Architecture
|
||||
|
||||
Running Chatwoot in production requires the following set of services.
|
||||
|
||||
* Chatwoot web servers
|
||||
* Chatwoot workers
|
||||
* PostgreSQL Database
|
||||
* Redis Database
|
||||
* Email service (SMTP servers / sendgrid / mailgun etc)
|
||||
* Object Storage ( S3, Azure Storage, GCS, etc)
|
||||
|
||||
|
||||
## 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 upto date with our releases to enjoy the lastest 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.
|
||||
|
||||
```
|
||||
bundle exec rails db:migrate
|
||||
```
|
||||
|
||||
The detailed instructions can be found in respective deployment guides.
|
||||
|
||||
### Available deployment options
|
||||
|
||||
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.
|
||||
|
||||
* [Heroku](/docs/deployment/deploy-chatwoot-with-heroku) (recommended)
|
||||
* [Caprover](/docs/deployment/deploy-chatwoot-with-caprover) (recommended)
|
||||
* [Docker](/docs/deployment/deploy-chatwoot-with-docker)
|
||||
* [Linux](/docs/deployment/deploy-chatwoot-in-linux-vm)
|
||||
57
docs/deployment/production/caprover.md
Normal file
57
docs/deployment/production/caprover.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
path: "/docs/deployment/deploy-chatwoot-with-caprover"
|
||||
title: "Caprover Chatwoot Production deployment guide"
|
||||
---
|
||||
|
||||
## 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 Chatwoot and hence the deployment process is very easy.
|
||||
|
||||
## Install Caprover on your VM
|
||||
|
||||
Finish your caprover installation by referring to [Getting started guid](https://caprover.com/docs/get-started.html).
|
||||
|
||||
## Installing Chatwoot in Caprover
|
||||
|
||||
Chatwoot is available in the one-click apps option in caprover, find Chatwoot by searching and clicking on it. Replace the default `version` with the latest `version` of chatwoot. User appropriate values for the Postgres and Redis passwords and click install. It should only take a few minutes.
|
||||
|
||||
## Configure the necessary environment variables
|
||||
|
||||
Caprover will take care of the installation of Postgres and Redis 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 E-mail, Object Store service etc referring to our [Environment variables guide](./environment-variables)
|
||||
|
||||
## Upgrading Chatwoot installation
|
||||
|
||||
To update your chatwoot installation to the latest version in caprover, Run the following command in deployment tab for web and worker in the method 5: deploy captain-definition
|
||||
|
||||
### web
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 2,
|
||||
"dockerfileLines": [
|
||||
"FROM chatwoot/chatwoot:latest",
|
||||
"RUN chmod +x docker/entrypoints/rails.sh",
|
||||
"ENTRYPOINT [\"docker/entrypoints/rails.sh\"]",
|
||||
"CMD bundle exec rake db:setup; bundle exec rake db:migrate; bundle exec rails s -b 0.0.0.0 -p 3000"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### worker
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 2,
|
||||
"dockerfileLines": [
|
||||
"FROM chatwoot/chatwoot:latest",
|
||||
"RUN chmod +x docker/entrypoints/rails.sh",
|
||||
"ENTRYPOINT [\"docker/entrypoints/rails.sh\"]",
|
||||
"CMD bundle exec sidekiq -C config/sidekiq.yml"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Further references
|
||||
|
||||
- https://isotropic.co/how-to-install-chatwoot-to-a-digitalocean-droplet/
|
||||
32
docs/deployment/production/docker.md
Normal file
32
docs/deployment/production/docker.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
path: "/docs/deployment/deploy-chatwoot-with-docker"
|
||||
title: "Docker Chatwoot Production deployment guide"
|
||||
---
|
||||
|
||||
## Deploying with docker
|
||||
|
||||
We publish our base images to docker hub. Build your web/worker images from these base images
|
||||
|
||||
### Web
|
||||
|
||||
```
|
||||
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"
|
||||
```
|
||||
|
||||
### worker
|
||||
|
||||
```
|
||||
FROM chatwoot/chatwoot:latest
|
||||
RUN chmod +x docker/entrypoints/rails.sh
|
||||
ENTRYPOINT [\"docker/entrypoints/rails.sh\"]
|
||||
CMD bundle exec sidekiq -C config/sidekiq.yml"
|
||||
```
|
||||
|
||||
The app servers will available on port `3000`. Ensure the images are connected to the same database and Redis servers. Provide the configuration for these services via environment variables.
|
||||
|
||||
## Upgrading
|
||||
|
||||
Update the images using the latest image from chatwoot. Run the `rails db:migrate` option after accessing console from one of the containers running latest image.
|
||||
22
docs/deployment/production/heroku.md
Normal file
22
docs/deployment/production/heroku.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
path: "/docs/deployment/deploy-chatwoot-with-Heroku"
|
||||
title: "Heroku Chatwoot Production deployment guide"
|
||||
---
|
||||
|
||||
## Deploying on Heroku
|
||||
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 tabs in Heroku app dashboard and click reveal config vars.
|
||||
4. Configure the environment variables for [mailer](https://www.chatwoot.com/docs/environment-variables#configure-emails) and [storage](https://www.chatwoot.com/docs/configuring-cloud-storage) as per the [documentation](https://www.chatwoot.com/docs/environment-variables).
|
||||
5. Head over to `yourapp.herokuapp.com` and enjoy using Chatwoot.
|
||||
|
||||
|
||||
## 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.
|
||||
114
docs/deployment/production/linux-vm.md
Normal file
114
docs/deployment/production/linux-vm.md
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
---
|
||||
path: "/docs/deployment/deploy-chatwoot-in-linux-vm"
|
||||
title: "Linux VM Chatwoot Production deployment guide"
|
||||
---
|
||||
|
||||
|
||||
## Deploying to Linux VM
|
||||
|
||||
We have prepared a deployment script for ubuntu 18.04. Run the script or refer the script and make changes accordingly to OS.
|
||||
|
||||
https://github.com/chatwoot/chatwoot/blob/develop/deployment/setup.sh
|
||||
|
||||
### After logging in to your Linux VM as the root user perform the following steps for initial set up
|
||||
|
||||
1. Create the `chatwoot.sh` file and copy the content from [deployment script](https://github.com/chatwoot/chatwoot/blob/develop/deployment/setup.sh).
|
||||
2. Execute the script and it will take care of the initial Chatwoot setup
|
||||
3. Chatwoot Installation will now be accessible at `http://{your_ip}:3000`
|
||||
|
||||
### Configure ngix and letsencrypt
|
||||
|
||||
1. configure Nginx to serve as a frontend proxy by following steps in your shell
|
||||
|
||||
```bash
|
||||
cd /etc/nginx/sites-enabled
|
||||
nano yourdomain.com.conf
|
||||
```
|
||||
2. Add the required Nginx config after replacing the `yourdomain.com` in `server_name`
|
||||
```sh
|
||||
server {
|
||||
server_name yourdomain.com;
|
||||
# where rails app is running
|
||||
set $upstream 127.0.0.1:3000;
|
||||
|
||||
# Here we define the web-root for our SSL proof
|
||||
location /.well-known {
|
||||
# Note that a request for /.well-known/test.html will be made
|
||||
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_set_header Connection “”;
|
||||
proxy_buffering off;
|
||||
client_max_body_size 0;
|
||||
proxy_read_timeout 36000s;
|
||||
proxy_redirect off;
|
||||
}
|
||||
listen 80;
|
||||
}
|
||||
```
|
||||
3. Verify and reload your Nginx config by running following command.
|
||||
```sh
|
||||
nginx -t
|
||||
systemctl reload nginx
|
||||
```
|
||||
4. Run Letsencrypt and configure SSL
|
||||
```sh
|
||||
mkdir -p /var/www/ssl-proof/chatwoot/.well-known
|
||||
certbot --webroot -w /var/www/ssl-proof/chatwoot/ -d yourdomain.com -i nginx
|
||||
```
|
||||
|
||||
5. You Chatwoot installation should be accessible from the `https://yourdomain.com` now.
|
||||
|
||||
### Configure the required environment variables
|
||||
For your chatwoot installation to properly function you would need to configure some of the essential environment variables like `FRONTEND_URL`, mailer and storage config etc. refer [environment variables](https://www.chatwoot.com/docs/environment-variables) for the full list.
|
||||
|
||||
1. Login as chatwoot and edit the .env file.
|
||||
```shell
|
||||
# login as chatwoot user
|
||||
sudo -i -u chatwoot
|
||||
cd chatwoot
|
||||
nano .env
|
||||
```
|
||||
2. Refer [environment variables](https://www.chatwoot.com/docs/environment-variables) and update the required variables. Save the `.env` file.
|
||||
3. Restart the Chatwoot server and enjoy using Chatwoot.
|
||||
```sh
|
||||
systemctl restart chatwoot.target
|
||||
```
|
||||
## Updating your Chatwoot Installation on a Linux VM
|
||||
|
||||
Run the following steps on your VM if you made use of our installation script Or making changes accordingly to your OS
|
||||
|
||||
```sh
|
||||
# login as chatwoot user
|
||||
sudo -i -u chatwoot
|
||||
|
||||
# navigate to the chatwoot directory
|
||||
cd chatwoot
|
||||
|
||||
# pull the latest version of the master branch
|
||||
git pull
|
||||
|
||||
# update dependencies
|
||||
bundle
|
||||
yarn
|
||||
|
||||
# recompile the assets
|
||||
rake assets:precompile RAILS_ENV=production
|
||||
|
||||
# migrate the database schema
|
||||
RAILS_ENV=production bundle exec rake db:migrate
|
||||
|
||||
#Restart the chatwoot server
|
||||
systemctl restart chatwoot.target
|
||||
```
|
||||
Loading…
Reference in a new issue