SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor

How to Self-Host Chatwoot on VPS with Docker

Run Chatwoot for VPS with Docker Compose and Traefik, using pinned tags, working SMTP, Postgres and uploads backups, plus safer upgrades.

Wetin you dey build

To self-host Chatwoot for VPS, you go run four containers: one Rails web process, one Sidekiq background worker, PostgreSQL with the pgvector extension, and Redis. Chatwoot na open source customer support desk, so you go get shared team inbox and website chat widget for server wey you control. The installation dey take about twenty minutes. Everything wey follow am, like mail delivery, backups, upgrades, and sizing, na wetin go determine whether the thing still dey run after one year.

Each container get one work. Rails dey serve agent dashboard and widget API (application programming interface). Sidekiq dey run slow jobs: e dey send email, poll connected channels, run automation rules, and build reports. Postgres dey store conversations, contacts, agent accounts, and every setting wey you change for dashboard. Redis dey hold Sidekiq queues and the ActionCable pub/sub channel wey dey push new message enter open dashboard without page reload. Redis no be disposable cache for here, because if e loss, queued jobs go loss too.

The Postgres image for the upstream compose file na pgvector/pgvector:pg16 instead of the normal postgres image, because Chatwoot schema dey enable vector extension for its AI features. If you replace am with stock Postgres, the first database run go stop with ERROR: extension "vector" is not available, because that image no get the extension control file. Use the image wey upstream ships.

This guide assume say Docker and reverse proxy already dey work for the server. If dem no dey work, start with Docker Compose for VPS and come back.

How much VPS self-hosted Chatwoot need?

As of October 2026, upstream requirements page dey ask for 4 GB RAM and 4 CPU cores as minimum, and e rate am for up to 10,000 conversations per day. E put 8 GB and 8 cores for up to 20,000 per day. E also ask for at least 1 GB swap, and e explain the reason directly: so the machine no go run out of memory during upgrade. Plan for 5 GB to 10 GB disk space for Postgres before you count file uploads.

Now make we talk am plainly. 2 GB VPS go boot Chatwoot, and e fit look fine with two agents and quiet inbox. But e dey fail for two places. The first one na Sidekiq. Upstream measure am at more than 1 GB for busy server, so sudden email burst or report job fit push the machine past its memory before Rails, Postgres, and Redis take their own share. The second one na upgrade, because db:chatwoot_prepare boots fresh Rails process to apply migrations, and Rails boot for this image dey cost hundreds of megabytes before e do any useful work.

You no go first see polite warning. Kernel out of memory killer go send SIGKILL to the process wey e pick, usually the biggest one. Docker go see say the container die, and restart: always go start am again. docker compose ps --all go then show container wey dey restart continuously or dey remain for Exited (137), where 137 mean say signal 9 kill am. If you leave out --all, stopped container no go show for the list at all. Exit code 137 by itself no prove say memory cause the problem, because docker kill dey send the same signal. So confirm am with sudo dmesg -T | grep -i "killed process", wey name the process kernel pick.

If 4 GB pass your budget, you fit run 2 GB machine with 2 GB swap, but accept say response time go worse when load high. Swap na buffer against running out of memory; e no be guarantee. Large enough burst still fit make container get killed. Set hard memory limit for each service either way, so worker no go bring database down with am. See memory limits for Docker Compose.

File uploads na the part wey dey grow without any limit wey you set. Every screenshot customer attach go enter storage volume and remain there, so monitor docker system df -v instead of assuming say database na wetin fill the disk.

Get compose file and pin version tag

mkdir -p ~/chatwoot && cd ~/chatwoot
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
chmod 600 .env

The file wey you just download talk say image: chatwoot/chatwoot:latest. Change this before you do anything else.

services:
  base: &base
    image: chatwoot/chatwoot:v4.19.1
    env_file: .env
    volumes:
      - storage_data:/app/storage

latest mean say the next docker compose pull go give you anything wey dem publish that morning. This fit be major version wey get migrations you never read about. For practical purpose, Chatwoot migrations no reversible, so accidental jump mean say you go restore from backup, no be undo. Pin the tag and change am deliberately. v4.19.1 na the current release as of 25 October 2026, and the release notes recommend am for the latest security fixes and hardening improvements; check the releases page to know the tag wey you suppose pin today. If you dey move from v4.18.0 or earlier, read the v4.19.0 notes first: Captain V1 don retire, and self-hosted installations wey dey use V1 instructions must migrate dem to V2 before upgrade. Anything wey dey own database need the same caution. Na why self-host the openGym workout tracker start by pinning a git tag, even though e be much smaller application than this one.

