VPS Tutorials
Self-host Chatwoot on a VPS (2026): Docker, HTTPS, email and recovery
Deploy Chatwoot Community Edition on Ubuntu with Docker, PostgreSQL, Redis and Caddy. Configure website chat, SMTP, attachments, secure backups, recovery drills and controlled upgrades.

Running customer support on a VPS involves more than bringing up a login page. The website widget, notifications, background jobs, attachments, HTTPS and recovery need to work together reliably. Chatwoot uses Rails, Sidekiq, PostgreSQL and Redis; an outdated installation command can leave you with an unpinned image, exposed database or unusable backup.
This complete guide uses Ubuntu 24.04, Chatwoot Community Edition v4.17.1, the official Docker Compose configuration and Caddy. It builds a support platform for a small or medium team, including an HTTPS dashboard, website chat, SMTP notifications, optional S3-compatible storage, offsite backups, recovery drills and controlled upgrades.
Version context: the source's September 8, 2026 example identified v4.17.1 as the stable release. This guide pins
chatwoot/chatwoot:v4.17.1-cerather thanlatest. That historical example is not a claim about the latest release today. Check Chatwoot Releases and the official Docker Hub tags when deploying, and select a supported stable version with relevant security fixes.
Chatwoot brings website chat, email and social messages connected through official integrations into one support workspace. It serves a similar purpose to Intercom or Zendesk; it is designed for customer support rather than internal team chat.
Self-hosting makes sense when:
- Customer conversations and contacts must stay on infrastructure you control.
- Several agents need conversation assignment, labels, private notes and saved replies.
- Website chat, email, webhooks or APIs need a shared inbox.
- Someone can maintain Linux, Docker, email delivery, backups and security updates.
- SaaS seat charges substantially exceed the combined infrastructure and operations cost.
A hosted support service is often easier for a personal site or a team without a person responsible for monitoring and recovery. Community Edition is free, but the VPS, domain, email provider, object storage, offsite backups and maintenance time still cost money.
| Option | Suitable needs | Advantages | Costs and responsibilities |
|---|---|---|---|
| Self-hosted Chatwoot | Data control, several agents, API integrations | Own infrastructure, unified channels, customization | VPS, mail, backups, upgrades and incidents |
| Intercom / Zendesk | Managed service and vendor support | Established features, managed infrastructure | Plan or seat fees; SaaS data terms |
| Simple chat plugin | Small site, one operator, website chat only | Quick setup, little maintenance | Limited channels, automation and collaboration |
Community Edition does not include every commercial feature. The current official comparison excludes Captain AI, voice calls, custom branding, agent capacity, advanced roles and permissions, SSO/SAML, SLA policies and priority support from CE. Check the self-hosted plans against your requirements; do not budget for paid features as part of the free edition.
For internal channels, private team messages and ChatOps, see the Mattermost self-hosting guide.
The official requirements specify at least 4 GB RAM. Their reference sizing associates 4 cores/4 GB with about 10,000 conversations per day and 8 cores/8 GB with about 20,000. These are vendor capacity references, not a measured guarantee for your workload. Agent concurrency, channels, attachments, webhooks and jobs all affect resource use; a busy Sidekiq process can consume over 1 GB by itself.
| Workload | Suggested starting resources | Storage | Notes |
|---|---|---|---|
| Trial or low volume | 2–4 vCPU, 4 GB RAM | 50 GB NVMe | Few agents and website chat; watch memory closely |
| Small or medium production team | 4 vCPU, 8 GB RAM | 80–160 GB NVMe | Headroom for Rails, Sidekiq, PostgreSQL and files |
| High volume or many channels | 8 vCPU, 16 GB+ RAM | Plan database and object storage separately | Split web, workers and database, then load-test |
The official guide also recommends at least 1 GB swap to absorb transient memory pressure during upgrades. Swap is a buffer; persistent swapping calls for more RAM or separated services. Check whether the host already has a swap file before using this example, and avoid adding duplicate fstab entries:
sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h
The source diagram shows HTTPS clients reaching host-level Caddy, which forwards to Rails on loopback port 3000. Rails and Sidekiq use PostgreSQL and Redis; attachments live in a Docker volume or S3-compatible storage:
访客网站 / 客服浏览器
│ HTTPS 443
▼
Caddy(宿主机)
│ 127.0.0.1:3000
▼
Chatwoot Rails 容器 ───── PostgreSQL
│
└──── Sidekiq ─── Redis
附件:本地 Docker volume,或 S3 兼容对象存储
Only 22/tcp, 80/tcp and 443/tcp need public access. The pinned production Compose file binds Rails 3000, PostgreSQL 5432 and Redis 6379 to 127.0.0.1. Keep those bindings; changing the database or Redis to 0.0.0.0 is not a troubleshooting step.
Choose a subdomain such as support.example.com and point its A record to the VPS IPv4 address. Add an AAAA record only if working IPv6 reaches the server; a broken IPv6 route can cause intermittent certificate or client failures.
export CW_DOMAIN="support.example.com"
getent ahosts "$CW_DOMAIN"
curl -4 https://ifconfig.me
Update Ubuntu and configure UFW:
sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y ca-certificates curl openssl ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose
Apply the same rules to any provider security group. Restrict SSH to administration addresses where practical, and verify login from another terminal before closing the current connection. Check Docker's published bindings separately; firewall rules alone do not establish container-port privacy.
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker version
sudo docker compose version
Plan log rotation, resource alerts and observability as part of production operation. See the Docker Compose production checklist.
Download files from the v4.17.1 tag, so later changes on develop do not silently change the deployment:
sudo install -d -o "$USER" -g "$USER" -m 0750 /opt/chatwoot
cd /opt/chatwoot
curl -fL https://raw.githubusercontent.com/chatwoot/chatwoot/v4.17.1/.env.example -o .env
curl -fL https://raw.githubusercontent.com/chatwoot/chatwoot/v4.17.1/docker-compose.production.yaml -o docker-compose.production.yaml
sed -i 's|image: chatwoot/chatwoot:latest|image: chatwoot/chatwoot:v4.17.1-ce|' docker-compose.production.yaml
grep 'image: chatwoot/chatwoot' docker-compose.production.yaml
The -ce image omits Enterprise code. Pinning makes each upgrade deliberate; it does not mean keeping an old version indefinitely. Also review the PostgreSQL/pgvector and Redis image tags, extensions and compatibility. Avoid casually changing their major versions with an application upgrade.
Generate three different secrets and save them in a password manager:
openssl rand -hex 64
openssl rand -base64 36
openssl rand -base64 36
The first value is for SECRET_KEY_BASE, with separate database and Redis passwords. Base64 can contain URL-sensitive characters. For a Redis password embedded in a URL, either encode the password correctly or generate a hexadecimal password, for example openssl rand -hex 32; use that exact same password in both Redis settings.
Edit /opt/chatwoot/.env and replace every placeholder domain, password and sender:
SECRET_KEY_BASE=replace-with-the-128-character-hex-secret
FRONTEND_URL=https://support.example.com
FORCE_SSL=true
ENABLE_ACCOUNT_SIGNUP=true
DEFAULT_LOCALE=zh_CN
REDIS_URL=redis://:replace-with-redis-password@redis:6379
REDIS_PASSWORD=replace-with-redis-password
POSTGRES_HOST=postgres
POSTGRES_DATABASE=chatwoot
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=replace-with-postgres-password
RAILS_ENV=production
RAILS_LOG_TO_STDOUT=true
LOG_LEVEL=info
MAILER_SENDER_EMAIL=Support <[email protected]>
SMTP_DOMAIN=example.com
SMTP_ADDRESS=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=replace-with-smtp-password
SMTP_AUTHENTICATION=login
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_OPENSSL_VERIFY_MODE=peer
ACTIVE_STORAGE_SERVICE=local
The preserved source example sets DEFAULT_LOCALE=zh_CN. For an English organization, use DEFAULT_LOCALE=en; it controls the initial language of newly created accounts. It does not establish where customers live.
Fix the database password before initialization. The pinned official Compose file contains a blank POSTGRES_PASSWORD= entry under the postgres service. A password in the application dotenv file does not replace that literal blank. Replace that entry in the existing postgres environment list with:
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
Keep POSTGRES_DB and POSTGRES_USER aligned with the application's database and user. Setting a new password variable after PostgreSQL has initialized does not change an existing database role password; handle existing installations through a controlled database password change.
The source shows this permission/configuration check:
cd /opt/chatwoot
chmod 600 .env
sudo docker compose -f docker-compose.production.yaml config >/tmp/chatwoot-compose.yaml
grep -A4 -E '127.0.0.1:3000|127.0.0.1:5432|127.0.0.1:6379' /tmp/chatwoot-compose.yaml
Do not write expanded secrets to a broadly readable temporary file. Prefer the following pipe, which prints only port bindings. Modern Compose renders structured port fields, so the source's literal-string grep may print nothing even when bindings are correct:
sudo docker compose -f /opt/chatwoot/docker-compose.production.yaml config --format json | python3 -c '
import json, sys
config = json.load(sys.stdin)
for name in ("rails", "postgres", "redis"):
for port in config["services"][name].get("ports", []):
assert port.get("host_ip") == "127.0.0.1", (name, "non-loopback binding")
print(name, port.get("host_ip"), port.get("published"), port.get("target"))
'
Keep the dotenv file at mode 600. Never post the full docker compose config output in a public issue: it can contain PostgreSQL, Redis and SMTP credentials.
Run the official preparation task before the first application start:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml pull
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker compose -f docker-compose.production.yaml up -d
sudo docker compose -f docker-compose.production.yaml ps
sudo docker compose -f docker-compose.production.yaml logs --tail=100 rails sidekiq postgres redis
Check the web port and dependencies:
curl -I http://127.0.0.1:3000
ss -lntp | grep -E ':3000|:5432|:6379'
sudo docker compose -f docker-compose.production.yaml exec -T postgres pg_isready -U postgres -d chatwoot
sudo docker compose -f docker-compose.production.yaml exec -T redis sh -lc 'redis-cli -a "$REDIS_PASSWORD" ping'
PostgreSQL should report accepting connections, Redis PONG, and the three published ports should use loopback. A health response alone does not prove that the application credentials work; inspect Rails/Sidekiq logs and send a test conversation too.
sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list >/dev/null
sudo apt-get update
sudo apt-get install -y caddy
Create /etc/caddy/Caddyfile with your real domain:
support.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000
log {
output file /var/log/caddy/chatwoot-access.log {
roll_size 100MiB
roll_keep 7
}
}
}
Create the access-log directory with ownership that lets the Caddy service write to it. Caddy's reverse_proxy supports WebSockets by default; you do not need to manually set the Upgrade header. Validate and reload:
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
curl -I https://support.example.com
For a host serving several applications, consult the Caddy reverse-proxy and automatic HTTPS guide.
Initially visit:
https://support.example.com/app/auth/signup
Restrict initial access to the intended administrator until bootstrap is complete. After creating the first administrator and organization, change .env to:
ENABLE_ACCOUNT_SIGNUP=false
Recreate the application containers so the updated environment takes effect:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml up -d --force-recreate rails sidekiq
Invite further agents from the administrator account rather than leaving public signup enabled. Enable MFA where supported. Before enabling it, configure the three Active Record Encryption keys described in .env.example:
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:encryption:init
Securely save ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY, ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY and ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT from the command output into .env and a password manager. Recreate Rails and Sidekiq. Preserve these keys across deployments and restores; regenerating or losing them can make existing encrypted data unreadable.
Open Settings → Inboxes → Add Inbox, choose Website, and enter the site name and allowed domains. Add the generated script containing websiteToken to the site's shared layout or tag manager.
Before going live, verify:
- The chat bubble appears in a private browser window.
- The first visitor message appears immediately in the agent workspace.
- Agent replies reach the page without requiring a refresh.
- An unapproved test domain cannot misuse the widget; confirm what the selected version's domain controls actually enforce.
- Attachment size and type rules match the business requirements.
- Email notifications continue after closing the agent dashboard.
If the widget is absent, inspect the browser Console, Network and WebSocket requests. Common causes include an incorrect FRONTEND_URL, a CSP blocking scripts, old CDN-cached code or a redirect error before the proxy.
SMTP supports invitations, notifications, password resets and conversation email. Send a dashboard test and inspect logs:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml logs -f --tail=100 rails sidekiq
For spam-folder problems, check the sender domain's SPF, DKIM and DMARC rather than disabling TLS validation. The domain in MAILER_SENDER_EMAIL must match an identity authorized by the email provider. With a relay, the provider operates the sending server's reverse DNS.
Customer replies continuing the same conversation require inbound email configuration as well. Set up a supported Mailgun, Postmark, SendGrid, SES or relay integration, with RAILS_INBOUND_EMAIL_SERVICE, the inbound password and relevant webhook. Verify support for the chosen version/provider: successful outbound SMTP does not prove inbound email is configured.
Unified inboxes do not bypass platform requirements. WhatsApp, Instagram and Facebook integrations generally require the appropriate Business account, developer application, webhooks, review and platform charges.
For production:
- Obtain credentials using Chatwoot and platform documentation.
- Use a dedicated application and tokens with minimum permissions.
- Keep callback domains on HTTPS.
- Assign owners for token rotation and platform review.
- Avoid unverified shared accounts and services promising to bypass review.
Validate website chat and an API Inbox first, then add external channels one at a time.
With ACTIVE_STORAGE_SERVICE=local, attachments are stored in the storage_data Docker volume. This is simple, but loss of the host disk also loses the files unless you have offsite backups.
For growing attachment collections, configure S3-compatible storage:
ACTIVE_STORAGE_SERVICE=s3_compatible
STORAGE_BUCKET_NAME=chatwoot-attachments
STORAGE_ACCESS_KEY_ID=replace-with-access-key
STORAGE_SECRET_ACCESS_KEY=replace-with-secret-key
STORAGE_REGION=auto
STORAGE_ENDPOINT=https://your-s3-compatible-endpoint
STORAGE_FORCE_PATH_STYLE=true
Providers differ in path-style addressing, CORS and signed-URL behavior. Test uploads, previews, downloads and deletion before switching, and migrate existing files deliberately; changing the environment variable does not move them. Recreate applications after changing storage configuration. Enable suitable versioning, lifecycle rules and backups on object storage too. S3 alone does not meet a recovery target. See the MinIO tutorial for self-managed compatible storage.
The official backup scope includes PostgreSQL, attachments, environment variables and code customizations. Redis stores queues and cache; it is not the sole source of conversations. The database and attachment collection need a coordinated recovery point, and pending jobs require explicit treatment.
The source's stop-and-copy illustration is preserved below. Use the reviewed version after it for the default local-volume topology; the original lacks reliable restart handling, exact volume discovery and a portable checksum manifest:
cd /opt/chatwoot
STAMP=$(date +%F-%H%M%S)
BACKUP_DIR="/var/backups/chatwoot/$STAMP"
sudo install -d -m 0700 "$BACKUP_DIR"
sudo docker compose -f docker-compose.production.yaml stop rails sidekiq
sudo sh -c "docker compose -f /opt/chatwoot/docker-compose.production.yaml exec -T postgres pg_dump -U postgres -d chatwoot -Fc > '$BACKUP_DIR/chatwoot.dump'"
sudo docker compose -f docker-compose.production.yaml run --rm --no-deps \
-v "$BACKUP_DIR:/backup" rails \
tar -czf /backup/storage.tar.gz -C /app/storage .
sudo cp .env docker-compose.production.yaml "$BACKUP_DIR/"
sudo sha256sum "$BACKUP_DIR"/* | sudo tee "$BACKUP_DIR/SHA256SUMS"
sudo docker compose -f docker-compose.production.yaml start rails sidekiq
Pause message producers or enter a maintenance window, and let Sidekiq queues drain where possible before stopping applications. Pre-pull the archive utility image before maintenance. This root-run example resolves the volumes actually mounted by the running Rails and Redis containers, checks their existence, keeps private permissions, saves Redis queues, records the application image and restarts services through an EXIT trap:
sudo bash <<'BACKUP'
set -Eeuo pipefail
umask 077
cd /opt/chatwoot
compose=(docker compose -f docker-compose.production.yaml)
rails_id=$("${compose[@]}" ps -q rails)
redis_id=$("${compose[@]}" ps -q redis)
test -n "$rails_id" && test -n "$redis_id"
storage_volume=$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/app/storage"}}{{if eq .Type "volume"}}{{.Name}}{{end}}{{end}}{{end}}' "$rails_id")
redis_volume=$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{if eq .Type "volume"}}{{.Name}}{{end}}{{end}}{{end}}' "$redis_id")
test -n "$storage_volume" && test -n "$redis_volume"
docker volume inspect "$storage_volume" "$redis_volume" >/dev/null
backup_dir="/var/backups/chatwoot/$(date -u +%Y%m%dT%H%M%SZ)"
install -d -m 0700 "$backup_dir"
resume_apps() { "${compose[@]}" start rails sidekiq >/dev/null || true; }
trap resume_apps EXIT
"${compose[@]}" stop rails sidekiq
"${compose[@]}" exec -T postgres pg_dump -U postgres -d chatwoot -Fc > "$backup_dir/chatwoot.dump"
"${compose[@]}" exec -T redis sh -ec 'REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli SAVE'
"${compose[@]}" stop redis
resume_services() { "${compose[@]}" start redis rails sidekiq >/dev/null || true; }
trap resume_services EXIT
docker run --rm --network none -v "$storage_volume:/source:ro" -v "$backup_dir:/backup" alpine:3.22 tar -czf /backup/storage.tar.gz -C /source .
docker run --rm --network none -v "$redis_volume:/source:ro" -v "$backup_dir:/backup" alpine:3.22 tar -czf /backup/redis.tar.gz -C /source .
cp -p .env docker-compose.production.yaml "$backup_dir/"
cp -p /etc/caddy/Caddyfile "$backup_dir/Caddyfile"
docker inspect --format '{{.Config.Image}} {{.Image}}' "$rails_id" > "$backup_dir/image-reference.txt"
(cd "$backup_dir" && sha256sum chatwoot.dump storage.tar.gz redis.tar.gz .env docker-compose.production.yaml Caddyfile image-reference.txt > SHA256SUMS && sha256sum -c SHA256SUMS)
printf 'Backup directory: %s\n' "$backup_dir"
BACKUP
It assumes local attachments, the shown database name and no concurrent producer writing to Redis or attachments. For S3, take a corresponding object-storage recovery point instead of treating the local archive as the authoritative files. Include custom code, additional configuration and any non-default mounts in the backup. Verify service recovery after any failure; the trap attempts restart but is not a health check.
Encrypt the complete backup and copy it to another region or provider. A second directory on the same VPS disk is not disaster recovery. Design retention around RPO, for example 7 daily copies, 4 weekly copies and 6–12 monthly copies. See the VPS backup strategy.
Use an isolated test VPS, block outbound channel webhooks and email, and restore the matching image, database, storage mode and encryption keys from .env. Verify SHA256SUMS from inside the backup directory before restoring.
The source's basic sequence is:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml stop rails sidekiq
sudo docker compose -f docker-compose.production.yaml exec -T postgres dropdb -U postgres --if-exists chatwoot
sudo docker compose -f docker-compose.production.yaml exec -T postgres createdb -U postgres chatwoot
sudo sh -c "cat /var/backups/chatwoot/RESTORE_POINT/chatwoot.dump | docker compose -f /opt/chatwoot/docker-compose.production.yaml exec -T postgres pg_restore -U postgres -d chatwoot"
sudo docker compose -f docker-compose.production.yaml run --rm --no-deps \
-v /var/backups/chatwoot/RESTORE_POINT:/backup:ro rails \
tar -xzf /backup/storage.tar.gz -C /app/storage
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker compose -f docker-compose.production.yaml start rails sidekiq
The database deletion in that sequence is permitted only on the empty, disposable recovery destination. Start PostgreSQL/Redis dependencies first, keep Rails and Sidekiq stopped, and use a privileged archive helper mounted to the destination's verified existing storage volume if the application user cannot write to the backup mount or restore files. Do not guess volume names or restore into the live source. Ensure restored ownership matches the image user. Restore Redis into a stopped destination Redis volume when preserving queued jobs; otherwise explicitly accept queue loss and reconcile missed or duplicate deliveries. Keep the destination isolated before starting workers to prevent replaying real notifications.
Then run preparation with the matching application image and start applications. Test administrator login, historical conversations, contacts, random attachments, website chat, notifications and background jobs in a controlled environment. A backup file proves that data was exported; a recovery drill proves it can support service restoration.
Read all release notes between the installed and target versions. Follow required intermediate upgrades rather than skipping several major versions at once.
The source example below starts applications before preparing the database. Its v4.17.2-ce tag is illustrative, not a recommendation that the tag exists or is suitable:
cd /opt/chatwoot
# 1. 先执行上一节的完整备份并记录当前镜像
grep 'image: chatwoot/chatwoot' docker-compose.production.yaml
# 2. 把 Compose 中的镜像改成已经核对过的新版本,例如 v4.17.2-ce
sudo docker compose -f docker-compose.production.yaml down
sudo docker compose -f docker-compose.production.yaml pull
sudo docker compose -f docker-compose.production.yaml up -d
# 3. 官方要求升级后运行数据库准备任务
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
# 4. 回读状态与日志
sudo docker compose -f docker-compose.production.yaml ps
sudo docker compose -f docker-compose.production.yaml logs --tail=200 rails sidekiq
curl -I https://support.example.com
Use this order instead, after a complete verified backup and selecting the actual target image:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml stop rails sidekiq
# Edit the shared base image to the reviewed target tag before pulling.
sudo docker compose -f docker-compose.production.yaml pull
sudo docker compose -f docker-compose.production.yaml up -d postgres redis
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker compose -f docker-compose.production.yaml up -d --force-recreate rails sidekiq
sudo docker compose -f docker-compose.production.yaml ps
sudo docker compose -f docker-compose.production.yaml logs --tail=200 rails sidekiq
curl -I https://support.example.com
Prepare the database while applications remain stopped, then recreate Rails and Sidekiq. After schema migrations, switching to the old image alone is not a reliable rollback. Restore the pre-upgrade database/files recovery point with matching keys and image, and test it in isolation first.
Monitor at least:
- Host memory, swap, CPU, free disk and inodes.
- Rails and Sidekiq restart counts.
- PostgreSQL connections, size and backup results.
- Redis availability and memory.
- Sidekiq queue backlog and failed jobs.
- HTTPS certificates, DNS and external availability.
- SMTP bounces, webhook failures and attachment growth.
Quick inspection commands:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml ps
sudo docker stats --no-stream
df -h
df -i
free -h
sudo docker compose -f docker-compose.production.yaml logs --since=30m rails sidekiq postgres redis
Website availability alone is insufficient. With Sidekiq down, the login page can work while email, webhooks, imports and jobs accumulate.
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml ps
sudo docker compose -f docker-compose.production.yaml logs --tail=200 rails sidekiq
sudo docker inspect --format '{{.State.OOMKilled}} {{.RestartCount}}' chatwoot-rails-1
Check SECRET_KEY_BASE, database connectivity, Redis credentials and OOM. Container names depend on the Compose project; obtain the real name with docker compose ps before inspecting it.
sudo docker compose -f docker-compose.production.yaml exec -T postgres pg_isready -U postgres -d chatwoot
sudo docker compose -f docker-compose.production.yaml exec -T redis sh -lc 'redis-cli -a "$REDIS_PASSWORD" ping'
Keep POSTGRES_DATABASE=chatwoot aligned with POSTGRES_DB=chatwoot, and the password in REDIS_URL consistent with REDIS_PASSWORD. Apply the blank-password correction above. Opening ports 5432 or 6379 to the Internet cannot repair internal authentication.
Test the origin without the CDN, then inspect browser WebSockets and Caddy/Rails logs. Caddy already supports WebSockets; a preceding CDN/WAF must allow long connections and avoid caching API or WebSocket routes.
sudo docker compose -f docker-compose.production.yaml logs --since=30m rails sidekiq | grep -Ei 'smtp|mail|timeout|auth|tls'
Check port, authentication, sender authorization, TLS and provider IP restrictions. VPS providers often restrict port 25. Use the mail provider's supported 587 STARTTLS or 465 TLS configuration according to its documentation.
df -h
df -i
sudo docker compose -f docker-compose.production.yaml run --rm --no-deps rails sh -lc 'df -h /app/storage && ls -ld /app/storage'
For local files, inspect disk, inodes and volume permissions. For S3-compatible storage, check endpoint, bucket, region, path-style access, CORS and signature timing. Host clock drift can immediately invalidate signed URLs.
Check the selected image and completed database preparation:
grep 'image: chatwoot/chatwoot' docker-compose.production.yaml
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker compose -f docker-compose.production.yaml logs --tail=200 rails sidekiq
Keep application traffic stopped while repairing migrations. If logs show an unsupported cross-version upgrade, follow the official supported sequence rather than repeatedly restarting.
- A/AAAA records match working network paths.
- Only 22, 80 and 443 are public; 3000/5432/6379 use loopback.
- The reviewed
v4.17.1-ceimage is pinned, rather thanlatest. -
.envhas mode 600; default/blank passwords are replaced in both application and database settings. -
ENABLE_ACCOUNT_SIGNUPis disabled after the first administrator is created. - MFA encryption keys are preserved in protected backups.
- The website widget sends and receives messages in realtime.
- SMTP, invitations, notifications and password reset have been tested.
- External channels use official credentials with a rotation plan.
- PostgreSQL, attachments, Redis queue policy and configuration have offsite recovery points.
- An isolated recovery drill succeeded.
- Rails, Sidekiq, database, Redis, disk and HTTPS have alerts.
It is not recommended for production. The official minimum is 4 GB RAM, and the host also runs Sidekiq, PostgreSQL, Redis, Docker and Caddy. A 2 GB instance might start at very low load but can run out of memory during upgrades, imports or message spikes.
CE can be self-hosted and is currently listed at $0 per agent. Confirm the license obligations for the chosen version. Advanced functions are not all included: check the current plans for Captain AI, voice, branding, permissions, SSO/SAML, SLA and vendor support.
No. PostgreSQL is the officially supported database. An unofficial conversion is not the maintained production deployment described here.
PostgreSQL holds core conversations, contacts and configuration, while Redis handles queues and cache. Redis loss can discard pending work or cause retries. Persist and monitor it, drain queues before maintenance when practical, and decide how the recovery process handles pending jobs.
Usually no. reverse_proxy supports it by default. Investigate the preceding CDN/WAF, browser connections, FRONTEND_URL and Rails logs when realtime messaging fails.
No. Meta's account, review, template, webhook and billing rules still apply. Use the official integration procedure.
A maintainable Chatwoot installation needs controlled image versions, clear Rails/Sidekiq/PostgreSQL/Redis dependencies, verified HTTPS and email, and recoverable database and attachments.
For a new small or medium team, start around 4 vCPU and 8 GB RAM, with a pinned CE image, Caddy HTTPS, local attachments and offsite backups. As volume and channels grow, separate PostgreSQL, workers and object storage. Go live once support messages flow correctly, jobs remain healthy and you have completed a recovery drill.