How to Install Chatwoot on the Latest Ubuntu and Debian Server

Chatwoot is an open-source customer support platform for live chat, shared inboxes, email, and other messaging channels. Self-hosting gives your team control over conversations, contacts, and attachments while keeping the application on your own infrastructure.

This guide follows Chatwoot's official Docker deployment path on a fresh Ubuntu or Debian VPS. It runs Chatwoot with PostgreSQL and Redis, keeps the services private on the server, and uses NGINX plus Let's Encrypt for the public HTTPS address.

Before You Start

Prepare:

• A fresh Ubuntu or Debian VPS with SSH and sudo access
• A domain or subdomain such as "support.example.com"
• At least 2 vCPUs, 4 GB RAM, and 20 GB SSD for a small installation
• At least 4 vCPUs, 8 GB RAM, and 50 GB SSD for a more comfortable production starting point
• Ports 22, 80, and 443 available
• An SMTP account for invitations, password resets, and notification emails

Create an A record before requesting a certificate:

support.example.com    A    203.0.113.10

Replace the example address with the public IP of your VPS. Chatwoot containers bind the Rails service to localhost, so NGINX will be the only public web entry point.

Update the VPS and Install Dependencies

Update the system:

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl wget nginx certbot python3-certbot-nginx ufw

Allow SSH and web traffic:

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

Install Docker and Compose

Install Docker Engine and the Docker Compose plugin:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo apt install -y docker-compose-plugin
sudo systemctl enable --now docker
rm get-docker.sh

Verify both tools:

docker --version
docker compose version

Download the Chatwoot Deployment Files

Create a dedicated directory:

sudo mkdir -p /opt/chatwoot
sudo chown -R "$USER":"$USER" /opt/chatwoot
cd /opt/chatwoot

Download the current templates from the official Chatwoot repository:

wget -O .env https://raw.githubusercontent.com/chatwoot/chatwoot/develop/.env.example
wget -O docker-compose.yaml https://raw.githubusercontent.com/chatwoot/chatwoot/develop/docker-compose.production.yaml

The templates change over time, so review them before starting the stack. Do not copy a random Compose file from an older tutorial when the official template is available.

Configure Chatwoot

Generate a long secret key:

openssl rand -hex 64

Open the environment file:

nano .env

Set the production URL, the generated secret, strong database and Redis passwords, and production mode:

SECRET_KEY_BASE=paste-the-generated-hex-value-here
FRONTEND_URL=https://support.example.com
FORCE_SSL=true
ENABLE_ACCOUNT_SIGNUP=false
REDIS_PASSWORD=replace-with-a-long-random-password
POSTGRES_PASSWORD=replace-with-another-long-random-password
RAILS_ENV=production
RAILS_LOG_TO_STDOUT=true

Keep the default internal service names "postgres" and "redis"; Docker Compose uses those names to connect the application to its dependencies.

The Compose template intentionally leaves the PostgreSQL password blank. Open it:

nano docker-compose.yaml

Find the PostgreSQL environment section and change the empty password to the value from the environment file:

environment:
  - POSTGRES_DB=chatwoot
  - POSTGRES_USER=postgres
  - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

Using the environment variable keeps the two files synchronized. Never commit either file to a public repository.

Prepare the Database and Start Chatwoot

Check that Compose can parse the configuration:

docker compose config

Prepare the database with Chatwoot's production task:

docker compose run --rm rails bundle exec rails db:chatwoot_prepare

Start the application, worker, PostgreSQL, and Redis services:

docker compose up -d

Check their status:

docker compose ps
curl -I http://127.0.0.1:3000/api

A successful local response confirms that Rails is responding. The service is not yet exposed publicly.

Configure NGINX as a Reverse Proxy

Create a site configuration:

sudo nano /etc/nginx/sites-available/chatwoot

Add the following configuration and replace the domain:

server {
    listen 80;
    listen [::]:80;
    server_name support.example.com;

    underscores_in_headers on;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Authorization $http_authorization;
    }
}

Enable the site and remove the default NGINX page:

sudo ln -s /etc/nginx/sites-available/chatwoot /etc/nginx/sites-enabled/chatwoot
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

Request a free Let's Encrypt certificate:

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

Choose the option that redirects HTTP to HTTPS when Certbot asks. Once the certificate is installed, open:

https://support.example.com

Finish the first-run onboarding flow and create the administrator account. Do not expose PostgreSQL or Redis directly to the internet; both services should remain bound to localhost through the Compose file.

Configure Email and Channels

After logging in:

1. Open the administration settings and confirm the installation URL.
2. Configure SMTP using your mail provider's hostname, port, username, password, and encryption settings.
3. Send a test email to verify invitations and password resets.
4. Create your first inbox and add the channels your team will use.
5. Review user roles and disable public signups unless you intentionally need them.
6. Configure storage and backups for uploaded attachments.

For higher-volume installations, consider object storage and an external PostgreSQL or Redis service instead of keeping every dependency on one VPS.

Maintain and Update Chatwoot

Back up the environment file and the Docker volumes before maintenance. The volumes contain the database, Redis state, and uploaded storage.

To update the containers:

cd /opt/chatwoot
docker compose pull
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
docker compose up -d

Review the official release notes before updating across a major version. The database preparation command is important because new images may require migrations before the application starts correctly.

Troubleshooting

The Chatwoot page shows a gateway error

Check the Rails container and the local endpoint:

docker compose ps
docker compose logs --tail=200 rails
curl -I http://127.0.0.1:3000/api

If Rails is healthy, check NGINX with "sudo nginx -t" and confirm that the proxy points to port 3000.

Database preparation fails

Verify that POSTGRES_PASSWORD is set in the environment file and that the PostgreSQL service uses the same value. Then inspect its logs:

docker compose logs --tail=200 postgres

Do not delete the PostgreSQL volume to solve a password error; that can destroy your Chatwoot data.

Email notifications are not sent

Check SMTP credentials, the SMTP port, and whether the provider requires STARTTLS or implicit TLS. Review the Rails logs after sending a test message:

docker compose logs --tail=200 rails

WebSocket or live updates do not work

Make sure the NGINX configuration includes the Upgrade, Connection, and underscores_in_headers on settings. Reload NGINX after every configuration change.

Frequently Asked Questions

Can Chatwoot run on Debian?

Yes. The Docker deployment is the most portable approach for a Debian or Ubuntu VPS. Check the current Chatwoot system requirements before choosing an older distribution.

Does Chatwoot need PostgreSQL and Redis?

Yes for the standard production Compose deployment. PostgreSQL stores application data, while Redis supports background jobs and caching.

Can I use Chatwoot without a domain?

You can test it through a temporary IP and port mapping, but a domain with HTTPS is strongly recommended for production, browser security, webhooks, and reliable integrations.

Where does Chatwoot store attachments?

The official Compose template uses a persistent Docker volume for local storage. Configure object storage if you need easier migration, larger capacity, or a multi-server deployment.

Get Started

Deploy a CloudBlast VPS with enough CPU, memory, and disk for your support team, connect a domain, and run Chatwoot with Docker and HTTPS. See CloudBlast plans and pricing for a suitable server size.

For version-specific changes, review the official Chatwoot self-hosted guide, Docker deployment guide, and system requirements.