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 -yReboot if any kernel updates were applied.
sudo rebootStep 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 enableVerify the firewall rules are in place:
sudo ufw statusThe 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.shRun the installer with the --install flag:
sudo ./install.sh --installThe 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
chatwootsystem 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-vmStep 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 -yRemove the default Nginx site and create a new virtual host for Chatwoot.
sudo unlink /etc/nginx/sites-enabled/defaultCreate the Chatwoot Nginx configuration file:
sudo vi /etc/nginx/sites-available/chatwoot.confAdd 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 -tIf the syntax test passes, reload Nginx to apply changes:
sudo systemctl reload nginxStep 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 -yRequest the certificate. Replace chat.example.com with your domain and provide a valid email address:
sudo certbot --nginx -d chat.example.comCertbot modifies your Nginx configuration to serve traffic over HTTPS and sets up automatic certificate renewal. Verify auto-renewal is working:
sudo certbot renew --dry-runIf 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 ~/chatwootOpen the environment file:
vi .envUpdate 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-passwordThe 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:
exitStep 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.targetThis 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.serviceThe 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.serviceThe 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.targetStep 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 --helpRestart all Chatwoot services:
sudo cwctl -rUpgrade Chatwoot to the latest version:
sudo cwctl --upgradeCheck Chatwoot logs for troubleshooting:
sudo cwctl -l webTo view Sidekiq worker logs:
sudo cwctl -l workerTroubleshooting 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 postgresqlRedis not running: Sidekiq and caching require Redis. Check its status.
sudo systemctl status redis-serverNginx 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-pagerPort 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 3000DNS not resolving: Confirm your domain’s A record points to the server IP. Use dig to verify.
dig +short chat.example.comConclusion
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.
