Self-Host Chatwoot on a VPS: Open-Source Omnichannel Support

SaaS customer support solutions have a simple business model: you pay per agent and per channel, and your customer data is stored on their servers. For a web agency or an SME, this can quickly amount to several hundred dollars per month once the team exceeds two or three people. Chatwoot reverses this equation: you deploy the platform on your own VPS, invite as many agents as needed, and connect all your channels at no extra cost. Your customer exchanges stay on your infrastructure — a compelling argument for GDPR compliance, customer trust and data sovereignty.

Chatwoot runs on a Ruby on Rails + Sidekiq + PostgreSQL 15 + Redis 7 stack — four Docker containers. Plan for a VPS with at least 2 GB of RAM (4 GB recommended for teams of more than 10 agents). Ubuntu 24.04 with Docker is the fastest path. On the network side, prepare a subdomain — support.your-domain.com for example — and a reverse proxy (Nginx or Caddy) to enable HTTPS. Chatwoot requires a FRONTEND_URL over HTTPS for OAuth redirects, email links and the livechat widget script to work correctly.

Before you start, verify that Docker Compose v2 is installed (docker compose version): Chatwoot v4 uses the docker compose syntax (with a space) rather than the legacy docker-compose command.

Chatwoot lets you centralise multiple channels in a single interface. Each channel creates an independent inbox, visible in the sidebar and assignable to a dedicated team.

Email (SMTP/IMAP): in Settings → Inboxes → Email, enter your inbound address and IMAP credentials. Chatwoot polls the mailbox every two minutes and creates one conversation per thread. Replies are sent via SMTP while preserving the same thread.

Twitter/X DMs: connect an account via the Twitter v2 API (API key + secret + access token). Incoming direct messages appear in real time via webhook. Note: Twitter v2 API access requires a Basic or higher developer subscription.

Phone and WebRTC: Chatwoot v4.17 migrated its video call integration from Dyte to Cloudflare RealtimeKit. If you use video calls, reconfigure the integration under Settings → Integrations → Cloudflare Calls with your App ID and App Token.

API channel: for custom integrations (chatbot, in-house CRM), create an API-type inbox. It exposes a REST endpoint to receive messages and you send replies via POST /api/v1/accounts/{id}/conversations/{conv_id}/messages. This is the entry point for connecting any external source.

Chatwoot offers several levels of integration to fit into your existing stack.

Webhooks: in Settings → Integrations → Webhooks, add your endpoint URL. Chatwoot fires a JSON event on every conversation created, message received or status changed. Useful for syncing tickets to a CRM, triggering an n8n workflow or logging conversations to your database.

Slack notifications: connect a Slack workspace via OAuth under Settings → Integrations → Slack. New conversations and mentions in Chatwoot generate a notification in the Slack channel of your choice. Agents never miss a message even when outside the interface.

REST API: all Chatwoot resources (conversations, contacts, messages, teams, labels) are exposed by a documented v1 REST API at /swagger. Authentication via token (user_access_token or agent API key). Common use cases: importing contacts from a CRM, reporting on resolved conversations, automatically updating contact attributes.

Zapier / Make (ex-Integromat): Chatwoot has native connectors on Zapier and Make to trigger no-code actions. Example: new Chatwoot conversation → create an opportunity in your CRM → notify the sales team by email.

Minor updates (patch releases like v4.17.0 → v4.17.1) are safe and often contain security fixes: plan them within 48 hours of publication.

For a patch update:

docker compose pull
docker compose down
docker compose up -d
docker compose exec rails bundle exec rails db:migrate

Then check the logs (docker compose logs web --tail=30) and test sending a message on each channel.

For a major upgrade (v3 → v4), the process is more delicate: v4 introduces blocking PostgreSQL schema migrations (restructured mentions and conversation_participants tables). Never run docker compose pull && docker compose up -d without a prior backup on a major version.

Best practice: always pin a specific version in docker-compose.yml (chatwoot/chatwoot:v4.17.1 rather than latest) so you control exactly what runs in production and avoid silent updates.

Chatwoot v4, released in June 2026, introduces the new 'Nova UI' interface and several blocking PostgreSQL schema migrations. An in-place upgrade from v3 will consistently break the instance if done without preparation — this is the subject of official issue #12088, which catalogues the most common failure cases.

The main reason for breakage: v4 renames the mentions table and restructures the conversation_participants table. A docker compose pull && docker compose up -d without a prior backup triggers the migrations automatically; if a migration fails mid-way (timeout, unsatisfied FK constraint), the database is left in an intermediate state and Chatwoot no longer starts.

In practice, three categories of instances are at risk: those running v3 with more than 50,000 conversations (bulk migrations are slow and may exceed Rails' 30-second timeout), those with undocumented custom columns in the contacts table, and those using Sidekiq Pro (removed from Community Edition in v4 — jobs queued at migration time are lost).

Sidekiq workers blocked. If outgoing emails no longer send or webhooks stop firing, Sidekiq is likely stalled or its workers are exhausted. Check via the Sidekiq Web interface (/sidekiq) or logs: docker compose logs sidekiq --tail=50. The most common cause is a saturated mailers queue. Restart the worker: docker compose restart sidekiq. If the issue persists, verify the Redis connection (docker compose exec redis redis-cli ping should return PONG).

Redis connection refused. If Rails and Sidekiq fail to start with Redis::CannotConnectError, the Redis container is not ready. Check its state: docker compose ps redis. A container in Restarting state indicates a volume or permission issue. Remove the Redis volume and restart if the Redis data is transient (queued jobs will be lost).

ActionCable WebSocket not connecting. The livechat widget shows 'connection lost' or agents don't receive messages in real time. Likely cause: the reverse proxy is not forwarding WebSocket headers. With Nginx, add to your location block:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

With Caddy, the reverse_proxy localhost:3000 configuration handles WebSockets automatically.

Migration stuck mid-way. If rails db:migrate stops with an error, do not retry immediately. Identify the failing migration in the error message, fix it manually or skip it (rails db:migrate:up VERSION=<timestamp>), then re-run. As a last resort, restore the backup taken before the migration.