The base service na YAML anchor wey rails and sidekiq both merge. So, if you change the tag for one place, e go change am for both. As you dey inside the file, delete the version: '3' line for the top. Modern Compose dey ignore am and print the attribute 'version' is obsolete, it will be ignored for every command.

Fill in the .env file

First generate the secret. Upstream require alphanumeric value, because special characters fit spoil when value pass through shell or YAML parser.

head /dev/urandom | tr -dc A-Za-z0-9 | head -c 63 ; echo ''

Then set these keys inside .env.

SECRET_KEY_BASE=<the 63 characters you just generated>
FRONTEND_URL=https://support.example.com
FORCE_SSL=true
DEFAULT_LOCALE=en
ENABLE_ACCOUNT_SIGNUP=true

POSTGRES_HOST=postgres
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=<long random string>
POSTGRES_DATABASE=chatwoot

REDIS_URL=redis://redis:6379
REDIS_PASSWORD=<a different long random string>

RAILS_ENV=production
INSTALLATION_ENV=docker
ACTIVE_STORAGE_SERVICE=local

POSTGRES_HOST=postgres and redis://redis:6379 na the Compose service names wey resolve for the project's default network. FRONTEND_URL no be decoration. Chatwoot dey use am build the widget script URL and every link inside outgoing email. So if the value wrong, password reset links go point to host wey no dey answer.

Now see the trap for the upstream file. The postgres service no dey read .env. E get im own environment block, and POSTGRES_PASSWORD= dey empty. So if you set password for .env alone, database go get no password while application get one. Point the service to the same variable:

  postgres:
    image: pgvector/pgvector:pg16
    restart: always
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=chatwoot
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

Compose dey read .env from the project directory for ${...} substitution. So both sides go get the same string now. If you set am wrong, Rails go stop with PG::ConnectionBad: FATAL: password authentication failed for user "postgres".

One behaviour dey surprise almost everybody: the Postgres image only applies POSTGRES_PASSWORD when e dey initialise an empty data directory. If you change the value later, e no go get effect, because initdb no dey run again. If you don start the stack before, change am inside the database instead.

docker compose exec postgres psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'the-new-password';"

ENABLE_ACCOUNT_SIGNUP=true na temporary. E opens the public registration form so you fit create the first account. Set am to false and run docker compose up -d again immediately your account don exist. Otherwise, anybody wey find the URL fit register for your support desk. From then, agents go come through invitation, and their passwords go live only inside this one app. That arrangement dey okay until you dey run about half a dozen services and you don tire to maintain separate account list for each one. For that point, a self-hosted identity provider like Authentik na the piece wey replaces dem.

.env now contain every secret wey this stack get, as plain text. So set the file mode to 600 and keep am out of git. How Compose reads env files, and where secrets leak explain the risky parts, including the difference between env_file and environment.

Put Chatwoot behind your existing Traefik

No build second reverse proxy for one application. If Traefik already dey terminate TLS (transport layer security) for other containers for this box, Chatwoot go join am with one label block. If you never set am up, set am up once with Traefik for front of several Docker Compose apps, then come back here.

Keep upstream's docker-compose.yaml close to the original so you fit compare am with newer copy later, and put your changes for override file. Compose dey merge docker-compose.override.yaml automatically, and how to split Compose across multiple files dey explain the merge rules.

services:
  rails:
    networks:
      - default
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.chatwoot.rule=Host(`support.example.com`)"
      - "traefik.http.routers.chatwoot.entrypoints=websecure"
      - "traefik.http.routers.chatwoot.tls.certresolver=letsencrypt"
      - "traefik.http.services.chatwoot.loadbalancer.server.port=3000"

networks:
  proxy:
    external: true

Use your own entrypoint and certresolver names. The container must dey for the same Docker network with Traefik. Na the proxy entry dey do this, and e must still dey for default too, or e go lose Postgres and Redis. Na this second line many people dey forget.

Leave the ports: block as e be. Upstream binds am to 127.0.0.1:3000, and na only loopback fit reach am. So internet no fit reach am, and e still useful for testing from inside the box with curl -I http://127.0.0.1:3000.

