Install Chatwoot on Ubuntu 24.04 with SSL [Guide]

Chatwoot is an open-source customer engagement platform that unifies conversations from live chat, email, Facebook, Twitter, WhatsApp, Instagram, and other channels into a single dashboard. It serves as a self-hosted alternative to Intercom, Zendesk, and Freshdesk – giving you full control over your data and infrastructure.

This guide walks through installing Chatwoot on Ubuntu 24.04 LTS using the official automated installer. We cover the full stack – PostgreSQL, Redis, Ruby, Node.js, Nginx reverse proxy, and Let’s Encrypt SSL via Certbot.

Prerequisites

Before starting, make sure you have:

A server running Ubuntu 24.04 LTS with at least 2 GB RAM and 2 CPU cores (4 GB recommended for production)
Root or sudo access to the server
A registered domain name with an A record pointing to your server’s public IP address
Ports 80 (HTTP) and 443 (HTTPS) open in your firewall
An SMTP mail server or service (SendGrid, Mailgun, Amazon SES) for sending emails

Step 1: Update System Packages

Start by updating all installed packages on your Ubuntu 24.04 server to their latest versions.

sudo apt update && sudo apt upgrade -y

Reboot if any kernel updates were applied.

sudo reboot

Step 2: Configure UFW Firewall

Chatwoot requires HTTP and HTTPS access. If UFW is active, allow the necessary ports.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow OpenSSH
sudo ufw enable

Verify the firewall rules are in place:

sudo ufw status

The output should show ports 80, 443, and 22 allowed:

Status: active

To                         Action      From
--                         ------      ----
80/tcp                     ALLOW       Anywhere
443/tcp                    ALLOW       Anywhere
OpenSSH                    ALLOW       Anywhere
80/tcp (v6)                ALLOW       Anywhere (v6)
443/tcp (v6)               ALLOW       Anywhere (v6)
OpenSSH (v6)               ALLOW       Anywhere (v6)

Step 3: Install Chatwoot on Ubuntu 24.04 Using the Install Script

Chatwoot provides an official installation script that handles the entire stack – it installs Ruby, Node.js, PostgreSQL, Redis, and all required dependencies automatically. Download and run it.

wget https://get.chatwoot.app/linux/install.sh
chmod +x install.sh

Run the installer with the --install flag:

sudo ./install.sh --install

The script is interactive – it asks for your domain name and whether to configure SSL. During installation, the script will:

Install PostgreSQL database server
Install Redis for caching and background job queuing
Install Ruby (via rbenv) and Node.js
Create a chatwoot system user
Clone the Chatwoot repository to /home/chatwoot/chatwoot
Run database migrations and compile assets
Set up systemd services for the web and worker processes

When the installer prompts for domain configuration, enter your fully qualified domain name (e.g., chat.example.com). If you choose to set up SSL during installation, it will also install Nginx as a reverse proxy and configure Let’s Encrypt certificates automatically.

On successful installation, you should see output similar to:

Woot! Woot!! Chatwoot server installation is complete
The server will be accessible at http://<server-ip>:3000
To configure a domain and SSL certificate, follow the guide at https://www.chatwoot.com/docs/deployment/deploy-chatwoot-in-linux-vm

Step 4: Configure Nginx Reverse Proxy for Chatwoot

If the installer did not set up Nginx and SSL for you, or if you skipped that step, configure them manually. Install Nginx first.

sudo apt install nginx -y

Remove the default Nginx site and create a new virtual host for Chatwoot.

sudo unlink /etc/nginx/sites-enabled/default

Create the Chatwoot Nginx configuration file:

sudo vi /etc/nginx/sites-available/chatwoot.conf

Add the following reverse proxy configuration. Replace chat.example.com with your actual domain name:

server {
  server_name chat.example.com;

  # Upstream to Chatwoot application server
  set $upstream 127.0.0.1:3000;

  # Chatwoot API uses underscored headers - allow them
  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;
    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;
}

Enable the site by creating a symbolic link and test the Nginx configuration:

sudo ln -s /etc/nginx/sites-available/chatwoot.conf /etc/nginx/sites-enabled/chatwoot.conf
sudo nginx -t

If the syntax test passes, reload Nginx to apply changes:

sudo systemctl reload nginx

Step 5: Set Up Let’s Encrypt SSL with Certbot

Secure your Chatwoot instance with a free Let’s Encrypt SSL certificate. Install Certbot and the Nginx plugin.

sudo apt install certbot python3-certbot-nginx -y

Request the certificate. Replace chat.example.com with your domain and provide a valid email address:

