How to Self-Host Chatwoot: A Complete Step-by-Step Guide

by Krishna R 8 months ago 4 min read

A Comprehensive Guide to Self-Hosting Chatwoot with Dokku on ARM64 Architecture

Chatwoot is an open-source customer engagement platform that allows businesses to manage customer interactions across various channels in a unified interface. While Chatwoot offers a hosted service, self-hosting it provides more control over data, security, and customizations. In this guide, we’ll walk through the process of self-hosting Chatwoot on any ARM64-based device using Dokku, a lightweight platform for managing and deploying Docker-based applications.

We’ll cover everything you need, from building the necessary Docker image for ARM64 architecture to deploying Chatwoot with PostgreSQL, configuring your environment, and addressing common issues.

Why Self-Host Chatwoot?

Self-hosting Chatwoot offers several advantages:

Full Control: Customize and optimize the infrastructure to meet your needs.
Cost Efficiency: Avoid ongoing subscription fees by running the service on your own hardware.
Scalability: Scale the application based on your requirements and available resources.

This guide will show you how to get your Chatwoot instance up and running on an ARM64-based environment, which could be anything from a cloud server to a device like Apple Silicon (M1/M2) or other ARM-based hardware.

Prerequisites

To get started, make sure you have:

A server or device based on ARM64 architecture (e.g., Apple Silicon, cloud instance, or ARM-based hardware).
Dokku installed on your server to manage the app deployment.
A PostgreSQL instance for the database.
Docker and Docker Buildx installed and set up for multi-platform builds.

Step 1: Set Up Dokku on Your ARM64 Server

Dokku makes managing and deploying applications simple by leveraging Docker under the hood. If you don’t already have Dokku installed on your server, follow these steps to get it set up.

Install Dokku

To install Dokku on your ARM64-based machine, run the following commands:

wget https://dokku.com/install/v0.27.3/bootstrap.sh
sudo DOKKU_TAG=v0.27.3 bash bootstrap.sh

Once Dokku is installed, you can access its web interface via the server’s IP address or domain name to configure it further.

Step 2: Clone the Chatwoot Repository

Next, clone the Chatwoot repository from GitHub to get the latest version of the source code. For this guide, we’ll use version v3.9.0.

git clone https://github.com/chatwoot/chatwoot.git
cd chatwoot
git checkout tags/v3.9.0

Remove Enterprise Features (Optional)

If you’re looking to use only the open-source edition of Chatwoot, you can remove the enterprise-specific features:

rm -rf spec/enterprise
rm -rf enterprise
echo -en '\nENV CW_EDITION="ce"' >> docker/Dockerfile

This ensures that only the community edition features are built and deployed.

Step 3: Build the Docker Image for ARM64

Since you’re working on an ARM64-based system (e.g., Apple Silicon or ARM servers), you need to build the Docker image specifically for ARM64. Docker’s Buildx tool makes this easy.

Build the ARM64 Docker Image

Run the following command to build the Chatwoot Docker image for ARM64:

docker buildx build --platform linux/arm64 -t USERNAME/chatwoot:v3.9.0-arm64 -f ./docker/Dockerfile .

To push the image to Docker Hub for future use, include the --push flag:

docker image ls
docker push USERNAME/chatwoot:v3.9.0-arm64

This command will create a Docker image that’s compatible with ARM64 devices.

Step 4: Set Up Chatwoot on Dokku

With the Docker image built, the next step is to deploy Chatwoot using Dokku.

Create a New Dokku App

First, create a new Dokku app:

dokku apps:create chatwoot

Set Up PostgreSQL

Chatwoot requires PostgreSQL to store its data. Set up PostgreSQL using Dokku’s PostgreSQL plugin:

dokku postgres:create chatwoot_db
dokku postgres:link chatwoot_db chatwoot

This command creates a PostgreSQL instance and links it to your Chatwoot app.

Set Environment Variables

Now, configure the environment variables required for Chatwoot to function properly:

dokku config:set chatwoot RAILS_ENV=production
dokku config:set chatwoot POSTGRES_HOST=your_postgres_host
dokku config:set chatwoot POSTGRES_PORT=your_postgres_port
dokku config:set chatwoot POSTGRES_USERNAME=your_postgres_username
dokku config:set chatwoot POSTGRES_PASSWORD=your_postgres_password

Replace the placeholders with the actual PostgreSQL credentials and host details.

Deploy the Docker Image to Dokku

Add the Dokku app as a Git remote and push your code:

git remote add dokku dokku@yourdomain.com:chatwoot
git push dokku main

This will deploy your Chatwoot instance to Dokku, using the ARM64 Docker image you built earlier.

Step 5: Run Database Migrations

Once the app is deployed, you need to run the required database migrations to set up the schema:

dokku run chatwoot bundle exec rails db:chatwoot_prepare

This command initializes the database and ensures that everything is configured correctly.

Step 6: Fix Common Errors

Issue: `rails: command not found`

If you encounter the error rails: command not found, it’s likely that the Rails binaries aren’t included in the container’s environment. To fix this, ensure that Rails is installed and the necessary paths are configured.

Add this line to your Dockerfile:

RUN gem install rails

Then, make sure that the correct path for Bundler-installed gems is added to your environment:

ENV PATH="/gems/bin:$PATH"

This should resolve any issues with missing Rails commands.

Step 7: Integrate Chatwoot on Your Website

To add Chatwoot’s live chat widget to your website, insert the following JavaScript snippet into the <head> section of your HTML:

<script type="text/javascript">
  (function(d,t) {
        var BASE_URL="https://chatwoot.mydomain.com";
        var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
        g.src=BASE_URL+"/packs/js/sdk.js";
        g.defer = true;
        g.async = true;
        s.parentNode.insertBefore(g,s);
        g.onload=function(){
          window.chatwootSDK.run({
            websiteToken: '9y2eQbHXzttJoj9Yd28NtfAD',
            baseUrl: BASE_URL
          })
        }
      })(document,"script");
</script>

Replace yourdomain.com with the domain where Chatwoot is hosted. This will add the live chat widget to your site.

Step 8: Automate Messages

Chatwoot allows you to automate messages when visitors land on your site. Navigate to Settings > Campaigns and create a new campaign. Set the trigger to "Page Load" and configure the message you want users to see.

Step 9: Access the Rails Console

To interact directly with the application or perform maintenance, you can access the Rails console via Dokku:

dokku run chatwoot RAILS_ENV=production bundle exec rails console

This gives you access to the Rails console in the production environment.

Conclusion

Self-hosting Chatwoot on an ARM64-based server using Dokku provides full control over your customer engagement platform. This guide covered everything from building the Docker image for ARM64 architecture, deploying the Chatwoot app, configuring PostgreSQL, and integrating the live chat widget on your website.

By following this process, you’ll have a fully functional Chatwoot instance that you can customize and scale according to your needs. With full control over the infrastructure, you’ll have the flexibility to tailor the setup to meet specific requirements, making it a great solution for both small projects and large-scale deployments.