The agent dashboard dey keep websocket open to /cable so e fit receive new messages live. Traefik forwards the HTTP upgrade without extra configuration, so you no need add anything. If you later put CDN or another proxy for front of Traefik, allow websockets there. The symptom na dashboard wey load normally, but new messages only show after manual refresh.

Database initialise and the stack start

Bring the data services up first, then allow Postgres finish the first run.

docker compose up -d postgres redis
docker compose logs postgres | tail -n 5

Wait for database system is ready to accept connections. Then create the schema.

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

This one go create the database if e no dey, then load the schema and the default seed data. E go print migration lines and exit cleanly. If e dey print postgres:5432 - no response without stopping, the entrypoint dey wait for database wey never ready to accept connections. For first run, this usually mean say initdb still dey work. Wait, read the Postgres logs, then run am again. If e stop for the vector extension, you don replace the pgvector image with stock Postgres.

docker compose up -d
docker compose ps
docker compose logs --tail 30 rails

All four containers suppose show Up, and the rails log suppose end with a Puma line wey dey listen on http://0.0.0.0:3000. Then check the public path:

curl -sI https://support.example.com | head -n 1

HTTP/2 200 mean say the whole chain dey work. If Traefik return 404, the router rule no match. Hostname typo na the usual cause. If e return 502, Traefik match the router but e no fit reach the container. This almost always mean say the proxy network dey missing, or loadbalancer.server.port no be 3000.

Open the URL, create your account for /app/auth/signup, then set ENABLE_ACCOUNT_SIGNUP=false and run docker compose up -d to close the form.

Wetin make password reset and email conversation fail without SMTP

Chatwoot wey no get SMTP (simple mail transfer protocol) settings na support desk wey no fit send mail, and this one spoil pass notification. Password reset go stop to work, so admin wey lock out no go fit enter again. Agent invitation go stop to work too, because invitation na email. Replying customer for email conversation go stop, so the conversation go only work one way. Na this step people dey skip, then dem go discover am for their worst week.

The way e work clear. If SMTP_ADDRESS no set, Chatwoot go switch ActionMailer to sendmail delivery. Upstream document this as Postfix setup, wey be the default since v2.12.0, and the instruction for am install Postfix for the server with sudo apt install -y postfix. This Docker setup no do that, so no configured mail server dey for that delivery to hand your mail over to. Background job dey send the mail, so any error wey delivery produce go enter Sidekiq log and no go enter Rails log. Meanwhile, person wey click "forgot password" go see cheerful confirmation but no mail go reach am.

MAILER_SENDER_EMAIL=Support <support@example.com>
SMTP_DOMAIN=example.com
SMTP_ADDRESS=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=support@example.com
SMTP_PASSWORD=<the relay password>
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true

Use port 587 with STARTTLS. E go open the connection as plain text, then upgrade am to encrypted before authentication. Many VPS providers dey block outbound port 25 by default to reduce spam. As of 8 November 2026, Hetzner dey block ports 25 and 465 by default for cloud servers, and the block dey apply per account. Vultr dey block port 25 for all new Compute Instances. Both providers dey review unblock requests case by case. Hetzner require make customer don dey with dem for one month and make first invoice don pay before you fit submit limit request. Neither provider block 587, so relay for 587 go work from the first boot without ticket or waiting. SMTP_DOMAIN na the domain wey your server announce during SMTP conversation, and some relays go reject am if e no match.

Apply the settings and monitor the worker:

docker compose up -d rails sidekiq
docker compose logs -f sidekiq

Trigger password reset from the login page. If delivery work, mailer job go finish normally for Sidekiq log. If e fail, log go show the exception class, then Sidekiq go retry with longer backoff each time. Na why broken relay fit produce the same error every few minutes for hours.

Two rejection types dey common, and neither one na Chatwoot bug. 535 Authentication failed mean authentication fail, so check the credentials, whether SMTP authentication dey enabled, and whether access policy dey block am. Correct credentials alone no rule out this error. Some providers require application password instead of account password. 550 Sender address rejected mean server reject the sender address. Read the full response before you change MAILER_SENDER_EMAIL. Sender permissions or verification fit cause am, but 550 5.7.27 Sender address rejected: Domain does not accept mail point to sender domain wey get null MX record.

