Chatwoot

Last reviewed Aug 26, 2026 · 798 words

Chatwoot is 5 containers, about 2 GB of RAM, and a Postgres database you will need to back up properly, in exchange for an Intercom-class shared inbox that costs nothing per agent seat. That trade is excellent for a small business paying for 3 or more support seats, and a poor one for a solo blogger who wants a chat bubble. Decide which you are before you pull the images.

Five services, one Rails app

The stack is a Ruby on Rails web process, a Sidekiq worker for background jobs (email fetching, webhooks, automation rules), Postgres with the pgvector extension, Redis, and whatever you put in front of it for TLS. The web and worker containers use the same image with different commands.

services:
  rails:
    image: chatwoot/chatwoot:latest
    env_file: .env
    command: bundle exec rails s -p 3000 -b 0.0.0.0
    ports:
      - "3000:3000"
    depends_on: [postgres, redis]
  sidekiq:
    image: chatwoot/chatwoot:latest
    env_file: .env
    command: bundle exec sidekiq -C config/sidekiq.yml
    depends_on: [postgres, redis]
  postgres:
    image: pgvector/pgvector:pg16
    volumes:
      - ./pg:/var/lib/postgresql/data
  redis:
    image: redis:alpine

Before the first start, run docker compose run --rm rails bundle exec rails db:chatwoot_prepare to create and seed the database. Skipping this is the number one cause of "the site loads but every page returns a 500".

Three env values that must be right before boot

FRONTEND_URL must be the exact public URL, https://support.example.com, because Chatwoot uses it in the widget script, email links, and OAuth callbacks. Changing it later means re-embedding the widget everywhere. SECRET_KEY_BASE must be a long random string, generated once with openssl rand -hex 64 and never rotated casually, since it signs sessions and encrypts stored credentials. POSTGRES_PASSWORD and REDIS_PASSWORD need to match what the database containers expect. Set ACTIVE_STORAGE_SERVICE=local and mount /app/storage unless you are pointing attachments at S3 or MinIO, which I would do from day one for any inbox that receives screenshots all day.

Two gigabytes is honest, four is comfortable

The web process settles around 600 to 800 MB, Sidekiq around 400 MB, Postgres and Redis a few hundred between them. That is the 2 GB in the listing and it leaves no headroom for the asset precompile that runs on some upgrades. A 4 GB VPS is the right size; 2 GB works if nothing else runs beside it. It is not a Raspberry Pi project.

Channels: the widget is easy, WhatsApp is not

The website live-chat widget takes 5 minutes: create a Website inbox, paste the generated script tag into your site, done. Email inboxes work over plain IMAP and SMTP, so any mailbox becomes a ticket queue, and Chatwoot threads replies correctly. Telegram bots and Twilio SMS are similarly quick. WhatsApp requires a Meta business account, a verified phone number, and Cloud API credentials, and Meta's approval process is the slow part, not Chatwoot. Facebook and Instagram require you to register your own Meta app, which is a real project.

Agents do not need to sit at a desk for any of this. The official iOS and Android apps connect to a self-hosted instance by entering its URL at login, so the team gets push notifications and can reply from a phone, which is the feature that makes a 2-person support rota workable at all.

Once channels exist, automation rules, canned responses, team assignment, and a reporting screen cover what most small teams used Zendesk for. What you lose is the knowledge-base polish and the marketplace of one-click integrations; the API and webhooks are there, but you wire them yourself.

Back up the database and the storage directory, together

A pg_dump of the Chatwoot database nightly plus a copy of /app/storage (or the S3 bucket) is the whole backup. They must be from the same moment or you get conversations referring to attachments that do not exist. Upgrades are docker compose pull followed by another db:chatwoot_prepare run to apply migrations; read the release notes first, as the project moves fast and occasionally changes a required env var.

What I'd do

If you are one person wanting a chat bubble and an email form, skip Chatwoot and use a contact form plus your mail client; the operational cost is not justified. For a team of 2 to 20 handling email, live chat, and maybe Telegram, run it on a 4 GB VPS with Postgres in the same compose stack, MinIO or S3 for attachments, Caddy in front, FRONTEND_URL set correctly on the first boot and never changed, and a nightly dump. It is the best self-hosted tool in the communication category for talking to customers rather than to colleagues.