Self-Hosting Chatwoot with PostgreSQL on a VPS: The Ultimate Guide to Open-Source Omnichannel Customer Engagement

Introduction: The Case for Self-Hosted Customer Engagement

In today's digital marketplace, managing customer communication across multiple channels—such as live chat, email, WhatsApp, Facebook, and Twitter—is critical to business success. However, relying on proprietary, closed-source SaaS platforms often introduces significant challenges, including skyrocketing subscription costs as teams scale and compliance concerns regarding data privacy.

For enterprises and growing startups seeking an alternative, Chatwoot emerges as a powerful, open-source omnichannel customer engagement suite. By self-hosting Chatwoot alongside a robust PostgreSQL database on a Virtual Private Server (VPS), your organization can retain 100% ownership of customer interaction logs, eliminate recurring per-agent licensing fees, and customize the environment to fit precise technical requirements. This guide provides a comprehensive, step-by-step blueprint for deploying Chatwoot on your own infrastructure.

Prerequisites and System Architecture

Before initiating the deployment process, it is essential to prepare the environment. For a standard production environment handling moderate traffic, the following baseline specifications are recommended:

Operating System: Ubuntu 22.04 LTS or Ubuntu 24.04 LTS (Clean installation).
Hardware Resources: Minimum 2 vCPUs, 4GB RAM, and 40GB SSD storage.
Domain Name: A fully qualified domain name (FQDN) with A records pointing to your VPS IP address (e.g., chat.yourcompany.com).
Network: Ports 80 and 443 open for HTTP/HTTPS traffic, and port 22 for SSH access.

Architecturally, Chatwoot relies on a Ruby on Rails backend, a Vue.js frontend, Redis for caching and job queuing, and PostgreSQL as the primary relational database. Hosting these components on a single VPS via managed scripts or Docker simplifies operations while maintaining high performance.

Step 1: Preparing the VPS Environment

Begin by accessing your VPS via SSH and updating the system packages to ensure security patches and dependencies are current. Run the following commands in your terminal:

sudo apt update && sudo apt upgrade -y

Next, configure a basic firewall using UFW (Uncomplicated Firewall) to secure the server, ensuring you do not lock yourself out of SSH access:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Step 2: Database Setup – Optimizing PostgreSQL

Chatwoot requires PostgreSQL (version 12 or higher) to store chat histories, contact information, and agent configurations. While Chatwoot's standalone installer can set up a local database automatically, enterprise environments benefit from explicitly configuring PostgreSQL to handle higher concurrent connections and query caching.

Install PostgreSQL and its contrib modules:

sudo apt install postgresql postgresql-contrib -y

Once installed, log into the PostgreSQL prompt to create a dedicated user and database for Chatwoot, ensuring you replace 'SecurePassword123' with a robust, randomly generated credential:sudo -i -u postgres psql CREATE DATABASE chatwoot_production; CREATE USER chatwoot_admin WITH PASSWORD 'SecurePassword123'; GRANT ALL PRIVILEGES ON DATABASE chatwoot_production TO chatwoot_admin; \q

Security Note: Never use default passwords or usernames in production environments. Restrict PostgreSQL to listen only on localhost (127.0.0.1) unless you are routing traffic from a separate database server.

Step 3: Installing Chatwoot via the Official Deployment Script

The Chatwoot team maintains an official deployment script for Ubuntu that automates the installation of Ruby, Node.js, Redis, and necessary system libraries. This is the most reliable method for standard VPS environments.

Download and execute the deployment script using the following sequence:

mkdir -p ~/.chatwoot && cd ~/.chatwoot
wget [https://get.chatwoot.app/setup](https://get.chatwoot.app/setup)
chmod +x setup
sudo ./setup_apps.sh

During the interactive prompt, the installer will request your domain name and email address to automatically provision an SSL certificate via Let's Encrypt. It will also ask whether you wish to configure an external database. Select Yes and input the PostgreSQL credentials created in Step 2.

Step 4: Configuring Environment Variables

Once the installation script completes, navigate to the Chatwoot directory to configure essential environment variables, including your SMTP email server settings, object storage provider (for chat attachments), and encryption keys.

Open the environment configuration file:

sudo nano /home/chatwoot/chatwoot/.env

Modify the following key parameters to ensure operational readiness:

FRONTEND_URL: Set this to [https://chat.yourcompany.com](https://chat.yourcompany.com).
SECRET_KEY_BASE: Generate a secure random token to sign session cookies.
SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD: Input your transactional email service provider details (e.g., SendGrid, Mailgun, or AWS SES) to enable agent invitations and email notifications.

Save the file and restart the Chatwoot services to apply the configuration:

sudo systemctl restart chatwoot.target

Step 5: Nginx Reverse Proxy and SSL Configuration

To expose Chatwoot securely to the internet, Nginx acts as a reverse proxy, routing incoming traffic from port 443 to the internal Rails application running on port 3000. The automated script configures this by default, but verifying the configuration guarantees stability.

Inspect the Nginx site configuration:

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

Ensure that WebSockets are properly configured within the Nginx block, as Chatwoot relies heavily on real-time data streaming via ActionCable. Look for the following lines within the location block:proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";

Test the Nginx configuration for syntax errors and reload the service:

sudo nginx -t
sudo systemctl reload nginx

Step 6: Post-Deployment Steps and Initial Onboarding

With the server successfully running, navigate to [https://chat.yourcompany.com](https://chat.yourcompany.com) in your web browser. You will be greeted by the initial onboarding wizard.

Create the Admin Account: Enter your name, professional email address, and a strong password. This account will serve as the Super Administrator.
Configure the Organization: Input your company name and default language settings.
Connect Communication Channels: Integrate your website widget, connect business email inboxes, or link API channels like WhatsApp Business.

Conclusion: Embracing Data Sovereignty

Self-hosting Chatwoot on a VPS combined with a dedicated PostgreSQL database grants your organization unparalleled control over your customer support ecosystem. You benefit from absolute data sovereignty, predictable infrastructure costs, and a highly customizable framework that scales seamlessly with your business operations. By following this deployment model, your team is now equipped with a enterprise-grade communication engine built entirely on an open-source foundation.