Receiving email inside conversation na separate job. For forwarding through Chatwoot's ingress, e need MAILER_INBOUND_EMAIL_DOMAIN and RAILS_INBOUND_EMAIL_SERVICE, plus mail server wey hand incoming messages to Chatwoot. You fit also connect mailbox through IMAP, including Google or Microsoft OAuth, without setting up that forwarding path. Renting relay na the fast option. If you prefer to control the whole mail path yourself, running your own mail server with Mailcow explain wetin that commitment really involve.

Wetin to back up, and how to prove say restore dey work

Chatwoot backup get four parts, and if you skip any one, restore go turn rebuild.

  • The Postgres database, wey dey hold conversations, contacts, agent accounts and every setting.
  • The storage_data volume, because ACTIVE_STORAGE_SERVICE=local dey write uploaded files to disk and keep only reference row for Postgres.
  • The .env file, because e dey hold SECRET_KEY_BASE and the ACTIVE_RECORD_ENCRYPTION_* keys.
  • The compose files, because dem dey record the exact image tag wey your database schema match.

If you restore the database alone, every conversation go come back with broken attachments, because the rows dey point to files wey no dey disk again.

cd ~/chatwoot
docker compose exec -T postgres pg_dump -U postgres -Fc chatwoot > db-$(date +%F).dump

-T matter. Without am, Compose go allocate pseudo terminal, wey go rewrite newline bytes for the stream. So you go get dump file wey pg_restore no fit accept. -Fc na the custom format. E dey compress the data and allow pg_restore work selectively.

docker run --rm -v chatwoot_storage_data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/storage-$(date +%F).tgz -C /data .

The volume name na your project directory name plus _storage_data. Confirm am with docker volume ls | grep storage_data before you trust that command, because Docker go create empty volume instead of failing when you name one wey no exist. You go get valid, empty archive and no error at all. Check the size afterwards with ls -lh storage-*.tgz.

Both files now dey the same disk with the thing wey dem suppose protect, so dem no protect you from anything. Push dem outside the server and encrypt dem, because database dump dey contain every customer message as plain text. Encrypted off-site backups with restic dey explain the scheduling and retention side.

The restore drill, run am before you need am

Restore am onto second VPS, no be the live one. Copy .env, the compose files and both archives go there, then run:

docker compose up -d postgres
docker compose exec -T postgres pg_restore -U postgres -d chatwoot --clean --if-exists < db-2026-08-10.dump
docker run --rm -v chatwoot_storage_data:/data -v "$PWD":/backup alpine \
  sh -c 'rm -rf /data/* && tar xzf /backup/storage-2026-08-10.tgz -C /data'
docker compose up -d

--clean --if-exists go drop the existing objects before e load the data, so point am only to database wey you ready to lose. Then sign in and open conversation wey get attachment. If message list load and the file download, the backup dey real.

Restore with different SECRET_KEY_BASE go invalidate every session cookie, so everybody go sign out. Restore with different ACTIVE_RECORD_ENCRYPTION_* keys worse pass: Chatwoot no fit decrypt the columns wey hold channel credentials and e go raise ActiveRecord::Encryption::Errors::Decryption. Na why .env dey the backup list.

How to upgrade Chatwoot to a new tag

The order matter pass the commands.

  1. Read the release notes between your tag and the target, and check for manual steps wey you must do.
  2. Take fresh database dump and storage archive, then check say both file sizes make sense.
  3. Edit the image tag for the base service inside docker-compose.yaml.
  4. Pull the new image, stop the stack, run migrations, then start am again.
docker compose pull
docker compose down
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
docker compose up -d
docker compose images

Pull before you migrate, because migration must run from the new image: the old image no get the new migration files. Stop the stack before you migrate, because the old code and new schema no match, so old Rails process wey still dey run fit raise errors or write rows wey the new schema no go accept. Stopping also free the memory wey migration need. Na this be the reason upstream ask for swap.

docker compose images dey print the tag wey each container dey actually run. This one go catch the case where you edit the tag but forget to pull.

How far you fit jump depend on how old the install be. If the install dey one or two releases behind, review the release notes between your tag and the target, set the target tag, and run the steps above once. Na only when your installation very old upstream Docker guide tell you to upgrade step by step through intermediate image tags instead of jumping straight to the latest image. For that case, repeat the tag change, pull, and prepare step for each intermediate tag, because upstream ask for db:chatwoot_prepare after each upgrade.

