Why self-host your customer 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 a Moroccan SME, this can quickly amount to several hundred dirhams 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.
What you get with a self-hosted Chatwoot
- Shared omnichannel inbox: livechat, email, WhatsApp, Telegram, Facebook Messenger and Twitter/X DMs in a single dashboard.
- Embeddable livechat widget: a customisable widget to add to any website with two lines of JavaScript.
- Canned responses and automation rules: automatic assignment, first-contact reply and routing by language or keyword.
- Team collaboration: internal notes, conversation assignment, mentions and team queues visible to all agents.
- Integrated CRM: contact profiles with conversation history, custom attributes and labels.
- REST API and webhooks: integration with n8n, Activepieces or your own backend.
- MIT licence — no per-agent pricing, no data sent to a third party, full sovereignty.
Prerequisites
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.
Deploy Chatwoot on a VPS in 6 steps
One-click deployment from the ServOrbit marketplace
Open your ServOrbit control panel, go to Marketplace → Collaboration and productivity → Chatwoot, then click Deploy. Docker pulls
chatwoot/chatwoot:latestand starts four containers: PostgreSQL, Redis, the Rails web server and the Sidekiq worker. On first start, the database migration runs automatically — wait 60 to 90 seconds before the interface becomes available.Create the administrator account
Go to
http://<your-vps-ip>:3000. Chatwoot displays a first-configuration wizard: enter your name, email address and a strong password. This account becomes the super-administrator. You can then invite additional agents and create teams from the Settings panel.Configure FRONTEND_URL and enable HTTPS
Point your domain to the VPS (A record → VPS IP). Install Caddy (
apt install -y caddy) and create/etc/caddy/Caddyfile:support.your-domain.com { reverse_proxy localhost:3000 }. Reload Caddy (systemctl reload caddy). Then setFRONTEND_URL=https://support.your-domain.comin your.envfile and restart the web container:docker compose restart web. Chatwoot uses this URL for OAuth redirects, email links and the widget script.Add your first inbox
In Chatwoot, go to Settings → Inboxes → Add Inbox. Choose Website for livechat, Email for SMTP/IMAP exchanges, or a messaging channel like WhatsApp Cloud API or Telegram. For livechat, copy the generated JavaScript snippet and paste it into the
<head>of your website. Visitors immediately see the chat bubble.Invite agents and configure automation
Go to Settings → Agents and send email invitations. In Settings → Automation, create rules to automatically assign conversations (for example, WhatsApp → sales team, email → billing) and send first-contact messages outside business hours. The Sidekiq worker handles all asynchronous tasks: sending emails, triggering webhooks and push notifications.
Connect WhatsApp Business (optional)
Create a Meta for Developers app and enable the WhatsApp Business Cloud API. In Chatwoot → Settings → Inboxes → Add → WhatsApp, enter your WhatsApp Business phone number, WhatsApp Business account ID, access token and Webhook verification token. Incoming WhatsApp messages now appear in the shared inbox alongside livechat and emails.
Log in for the first time
Open the URL once installation is complete: a welcome screen prompts you to create the first account (name, email, password), which becomes the workspace owner.
Set up canned responses (Settings → Canned Responses) on day one: contact acknowledgement, order confirmation, processing times. Your agents save several minutes per conversation — and tone consistency is maintained regardless of who replies. Combine with automation rules to automatically send the first-contact reply at night and on weekends.
Official documentation
For advanced configuration (SMTP, LDAP SSO, S3 storage, multi-accounts) and Chatwoot-specific options, refer to the official Chatwoot self-hosted documentation. This guide covers deployment on VPS; the vendor documentation remains the reference for fine-tuning and major upgrades.
Migrating from Chatwoot v3 to v4
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).
v3 → v4 migration procedure
Back up the database and volumes
Before any action, save the full state:
docker compose exec postgres pg_dumpall -U postgres > /tmp/chatwoot-v3-dump-$(date +%F).sql. Also copy the Docker volumes linked to PostgreSQL and Rails Storage. This backup is your only safety net: if the migration fails, restoration is the only clean exit.Pin the image tag to v4
In your
docker-compose.yml, replacechatwoot/chatwoot:latestwithchatwoot/chatwoot:v4.0.2(or the latest v4 patch release). Avoidlatestin production: this tag tracks HEAD and can introduce regressions without warning. Check the changelog for each version on the GitHub repository before targeting a tag.Run migrations manually
Rather than letting Rails launch migrations when the web container starts, run them explicitly in the foreground to monitor progress:
docker compose run --rm web bundle exec rails db:migrate. If an error occurs, the message is immediately visible — it identifies the failing migration and lets you fix it or skip it withdb:migrate:up VERSION=...before re-running.Start and verify
Once the migrations complete without error, start the stack:
docker compose up -d. Log in to the Nova UI and verify that existing inboxes, contacts and conversations are present. Test sending and receiving a message on each connected channel. If Sidekiq shows failed jobs, use the Sidekiq Web interface (mounted at/sidekiqif enabled) to retry them.
Security fix v4.0.2: token invalidation
The Chatwoot v4.0.2 changelog includes a fix in authentication token handling: under certain conditions, a server-revoked token was still accepted by the Rails authentication middleware until the JWT's natural expiry. This affected instances where the user_access_token was not regenerated on forced logout (expired session, password change, admin revocation).
If your instance is on v3 or v4.0.0/v4.0.1, update to v4.0.2 minimum and run docker compose exec web bundle exec rails runner "UserAccessToken.where(revoked_at: ...Time.current).delete_all" to clean up expired tokens in the database. This has no impact on legitimate active sessions: only tokens whose revoked_at date is in the past are deleted.