sudo certbot --nginx -d chat.example.com

Certbot modifies your Nginx configuration to serve traffic over HTTPS and sets up automatic certificate renewal. Verify auto-renewal is working:

sudo certbot renew --dry-run

If the dry run completes without errors, renewal is properly configured and will run automatically via a systemd timer.

Step 6: Configure Chatwoot Environment Variables

Chatwoot stores its configuration in a .env file under the Chatwoot user’s home directory. Switch to the chatwoot user and open the file.

sudo -i -u chatwoot
cd ~/chatwoot

Open the environment file:

vi .env

Update these key settings with your values:

# Application URL - must match your domain
FRONTEND_URL=https://chat.example.com

# SMTP / Email configuration
[email protected]
SMTP_ADDRESS=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=your-smtp-username
SMTP_PASSWORD=your-smtp-password
SMTP_AUTHENTICATION=login
SMTP_ENABLE_STARTTLS_AUTO=true

# Redis (default works if Redis is local)
REDIS_URL=redis://localhost:6379

# PostgreSQL (default works if PostgreSQL is local)
POSTGRES_HOST=localhost
POSTGRES_USERNAME=chatwoot
POSTGRES_PASSWORD=your-db-password

The FRONTEND_URL must be set to your actual domain with HTTPS. Without this, features like email notifications, webhooks, and widget embedding will not work correctly. Exit back to your regular user after saving:

exit

Step 7: Manage Chatwoot Systemd Services

The installer creates systemd services for the Chatwoot web server and Sidekiq background worker. Restart both after making configuration changes.

sudo systemctl restart chatwoot.target

This restarts both chatwoot-web.1.service (the Puma web server) and chatwoot-worker.1.service (Sidekiq for background jobs like sending emails and processing webhooks).

Check that both services are running:

sudo systemctl status chatwoot-web.1.service

The web service should show active (running):

● chatwoot-web.1.service - Chatwoot web server
     Loaded: loaded (/etc/systemd/system/chatwoot-web.1.service; enabled)
     Active: active (running)

Check the worker service as well:

sudo systemctl status chatwoot-worker.1.service

The Sidekiq worker handles background tasks – email delivery, webhook dispatching, and scheduled jobs. If it is not running, those features will silently fail.

Enable both services to start on boot:

sudo systemctl enable chatwoot.target

Step 8: Access Chatwoot Web Interface

Open your browser and navigate to your domain – https://chat.example.com. You should see the Chatwoot setup wizard.

Create the administrator account by providing your full name, email address, and password. After signing in, you can:

Add inboxes for website live chat, email, Facebook, WhatsApp, Instagram, Telegram, and other channels
Invite team members and assign agent roles
Configure automation rules and canned responses
Set up integrations with Slack, Dialogflow, and other tools

Using cwctl – The Chatwoot CLI Tool

Starting from Chatwoot v2.7.0, the cwctl CLI tool is included with the installation. It simplifies common management tasks.

View available commands:

sudo cwctl --help

Restart all Chatwoot services:

sudo cwctl -r

Upgrade Chatwoot to the latest version:

sudo cwctl --upgrade

Check Chatwoot logs for troubleshooting:

sudo cwctl -l web

To view Sidekiq worker logs:

sudo cwctl -l worker

Troubleshooting Chatwoot Installation

If Chatwoot is not accessible after installation, check these common issues:

PostgreSQL not running: The Chatwoot web service depends on PostgreSQL. Verify it is active.

sudo systemctl status postgresql

Redis not running: Sidekiq and caching require Redis. Check its status.

sudo systemctl status redis-server

Nginx proxy errors: If you see 502 Bad Gateway, Chatwoot’s Puma server on port 3000 is not responding. Check the web service logs.

sudo journalctl -u chatwoot-web.1.service -n 50 --no-pager

Port conflicts: Make sure nothing else is using port 3000. If you have Node.js development servers or other applications running on port 3000, stop them first.

sudo ss -tlnp | grep 3000

DNS not resolving: Confirm your domain’s A record points to the server IP. Use dig to verify.

dig +short chat.example.com

Conclusion

You now have Chatwoot running on Ubuntu 24.04 with Nginx as a reverse proxy and Let’s Encrypt SSL termination. The setup includes PostgreSQL for data storage, Redis for caching, and Sidekiq for background job processing.

For production use, set up regular PostgreSQL backups, configure email delivery through a reliable SMTP provider, and monitor disk usage – Chatwoot’s conversation data and file attachments grow over time. Check the official Chatwoot deployment documentation for advanced configuration options including super admin console access and cloud storage setup.