If Rails start before migration run, e refuse to serve and log ActiveRecord::PendingMigrationError: Migrations are pending. When restart: always dey set, the container go keep cycling, so docker compose ps go show uptime wey reset every few seconds. Run the prepare step and e go clear.

To roll back, put the old tag back and restore the dump. No reverse migration path dey wey you fit rely on. Na this be the reason for step 2.

Failure modes and the strings you go see

502 Bad Gateway from Traefik. Router match, but backend no answer. Check docker compose ps show rails as Up, then run docker network inspect proxy and confirm say rails container dey appear for the container list. Container wey no attach no dey visible to Traefik, so request match router but e no go anywhere.

Dashboard loads but new messages need refresh. Websocket go /cable no dey pass, or FRONTEND_URL no match the address wey dey browser bar. If dem no match, page go try open websocket to another origin, and browser go block am.

FATAL: password authentication failed for user "postgres". Password for .env and the one wey dey inside Postgres data volume no be the same. Fix am with ALTER USER inside the running container, because editing .env again no go change database wey don already initialise.

NOAUTH Authentication required. Redis dey run with --requirepass, but application connect without password, so REDIS_PASSWORD dey miss from .env or application no pick am. Test the password wey Redis expect directly with docker compose exec redis sh -c 'redis-cli -a "$REDIS_PASSWORD" ping'. E suppose answer PONG. The single quotes matter: dem make the variable expand inside the container, where e go read .env, instead of for your own shell, where e dey usually empty.

Containers dey exit with code 137. Na SIGKILL be that. For small box, kernel's out of memory killer na the usual sender, but docker kill fit send the same signal too, so check sudo dmesg -T | grep -i "killed process" before you blame memory. If na memory problem, add swap, set memory limits for each service, or move go bigger plan.

FAQ

How many RAM self-hosted Chatwoot VPS need?

As of October 2026, upstream dey ask for 4 GB RAM and 4 CPU cores as minimum, rated for up to 10,000 conversations per day. E dey ask for 8 GB and 8 cores for up to 20,000. Add at least 1 GB swap, because upgrade go run second Rails process to apply migrations, and na there small servers dey run out of memory. 2 GB VPS fit boot and work for few agents, but Sidekiq alone fit pass 1 GB under load. So expect containers to get killed with exit code 137 during busy periods and upgrades.

Why Chatwoot password reset emails no dey arrive?

Because no SMTP_ADDRESS dey set, so Chatwoot falls back to sendmail delivery. Upstream intend this for Postfix server wey dey installed on the host, but this Docker setup no get one. The job dey run inside Sidekiq, so any delivery error go enter Sidekiq log while browser still dey show success message. Set SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD and MAILER_SENDER_EMAIL inside .env. Restart the rails and sidekiq services, then monitor docker compose logs -f sidekiq while you trigger reset.

Wetin I need back up to restore Chatwoot?

The Postgres database, the storage_data Docker volume, the .env file, and the compose files. Database alone no enough, because uploaded files dey inside the volume while Postgres only dey keep references to dem. So database-only restore go give you conversations with broken attachments. .env matter because different SECRET_KEY_BASE go sign every user out. Different ACTIVE_RECORD_ENCRYPTION_* keys go make the encrypted columns unreadable.

How I fit upgrade Chatwoot without breaking the database?

Take backup, read the release notes between your tag and the target, change the image tag inside your compose file, then run docker compose pull, docker compose down, docker compose run --rm rails bundle exec rails db:chatwoot_prepare and docker compose up -d. Pull first because migrations must run from the new image. Stop the stack first because old code against new schema go raise errors. Only very old installation need to pass through intermediate image tags instead of jumping straight to the latest. Run the prepare step after each one.

I fit use the standard postgres image instead of pgvector?

No. Chatwoot schema dey enable the vector extension, so the stock postgres image go fail during db:chatwoot_prepare with ERROR: extension "vector" is not available because the extension control file no dey inside that image. Keep pgvector/pgvector:pg16 from the upstream compose file, or use another image wey ships pgvector for your Postgres major version.

Dis article help you?

#chatwoot#self-hosting#docker-compose#support-desk#smtp#backups