Chatwoot mit Docker auf einem VPS selbst hosten
Installieren Sie Chatwoot mit Docker Compose und Traefik: feste Tags, funktionierendes SMTP, Backups für Postgres und Uploads sowie sichere Upgrades.
Was Sie erstellen
Für das Self-Hosting von Chatwoot auf einem VPS führen Sie vier Container aus: einen Rails-Webprozess, einen Sidekiq-Hintergrund-Worker, PostgreSQL mit der Erweiterung pgvector und Redis. Chatwoot ist ein Open-Source-Kundensupportsystem. Sie erhalten damit einen gemeinsamen Team-Posteingang und ein Website-Chat-Widget auf einem von Ihnen kontrollierten Server. Die Installation dauert etwa zwanzig Minuten. Ob das System auch in einem Jahr noch läuft, hängt von allem ab, was danach kommt: E-Mail-Zustellung, Backups, Upgrades und die Dimensionierung.
Jeder Container hat eine Aufgabe. Rails stellt das Agent-Dashboard und die Widget-API (Application Programming Interface) bereit. Sidekiq führt zeitaufwendige Aufgaben aus: E-Mails senden, verbundene Kanäle abfragen, Automatisierungsregeln ausführen und Berichte erstellen. Postgres speichert Unterhaltungen, Kontakte, Agentenkonten und jede Einstellung, die Sie im Dashboard ändern. Redis speichert die Sidekiq-Warteschlangen und den ActionCable-Pub/Sub-Kanal, der eine neue Nachricht ohne Neuladen der Seite in ein geöffnetes Dashboard überträgt. Redis ist hier kein entbehrlicher Cache. Wenn Redis verloren geht, gehen auch die eingereihten Jobs verloren.
Das Postgres-Image in der vorgelagerten Compose-Datei ist pgvector/pgvector:pg16 und nicht das Standard-Image postgres, weil das Schema von Chatwoot für seine KI-Funktionen die Erweiterung vector aktiviert. Wenn Sie stattdessen das Standard-Postgres verwenden, bricht der erste Datenbankstart mit ERROR: extension "vector" is not available ab, weil die Steuerdatei der Erweiterung in diesem Image fehlt. Verwenden Sie das Image, das upstream bereitstellt.
Diese Anleitung setzt voraus, dass Docker und ein Reverse Proxy auf dem Server bereits funktionieren. Falls nicht, beginnen Sie mit Docker Compose auf einem VPS und kehren Sie anschließend hierher zurück.
Wie viel VPS benötigt ein selbst gehostetes Chatwoot?
Stand Oktober 2026 nennt die Upstream-Anforderungsseite mindestens 4 GB RAM und 4 CPU-Kerne. Diese Konfiguration ist für bis zu 10.000 Unterhaltungen pro Tag ausgelegt. Für bis zu 20.000 Unterhaltungen pro Tag werden 8 GB RAM und 8 CPU-Kerne genannt. Außerdem werden mindestens 1 GB Swap empfohlen. Der Grund wird direkt angegeben: So läuft der Rechner während eines Upgrades nicht wegen Speichermangels aus. Planen Sie für Postgres zunächst 5 GB bis 10 GB Festplattenspeicher ein. Speicherbedarf für Datei-Uploads ist darin noch nicht enthalten.
Der kritische Punkt ist folgender. Ein VPS mit 2 GB RAM startet Chatwoot. Mit zwei Agents und einem wenig ausgelasteten Posteingang wirkt alles zunächst unauffällig. Unter zwei Bedingungen kommt es jedoch zu Problemen. Die erste ist Sidekiq. Upstream gibt für einen ausgelasteten Server mehr als 1 GB Speicherbedarf an. Ein Schub eingehender E-Mails oder ein Report-Job kann den Speicher des Systems daher vollständig aufbrauchen, bevor Rails, Postgres und Redis ihren Anteil belegt haben. Die zweite Bedingung ist das Upgrade. Dabei startet db:chatwoot_prepare einen neuen Rails-Prozess, um Migrationen anzuwenden. Der Start von Rails benötigt auf diesem Image bereits mehrere hundert Megabyte, bevor der Prozess eine nützliche Aufgabe ausführt.
Zuvor erscheint keine zuverlässige Warnung. Der Out-of-Memory-Killer des Kernels sendet SIGKILL an den ausgewählten Prozess, normalerweise an den größten. Docker erkennt, dass der Container beendet wurde, und restart: always startet ihn erneut. docker compose ps --all zeigt dann einen Container, der ständig neu gestartet wird oder bei Exited (137) bleibt. Der Wert 137 bedeutet, dass der Prozess durch Signal 9 beendet wurde. Ohne --all werden beendete Container überhaupt nicht aufgelistet. Der Exit-Code 137 allein beweist nicht, dass Speichermangel die Ursache war, da docker kill dasselbe Signal sendet. Bestätigen Sie die Ursache daher mit sudo dmesg -T | grep -i "killed process". Dieser Befehl nennt den Prozess, den der Kernel ausgewählt hat.
Wenn 4 GB das Budget überschreiten, können Sie einen Rechner mit 2 GB RAM und 2 GB Swap betreiben. Akzeptieren Sie dann, dass sich die Antwortzeiten unter Last verschlechtern. Swap dient als Puffer gegen Speichermangel, ist aber keine Garantie. Ein ausreichend großer Lastanstieg kann daher weiterhin dazu führen, dass ein Container beendet wird. Unabhängig davon sollten Sie ein hartes Speicherlimit pro Dienst festlegen. So kann der Worker die Datenbank nicht mit in den Ausfall ziehen. Siehe Speicherlimits in Docker Compose.
Datei-Uploads wachsen ohne eine von Ihnen festgelegte Obergrenze. Jeder Screenshot, den ein Kunde anhängt, wird im Storage-Volume gespeichert und bleibt dort. Überwachen Sie daher docker system df -v, anstatt anzunehmen, dass die Datenbank den Festplattenspeicher belegt hat.
Compose-Datei abrufen und einen Versions-Tag festlegen
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 .envIn der gerade heruntergeladenen Datei steht image: chatwoot/chatwoot:latest. Ändern Sie diesen Eintrag, bevor Sie etwas anderes tun.
services:
base: &base
image: chatwoot/chatwoot:v4.19.1
env_file: .env
volumes:
- storage_data:/app/storagelatest bedeutet, dass docker compose pull Ihnen die Version bereitstellt, die an diesem Morgen veröffentlicht wurde. Das kann eine Hauptversion mit Migrationen sein, über die Sie noch nichts gelesen haben. Chatwoot-Migrationen lassen sich in der Praxis nicht rückgängig machen. Ein unbeabsichtigter Versionssprung erfordert daher eine Wiederherstellung aus einem Backup und kein einfaches Rückgängigmachen. Legen Sie den Tag fest und ändern Sie ihn bewusst. v4.19.1 war am 25 October 2026 die aktuelle Version. In den Release Notes wird diese Version wegen der neuesten Security-Fixes und Verbesserungen an der Absicherung empfohlen. Sehen Sie auf der Releases-Seite nach, welchen Tag Sie heute festlegen sollten. Wenn Sie von v4.18.0 oder einer früheren Version aktualisieren, lesen Sie zuerst die Hinweise zu v4.19.0: Captain V1 wurde eingestellt, und Self-Hosting-Installationen, die Anweisungen für V1 verwenden, müssen vor dem Upgrade auf V2 migriert werden. Für alles, was eine Datenbank verwaltet, gilt dieselbe Vorsicht. Deshalb beginnt auch das Self-Hosting des OpenGym-Workout-Trackers mit dem Festlegen eines Git-Tags, obwohl es sich um eine deutlich kleinere Anwendung als diese handelt.
Der Dienst base ist ein YAML-Anker, den rails und sidekiq beide zusammenführen. Wenn Sie den Tag an einer Stelle ändern, gilt die Änderung daher für beide. Löschen Sie in derselben Datei außerdem die Zeile version: '3' am Anfang. Modernes Compose ignoriert sie und gibt bei jedem Befehl the attribute 'version' is obsolete, it will be ignored aus.
Die .env-Datei ausfüllen
Generieren Sie zuerst das Secret. Upstream erwartet einen alphanumerischen Wert, weil Sonderzeichen verändert werden können, wenn der Wert eine Shell oder einen YAML-Parser durchläuft.
head /dev/urandom | tr -dc A-Za-z0-9 | head -c 63 ; echo ''Setzen Sie anschließend diese Schlüssel in .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=localPOSTGRES_HOST=postgres und redis://redis:6379 sind die Compose-Dienstnamen, die im standardmäßigen Netzwerk des Projekts aufgelöst werden. FRONTEND_URL ist keine reine Dekoration. Chatwoot erstellt daraus die URL für das Widget-Skript und jeden Link in einer ausgehenden E-Mail. Ein falscher Wert führt daher zu Links für die Passwortzurücksetzung, die auf einen Host zeigen, der nicht antwortet.
Die eigentliche Falle befindet sich in der Upstream-Datei. Der Dienst postgres liest .env nicht ein. Er enthält einen eigenen environment-Block, in dem POSTGRES_PASSWORD= leer bleibt. Wenn Sie das Passwort nur in .env setzen, hat die Datenbank daher kein Passwort, während die Anwendung eines verwendet. Verweisen Sie den Dienst auf dieselbe 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 liest .env aus dem Projektverzeichnis für die ${...}-Substitution. Dadurch erhalten beide Seiten dieselbe Zeichenfolge. Bei einer falschen Konfiguration beendet sich Rails mit PG::ConnectionBad: FATAL: password authentication failed for user "postgres".
Ein Verhalten überrascht fast alle: Das Postgres-Image wendet POSTGRES_PASSWORD nur an, wenn es ein leeres Datenverzeichnis initialisiert. Eine spätere Änderung hat keine Wirkung, weil initdb nicht erneut ausgeführt wird. Wenn Sie den Stack bereits einmal gestartet haben, ändern Sie den Wert direkt in der Datenbank.
docker compose exec postgres psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'the-new-password';"ENABLE_ACCOUNT_SIGNUP=true ist nur vorübergehend erforderlich. Damit wird das öffentliche Registrierungsformular geöffnet, damit Sie das erste Konto erstellen können. Setzen Sie den Wert auf false und führen Sie docker compose up -d erneut aus, sobald Ihr Konto existiert. Andernfalls kann sich jeder, der die URL findet, in Ihrem Supportsystem registrieren. Danach werden Agents per Einladung hinzugefügt. Ihre Passwörter werden ausschließlich in dieser Anwendung gespeichert. Das funktioniert problemlos, bis Sie etwa ein halbes Dutzend Dienste betreiben und die separate Kontoliste in jedem Dienst verwalten müssen. Dann ist ein selbst gehosteter Identity Provider wie Authentik die Komponente, die diese Kontolisten ersetzt.
.env enthält jetzt alle Secrets dieses Stacks im Klartext. Setzen Sie daher den Modus auf 600 und nehmen Sie die Datei aus git aus. Wie Compose Env-Dateien liest und wo Secrets offengelegt werden behandelt die kritischen Punkte, einschließlich des Unterschieds zwischen env_file und environment.
Chatwoot hinter Ihrem bestehenden Traefik betreiben
Bauen Sie keinen zweiten Reverse Proxy für eine einzelne Anwendung. Wenn Traefik auf diesem Server bereits für andere Container TLS (Transport Layer Security) terminiert, wird Chatwoot über einen Label-Block eingebunden. Falls das noch nicht eingerichtet ist, richten Sie es einmal mit Traefik vor mehreren Docker-Compose-Anwendungen ein und kehren Sie anschließend hierher zurück.
Belassen Sie die docker-compose.yaml-Datei des Upstream möglichst unverändert, damit Sie sie später mit einer neueren Version vergleichen können, und legen Sie Ihre Änderungen in einer Override-Datei ab. Compose führt docker-compose.override.yaml automatisch zusammen. Compose auf mehrere Dateien aufteilen erläutert die Regeln für diese Zusammenführung.
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: trueVerwenden Sie Ihre eigenen Namen für Entrypoint und Certresolver. Der Container muss sich im selben Docker-Netzwerk wie Traefik befinden. Dafür sorgt der Eintrag proxy. Außerdem muss er weiterhin in default eingebunden sein, sonst verliert er den Zugriff auf Postgres und Redis. Diese zweite Zeile wird häufig vergessen.
Lassen Sie den Block ports: unverändert. Upstream bindet ihn an 127.0.0.1:3000, also ausschließlich an die Loopback-Schnittstelle. Dadurch ist er nicht aus dem Internet erreichbar und bleibt für Tests innerhalb des Servers mit curl -I http://127.0.0.1:3000 nutzbar.
Das Agent-Dashboard hält für die Live-Zustellung von Nachrichten eine WebSocket-Verbindung zu /cable offen. Traefik leitet das HTTP-Upgrade ohne zusätzliche Konfiguration weiter. Sie müssen daher nichts ergänzen. Wenn Sie später einen CDN oder einen weiteren Proxy vor Traefik setzen, müssen Sie dort WebSockets erlauben. Andernfalls lädt das Dashboard zwar normal, neue Nachrichten erscheinen jedoch erst nach einer manuellen Aktualisierung.
Datenbank initialisieren und den Stack starten
Starten Sie zuerst die Datendienste, und warten Sie, bis Postgres den ersten Start abgeschlossen hat.
docker compose up -d postgres redis
docker compose logs postgres | tail -n 5Warten Sie auf database system is ready to accept connections. Erstellen Sie anschließend das Schema.
docker compose run --rm rails bundle exec rails db:chatwoot_prepareDamit wird die Datenbank erstellt, falls sie fehlt. Anschließend werden das Schema und die standardmäßigen Seed-Daten geladen. Der Befehl gibt Migrationszeilen aus und wird fehlerfrei beendet. Wenn kontinuierlich postgres:5432 - no response ausgegeben wird, wartet der Entrypoint auf eine Datenbank, die noch keine Verbindungen annimmt. Beim ersten Start bedeutet das normalerweise, dass initdb noch arbeitet. Warten Sie, lesen Sie die Postgres-Logs und führen Sie den Befehl anschließend erneut aus. Wenn der Vorgang bei der Erweiterung vector stoppt, haben Sie das pgvector-Image durch das Standard-Postgres-Image ersetzt.
docker compose up -d
docker compose ps
docker compose logs --tail 30 railsBei allen vier Containern sollte Up angezeigt werden. Das Rails-Log sollte mit einer Puma-Zeile enden, die auf http://0.0.0.0:3000 lauscht. Prüfen Sie anschließend den öffentlichen Pfad:
curl -sI https://support.example.com | head -n 1HTTP/2 200 bedeutet, dass die gesamte Kette funktioniert. Ein 404 von Traefik bedeutet, dass die Router-Regel nicht zutraf, meistens wegen eines Tippfehlers im Hostnamen. Ein 502 bedeutet, dass Traefik den Router gefunden hat, den Container aber nicht erreichen konnte. Fast immer fehlt dann das proxy-Netzwerk oder es ist ein loadbalancer.server.port konfiguriert, das nicht 3000 entspricht.
Öffnen Sie die URL, erstellen Sie Ihr Konto unter /app/auth/signup, setzen Sie anschließend ENABLE_ACCOUNT_SIGNUP=false und führen Sie docker compose up -d aus, um das Formular zu schließen.
Warum Passwortzurücksetzungen und E-Mail-Konversationen ohne SMTP fehlschlagen
Chatwoot ohne SMTP-Einstellungen (Simple Mail Transfer Protocol) ist ein Supportdesk, der keine E-Mails senden kann. Dadurch funktionieren nicht nur Benachrichtigungen nicht mehr. Passwortzurücksetzungen werden beendet, sodass ein Administrator, der ausgesperrt wird, ausgesperrt bleibt. Einladungen für Agents funktionieren ebenfalls nicht mehr, weil eine Einladung per E-Mail versendet wird. Antworten an Kunden in einer E-Mail-Konversation funktionieren nicht mehr, sodass die Konversation nur noch in eine Richtung läuft. Diesen Schritt überspringen viele und bemerken das Problem dann in der schwierigsten Woche.
Der Mechanismus ist eindeutig. Wenn SMTP_ADDRESS nicht gesetzt ist, stellt Chatwoot ActionMailer auf die Zustellung über sendmail um. In der Upstream-Dokumentation wird dies als Postfix-Setup beschrieben. Es ist seit v2.12.0 die Standardeinstellung. Die Anleitung installiert Postfix mit sudo apt install -y postfix auf dem Server. Dieses Docker-Setup führt das nicht aus. Daher ist kein konfigurierter Mailserver vorhanden, an den diese Zustellmethode die E-Mails übergeben kann. Der Versand erfolgt aus einem Hintergrundjob. Deshalb landet ein Fehler der Zustellung im Sidekiq-Log und nicht im Rails-Log. Die Person, die auf „Passwort vergessen“ klickt, sieht währenddessen eine positive Bestätigung und erhält keine E-Mail.
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=trueVerwenden Sie Port 587 mit STARTTLS. Dabei wird die Verbindung im Klartext geöffnet und vor der Authentifizierung auf Verschlüsselung umgestellt. Viele VPS-Anbieter blockieren ausgehenden Port 25 standardmäßig, um Spam zu begrenzen. Seit dem 8. November 2026 blockiert Hetzner auf Cloud-Servern standardmäßig die Ports 25 und 465. Die Sperre wird pro Konto durchgesetzt. Vultr blockiert Port 25 auf allen neuen Compute Instances. Beide Anbieter prüfen Anträge auf Aufhebung der Sperre einzeln. Bei Hetzner müssen Sie seit einem Monat Kunde sein und die erste Rechnung bezahlt haben, bevor Sie einen Antrag auf Aufhebung des Limits stellen können. Port 587 wird von keinem der beiden Anbieter blockiert. Ein Relay auf Port 587 funktioniert daher bereits beim ersten Boot ohne Ticket und ohne Wartezeit. SMTP_DOMAIN ist die Domain, die Ihr Server während der SMTP-Konversation bekannt gibt. Einige Relays lehnen eine Abweichung ab.
Übernehmen Sie die Einstellungen und überwachen Sie den Worker:
docker compose up -d rails sidekiq
docker compose logs -f sidekiqLösen Sie auf der Anmeldeseite eine Passwortzurücksetzung aus. Bei einer funktionierenden Zustellung wird der Mailer-Job im Sidekiq-Log normal beendet. Bei einem Fehler wird zuerst die Exception-Klasse angezeigt. Danach versucht Sidekiq die Zustellung mit zunehmender Wartezeit erneut. Deshalb erzeugt ein fehlerhaftes Relay über Stunden alle paar Minuten denselben Fehler.
Zwei Ablehnungen treten häufig auf. Keine davon ist ein Fehler in Chatwoot. 535 Authentication failed bedeutet, dass die Authentifizierung fehlgeschlagen ist. Prüfen Sie daher die Zugangsdaten, ob die SMTP-Authentifizierung aktiviert ist und ob eine Zugriffsrichtlinie die Authentifizierung blockiert. Korrekte Zugangsdaten allein schließen diesen Fehler nicht aus. Einige Anbieter verlangen anstelle des Kontopassworts ein Anwendungspasswort. 550 Sender address rejected bedeutet, dass der Server die Absenderadresse abgelehnt hat. Lesen Sie die vollständige Antwort, bevor Sie MAILER_SENDER_EMAIL ändern. Fehlende Absenderberechtigungen oder eine nicht abgeschlossene Verifizierung sind mögliche Ursachen. 550 5.7.27 Sender address rejected: Domain does not accept mail weist jedoch auf eine Absenderdomain mit einem Null-MX-Record hin.
Der Empfang von E-Mails in einer Konversation ist ein separater Vorgang. Für die Weiterleitung über den Ingress von Chatwoot werden MAILER_INBOUND_EMAIL_DOMAIN und RAILS_INBOUND_EMAIL_SERVICE sowie ein Mailserver benötigt, der eingehende Nachrichten an Chatwoot übergibt. Sie können auch ein Postfach über IMAP anbinden, einschließlich Google- oder Microsoft-OAuth, ohne diesen Weiterleitungspfad einzurichten. Ein gemietetes Relay ist der schnellste Weg. Wenn Sie den gesamten Mailpfad selbst betreiben möchten, beschreibt den Betrieb eines eigenen Mailservers mit Mailcow, was diese Verpflichtung tatsächlich umfasst.
Was Sie sichern müssen und wie Sie die Wiederherstellung nachweisen
Ein Chatwoot-Backup besteht aus vier Teilen. Fehlt einer davon, wird die Wiederherstellung zu einer Neuinstallation.
- Die Postgres-Datenbank. Sie enthält Unterhaltungen, Kontakte, Agent-Konten und alle Einstellungen.
- Das
storage_data-Volume.ACTIVE_STORAGE_SERVICE=localschreibt hochgeladene Dateien auf die Festplatte und speichert in Postgres nur eine Referenzzeile. - Die
.env-Datei. Sie enthältSECRET_KEY_BASEund dieACTIVE_RECORD_ENCRYPTION_*-Schlüssel. - Die Compose-Dateien. Sie dokumentieren den exakten Image-Tag, zu dem das Datenbankschema passt.
Wenn Sie nur die Datenbank wiederherstellen, sind alle Unterhaltungen wieder vorhanden, aber die Anhänge funktionieren nicht. Die Datensätze verweisen auf Dateien, die nicht mehr auf der Festplatte liegen.
cd ~/chatwoot
docker compose exec -T postgres pg_dump -U postgres -Fc chatwoot > db-$(date +%F).dump-T ist wichtig. Ohne diese Option weist Compose ein Pseudo-Terminal zu. Dadurch werden Newline-Bytes im Datenstrom geändert. Die resultierende Dump-Datei wird von pg_restore abgelehnt. -Fc ist das benutzerdefinierte Format. Es komprimiert die Daten und ermöglicht es pg_restore, selektiv zu arbeiten.
docker run --rm -v chatwoot_storage_data:/data:ro -v "$PWD":/backup alpine \
tar czf /backup/storage-$(date +%F).tgz -C /data .Der Volume-Name besteht aus dem Namen Ihres Projektverzeichnisses und _storage_data. Bestätigen Sie ihn mit docker volume ls | grep storage_data, bevor Sie diesem Befehl vertrauen. Docker erstellt ein leeres Volume, anstatt mit einem Fehler abzubrechen, wenn Sie ein nicht vorhandenes Volume angeben. Sie erhalten dann ein gültiges, leeres Archiv und überhaupt keinen Fehler. Prüfen Sie anschließend die Größe mit ls -lh storage-*.tgz.
Beide Dateien liegen nun auf derselben Festplatte wie die Daten, die sie schützen sollen. Das schützt Sie vor nichts. Übertragen Sie die Dateien auf ein anderes System und verschlüsseln Sie sie. Ein Datenbank-Dump enthält jede Kundennachricht im Klartext. Verschlüsselte Offsite-Backups mit restic behandelt die Planung und Aufbewahrung.
Der Wiederherstellungstest: Führen Sie ihn durch, bevor Sie ihn benötigen
Stellen Sie die Daten auf einem zweiten VPS wieder her, nicht auf dem produktiven System. Kopieren Sie .env, die Compose-Dateien und beide Archive auf das zweite System und führen Sie anschließend Folgendes aus:
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 löscht die vorhandenen Objekte vor dem Laden. Verwenden Sie den Befehl daher nur für eine Datenbank, deren Inhalt Sie löschen können. Melden Sie sich anschließend an und öffnen Sie eine Unterhaltung mit einem Anhang. Wenn die Nachrichtenliste geladen wird und sich die Datei herunterladen lässt, ist das Backup brauchbar.
Eine Wiederherstellung mit einem anderen SECRET_KEY_BASE macht alle Sitzungscookies ungültig. Dadurch werden alle Benutzer abgemeldet. Eine Wiederherstellung mit anderen ACTIVE_RECORD_ENCRYPTION_*-Schlüsseln ist noch problematischer: Chatwoot kann die Spalten mit den Zugangsdaten der Kanäle nicht entschlüsseln und meldet ActiveRecord::Encryption::Errors::Decryption. Deshalb steht .env auf der Backup-Liste.
So aktualisieren Sie Chatwoot auf ein neues Tag
Die Reihenfolge ist wichtiger als die einzelnen Befehle.
- Lesen Sie die Release Notes zwischen Ihrem Tag und dem Ziel-Tag. Achten Sie dabei auf erforderliche manuelle Schritte.
- Erstellen Sie einen aktuellen Datenbank-Dump und ein Archiv des Speichers. Prüfen Sie, ob beide Dateigrößen plausibel sind.
- Bearbeiten Sie das Image-Tag für den Dienst
baseindocker-compose.yaml. - Pullen Sie das neue Image, stoppen Sie den Stack, führen Sie die Migrationen aus und starten Sie den Stack anschließend erneut.
docker compose pull
docker compose down
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
docker compose up -d
docker compose imagesPullen Sie das Image vor der Migration. Die Migration muss aus dem neuen Image ausgeführt werden, weil das alte Image die neuen Migrationsdateien nicht enthält. Stoppen Sie den Stack vor der Migration. Der alte Code und das neue Schema sind nicht kompatibel. Ein laufender alter Rails-Prozess kann daher Fehler auslösen oder Datensätze schreiben, die das neue Schema nicht akzeptiert. Das Stoppen gibt außerdem den Arbeitsspeicher frei, den die Migration benötigt. Genau deshalb fordert Upstream Swap an.
docker compose images gibt das Tag aus, mit dem jeder Container tatsächlich läuft. Damit erkennen Sie den Fall, dass Sie das Tag geändert, das Image aber nicht gepullt haben.
Wie weit Sie direkt aktualisieren können, hängt vom Alter der Installation ab. Wenn Ihre Installation ein oder zwei Releases zurückliegt, lesen Sie die Release Notes zwischen Ihrem Tag und dem Ziel-Tag, setzen Sie das Ziel-Tag und führen Sie die oben genannten Schritte einmal aus. Nur bei einer sehr alten Installation weist die Docker-Anleitung von Upstream an, nacheinander über Zwischen-Tags zu aktualisieren, statt direkt auf das neueste Image zu wechseln. Wiederholen Sie in diesem Fall die Schritte zum Ändern des Tags, Pullen und Vorbereiten für jedes Zwischen-Tag, weil Upstream nach jedem Upgrade db:chatwoot_prepare verlangt.
Wenn Rails startet, bevor die Migration ausgeführt wurde, verweigert der Prozess die Verarbeitung von Anfragen und protokolliert ActiveRecord::PendingMigrationError: Migrations are pending. Wenn restart: always gesetzt ist, wird der Container anschließend wiederholt neu gestartet. Daher zeigt docker compose ps eine Laufzeit an, die sich alle paar Sekunden zurücksetzt. Führen Sie den Vorbereitungsschritt aus. Dadurch wird der Fehler behoben.
Für ein Rollback setzen Sie das alte Tag wieder ein und stellen den Dump wieder her. Es gibt keinen verlässlichen Pfad für Rückwärtsmigrationen. Dafür ist Schritt 2 erforderlich.
Fehlerbilder und die angezeigten Meldungen
502 Bad Gateway von Traefik. Der Router wurde ausgewählt, aber das Backend hat nicht geantwortet. Prüfen Sie mit docker compose ps, ob rails als Up angezeigt wird. Führen Sie anschließend docker network inspect proxy aus und stellen Sie sicher, dass der rails-Container in der Containerliste erscheint. Ein Container, der nicht angebunden ist, ist für Traefik nicht sichtbar. Die Anfrage passt dann zu einem Router, wird aber nicht weitergeleitet.
Das Dashboard wird geladen, aber neue Nachrichten werden erst nach einer Aktualisierung angezeigt. Die WebSocket-Verbindung zu /cable wird nicht durchgelassen, oder FRONTEND_URL stimmt nicht mit der Adresse in der Browserleiste überein. Bei einer Abweichung versucht die Seite, eine WebSocket-Verbindung zu einer anderen Origin zu öffnen. Der Browser blockiert diese Verbindung.
FATAL: password authentication failed for user "postgres". Das Passwort in .env und das im Postgres-Datenvolume gespeicherte Passwort unterscheiden sich. Beheben Sie das Problem mit ALTER USER im laufenden Container. Eine erneute Änderung von .env ändert eine bereits initialisierte Datenbank nicht.
NOAUTH Authentication required. Redis läuft mit --requirepass, aber die Anwendung hat sich ohne Passwort verbunden. Daher fehlt REDIS_PASSWORD in .env oder wurde nicht übernommen. Testen Sie das von Redis erwartete Passwort direkt mit docker compose exec redis sh -c 'redis-cli -a "$REDIS_PASSWORD" ping'. Der Befehl sollte mit PONG antworten. Die einfachen Anführungszeichen sind erforderlich. Sie sorgen dafür, dass die Variable im Container expandiert wird. Dort wird .env gelesen, nicht in Ihrer eigenen Shell, wo die Variable normalerweise leer ist.
Container werden mit Code 137 beendet. Das ist SIGKILL. Auf einem kleinen Server wird dieses Signal normalerweise vom Out-of-Memory-Killer des Kernels gesendet. Allerdings sendet auch docker kill dasselbe Signal. Prüfen Sie daher sudo dmesg -T | grep -i "killed process", bevor Sie Speichermangel als Ursache annehmen. Bei Speichermangel fügen Sie Swap hinzu, legen Sie Speicherlimits pro Dienst fest oder wechseln Sie zu einem größeren Tarif.
FAQ
Wie viel RAM benötigt ein selbst gehosteter Chatwoot-VPS?
Stand Oktober 2026 fordert der Upstream mindestens 4 GB RAM und 4 CPU-Kerne für bis zu 10.000 Unterhaltungen pro Tag sowie 8 GB RAM und 8 Kerne für bis zu 20.000. Fügen Sie mindestens 1 GB Swap hinzu, weil ein Upgrade einen zweiten Rails-Prozess zum Anwenden der Migrationen startet und kleinen Systemen dabei der Speicher ausgeht. Ein VPS mit 2 GB RAM startet und funktioniert für einige wenige Agents, aber allein Sidekiq kann unter Last mehr als 1 GB belegen. Rechnen Sie daher in stark ausgelasteten Zeiten und während Upgrades mit Containern, die mit Exit-Code 137 beendet werden.
Warum kommen E-Mails zum Zurücksetzen von Chatwoot-Passwörtern nie an?
Weil kein SMTP_ADDRESS gesetzt ist. Chatwoot verwendet dann die Zustellung über sendmail. Der Upstream geht dabei von einem auf dem Host installierten Postfix-Server aus. Dieses Docker-Setup enthält keinen solchen Server. Der Job läuft in Sidekiq. Deshalb landet jeder Zustellungsfehler im Sidekiq-Log, während der Browser weiterhin eine Erfolgsmeldung anzeigt. Setzen Sie SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD und MAILER_SENDER_EMAIL in .env. Starten Sie anschließend die Dienste rails und sidekiq neu. Überwachen Sie danach docker compose logs -f sidekiq, während Sie das Zurücksetzen auslösen.
Was muss ich sichern, um Chatwoot wiederherzustellen?
Die Postgres-Datenbank, das Docker-Volume storage_data, die Datei .env und die Compose-Dateien. Die Datenbank allein reicht nicht aus. Hochgeladene Dateien liegen im Volume, während Postgres nur Referenzen auf diese Dateien speichert. Eine Wiederherstellung ausschließlich der Datenbank liefert daher Unterhaltungen mit defekten Anhängen. .env ist wichtig, weil ein anderes SECRET_KEY_BASE alle Benutzer abmeldet. Andere ACTIVE_RECORD_ENCRYPTION_*-Schlüssel machen die verschlüsselten Spalten unlesbar.
Wie aktualisiere ich Chatwoot, ohne die Datenbank zu beschädigen?
Erstellen Sie ein Backup. Lesen Sie die Release Notes zwischen Ihrem Tag und dem Ziel-Tag. Ändern Sie den Image-Tag in Ihrer Compose-Datei. Führen Sie anschließend docker compose pull, docker compose down, docker compose run --rm rails bundle exec rails db:chatwoot_prepare und docker compose up -d aus. Führen Sie zuerst den Pull aus, weil die Migrationen aus dem neuen Image ausgeführt werden müssen. Stoppen Sie zuerst den Stack, weil alter Code mit einem neuen Schema Fehler verursacht. Nur eine sehr alte Installation muss nacheinander über Zwischen-Tags aktualisiert werden, statt direkt auf den neuesten Tag zu wechseln. Führen Sie den Vorbereitungsschritt nach jedem Zwischen-Tag aus.
Kann ich statt pgvector das Standard-Postgres-Image verwenden?
Nein. Das Schema von Chatwoot aktiviert die Erweiterung vector. Deshalb schlägt das Standard-Image postgres während db:chatwoot_prepare mit ERROR: extension "vector" is not available fehl, weil die Steuerdatei der Erweiterung in diesem Image nicht vorhanden ist. Behalten Sie pgvector/pgvector:pg16 aus der Upstream-Compose-Datei bei. Alternativ können Sie ein anderes Image verwenden, das pgvector für Ihre Postgres-Hauptversion enthält.