Chatwoot bündelt Live-Chat, E-Mail und externe Kanäle in einer gemeinsamen Inbox. Agenten weisen Gespräche zu und hinterlegen interne Notizen. Diese Anleitung zeigt Chatwoot v4.19.0 als Vier-Dienste-Compose-Projekt im Synology Container Manager. Selbsthosting hält die gespeicherten Daten auf Ihrem NAS; externe Kanäle übertragen Daten an ihre Anbieter. Datenschutzkonformität erfordert passende Einstellungen, Zugriffsrechte und organisatorische Maßnahmen.

Voraussetzungen

Synology NAS mit x86_64-Prozessor (z. B. DS923+, DS1522+, DS1823xs+) und mindestens 4 GB RAM installiert (2 GB für DSM, ~1 GB für den Chatwoot-Stack)
DSM 7.2 oder neuer mit installiertem Container Manager (kostenlos im Package Center)
SSH-Zugang zum NAS: Sie benötigen ihn für den Datenbank-Init-Befehl und die Migrationen nach Updates, weil der Container Manager keine Befehle in laufenden Containern ausführt; Aktivierung Schritt für Schritt: SSH auf dem Synology NAS aktivieren und verbinden
Domain oder DynDNS-Adresse mit gültigem HTTPS-Zertifikat (z. B. *.synology.me Wildcard-Zertifikat oder eigene Domain mit Let's Encrypt). Chatwoot benötigt zwingend HTTPS für Cookies und das Live-Chat-Widget
Ca. 2 GB freier Speicherplatz auf dem Volume für Images und Datenbankwachstum
SMTP-Zugangsdaten für E-Mail-Versand (Gmail App-Passwort, Sendgrid, Mailgun o. ä.), optional, aber für den E-Mail-Kanal notwendig
Grundkenntnisse in Docker Compose, Auffrischung: Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren

Hardware für diese Anleitung

Enthält Werbelinks

Synology mit Container Manager	Container laufen nur auf Modellen mit Container Manager, vor allem der Plus-Serie. Vor dem Kauf die Kompatibilitätsliste von Synology prüfen. Bei uns läuft eine DS920+.	Synology bei Amazon (Werbelink)
NAS-Festplatten	Für den Dauerbetrieb Platten mit CMR-Technik wählen, für RAID 1 zwei gleich große.	NAS-Platten bei Amazon (Werbelink)
RAM-Erweiterung	Mehrere Container gleichzeitig brauchen Speicher. Viele Plus-Modelle lassen sich aufrüsten, das passende Modul steht im Datenblatt.	Bei Amazon ansehen (Werbelink)

Vorhandene Hardware reicht oft. Die Liste zeigt, worauf es bei einem Neukauf ankommt. * Werbelink

Schritt 1: Ordnerstruktur anlegen

Legen Sie die Ordner für Uploads, PostgreSQL und Redis vor dem Start an. Prüfen Sie die Berechtigungen, wenn PostgreSQL wrong ownership meldet.

Öffnen Sie die File Station und erstellen Sie folgende Verzeichnisse unterhalb von /volume1/docker/:

/volume1/docker/chatwoot/
/volume1/docker/chatwoot/storage
/volume1/docker/chatwoot/db
/volume1/docker/chatwoot/redis

Die drei Unterordner müssen vor dem Start existieren. Prüfen Sie ihre Eigentümer und Rechte nach den Anforderungen des jeweiligen Images. Details: Docker-Ordner und Berechtigungen auf dem Synology NAS.

Verifizieren: Öffnen Sie die File Station und navigieren Sie nach /volume1/docker/chatwoot. Sie sehen drei Unterordner: storage, db und redis. Alle drei müssen vorhanden sein, bevor Sie weitermachen.

Schritt 2: SECRET_KEY_BASE und Passwörter generieren

Erzeugen Sie SECRET_KEY_BASE per SSH mit folgendem Befehl. Verwenden Sie ausschließlich A-Za-z0-9, wie die Herstellerdokumentation vorgibt:

cat /dev/urandom | tr -dc A-Za-z0-9 | head -c 128 ; echo

Bewahren Sie den Schlüssel sicher auf. Erzeugen Sie auch PostgreSQL- und Redis-Passwörter und übernehmen Sie alle Werte in die Compose-Datei.

Verifizieren: Der generierte Schlüssel ist exakt 128 Zeichen lang und enthält ausschließlich Buchstaben und Ziffern. Prüfen Sie mit ... | wc -c; die Ausgabe muss 128 sein.

Eckdaten auf einen Blick

Parameter	Wert
Image Rails/Sidekiq	`chatwoot/chatwoot:v4.19.0` (stabiles Release, Oktober 2026)
Image PostgreSQL	`pgvector/pgvector:pg16` (offiziell, mit pgvector-Extension)
Image Redis	`redis:alpine`
Host-Port → Container	`3248:3000` (Rails Web-App; Reverse Proxy notwendig)
PostgreSQL / Redis	nur intern erreichbar (kein Port-Mapping nach außen)
Storage-Volume	`/volume1/docker/chatwoot/storage:/app/storage`
DB-Volume	`/volume1/docker/chatwoot/db:/var/lib/postgresql/data`
Redis-Volume	`/volume1/docker/chatwoot/redis:/data`
RAM-Bedarf gesamt	~1 GB (Rails 512 MB, Sidekiq 256 MB, PG 128 MB, Redis 30 MB)

Schritt 3: Compose-Datei erstellen und Stack starten

Öffnen Sie den Container Manager, wechseln Sie zu Projekt → Erstellen und legen Sie ein neues Projekt mit dem Namen chatwoot und dem Pfad /volume1/docker/chatwoot an. Fügen Sie folgende compose.yaml ein und ersetzen Sie alle Platzhalter:

HIEREIN128STELLIGENALPHANUMERISCHENSCHLUESSEL → Ihren generierten SECRET_KEY_BASE (identisch in Rails und Sidekiq!)
chatwoot.meinedomain.de → Ihre tatsächliche Domain (inkl. https://, ohne abschließenden Slash)
chatwootpass → Ihr gewähltes PostgreSQL-Passwort (an allen drei Stellen identisch)
REDIS_PASSWORT → Ihr gewähltes Redis-Passwort (an beiden Stellen identisch)

x-base: &base
  image: chatwoot/chatwoot:v4.19.0
  restart: always
  volumes:
    - /volume1/docker/chatwoot/storage:/app/storage

services:

  rails:
    <<: *base
    container_name: Chatwoot-RAILS
    hostname: rails
    depends_on:
      - postgres
      - redis
    ports:
      - "3248:3000"
    environment:
      - NODE_ENV=production
      - RAILS_ENV=production
      - INSTALLATION_ENV=docker
      - SECRET_KEY_BASE=HIEREIN128STELLIGENALPHANUMERISCHENSCHLUESSEL
      - FRONTEND_URL=https://chatwoot.meinedomain.de
      - DATABASE_URL=postgresql://chatwootuser:chatwootpass@chatwoot-db:5432/chatwoot_production
      - REDIS_URL=redis://:REDIS_PASSWORT@chatwoot-redis:6379
      - DEFAULT_LOCALE=de
      - MAILER_SENDER_EMAIL=noreply@meinedomain.de
      - SMTP_ADDRESS=smtp.example.com
      - SMTP_USERNAME=noreply@meinedomain.de
      - SMTP_PASSWORD=smtp-passwort
      - SMTP_TLS=true
      - ENABLE_ACCOUNT_SIGNUP=false
      - TZ=Europe/Berlin
    entrypoint: docker/entrypoints/rails.sh
    command: ["bundle", "exec", "rails", "s", "-p", "3000", "-b", "0.0.0.0"]

  sidekiq:
    <<: *base
    container_name: Chatwoot-SIDEKIQ
    hostname: sidekiq
    depends_on:
      - postgres
      - redis
    environment:
      - NODE_ENV=production
      - RAILS_ENV=production
      - INSTALLATION_ENV=docker
      - SECRET_KEY_BASE=HIEREIN128STELLIGENALPHANUMERISCHENSCHLUESSEL
      - FRONTEND_URL=https://chatwoot.meinedomain.de
      - DATABASE_URL=postgresql://chatwootuser:chatwootpass@chatwoot-db:5432/chatwoot_production
      - REDIS_URL=redis://:REDIS_PASSWORT@chatwoot-redis:6379
      - DEFAULT_LOCALE=de
      - MAILER_SENDER_EMAIL=noreply@meinedomain.de
      - SMTP_ADDRESS=smtp.example.com
      - SMTP_USERNAME=noreply@meinedomain.de
      - SMTP_PASSWORD=smtp-passwort
      - SMTP_TLS=true
      - TZ=Europe/Berlin
    command: ["bundle", "exec", "sidekiq", "-C", "config/sidekiq.yml"]

  postgres:
    image: pgvector/pgvector:pg16
    container_name: Chatwoot-DB
    hostname: chatwoot-db
    restart: always
    volumes:
      - /volume1/docker/chatwoot/db:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=chatwoot_production
      - POSTGRES_USER=chatwootuser
      - POSTGRES_PASSWORD=chatwootpass

  redis:
    image: redis:alpine
    container_name: Chatwoot-REDIS
    hostname: chatwoot-redis
    restart: always
    command: ["sh", "-c", "redis-server --requirepass \"REDIS_PASSWORT\""]
    volumes:
      - /volume1/docker/chatwoot/redis:/data

x-base ist ein gemeinsamer Einstellungsblock, kein Dienst. Rails und Sidekiq benötigen identische Geheimnisse, Datenbank- und Redis-Verbindungen. ENABLE_ACCOUNT_SIGNUP=false schließt die Selbstregistrierung. Verwenden Sie PostgreSQL mit pgvector, hier pgvector/pgvector:pg16; dem Standard-Image fehlt die Erweiterung.

Verifizieren: Starten Sie das Projekt im Container Manager. Nach etwa zwei Minuten laufen Datenbank und Redis dauerhaft, Chatwoot-RAILS und Chatwoot-SIDEKIQ starten bis zur Initialisierung immer wieder neu; in den Logs steht relation "installation_configs" does not exist. Das ist normal, der Init-Schritt folgt im nächsten Abschnitt.

Schritt 4: Datenbank initialisieren (db:chatwoot_prepare)

Initialisieren Sie die Datenbank per SSH in einem kurzlebigen Container nach der offiziellen Docker-Anleitung. Der Befehl legt Tabellen, pgvector und Seed-Daten an; ohne ihn starten Rails und Sidekiq nicht korrekt.

cd /volume1/docker/chatwoot
sudo docker compose run --rm rails bundle exec rails db:chatwoot_prepare

Das dauert beim ersten Mal ein bis zwei Minuten. Starten Sie danach Rails und Sidekiq neu:

sudo docker restart Chatwoot-RAILS Chatwoot-SIDEKIQ

Verifizieren: Alle vier Container laufen dauerhaft. Der Aufruf curl -s http://localhost:3248/api per SSH liefert die Version und "queue_services":"ok","data_services":"ok". Ein Aufruf von http://nas-ip:3248 im Browser (nur zur Überprüfung, noch per HTTP) sollte den Chatwoot-Onboarding-Assistenten oder den Login-Bildschirm laden.

Schritt 5: Reverse Proxy mit WebSocket-Unterstützung einrichten

Das Live-Chat-Widget benötigt WebSocket-Verbindungen für Echtzeit-Updates; ohne die entsprechenden HTTP-Header zeigt das Widget dauerhaft „Connecting…“. Richten Sie im DSM einen Reverse Proxy ein unter Systemsteuerung → Anmeldeportal → Erweitert → Reverseproxy:

Feld	Wert
Quellprotokoll	HTTPS
Quellhostname	`chatwoot.meinedomain.de`
Quellport	443
Zielprotokoll	HTTP
Zielhost	localhost
Zielport	3248

Unter Benutzerdefinierter Header → Erstellen → WebSocket ergänzt DSM die Upgrade-Header. Alternativ: Nginx Proxy Manager im Container Manager.

Öffnen Sie außerdem Port 443 in der DSM-Firewall, sofern noch nicht geschehen: DSM-Firewall auf dem Synology NAS: Ports für Docker-Container freigeben.

Verifizieren: Öffnen Sie https://chatwoot.meinedomain.de im Browser. Sie sehen den Onboarding-Assistenten oder den Login-Bildschirm mit gültigem HTTPS-Schloss. Prüfen Sie in den Browser-Entwicklertools (F12 → Netzwerk → WS), ob WebSocket-Verbindungen aufgebaut werden (Status 101 Switching Protocols).

Schritt 6: Onboarding und erste Inbox einrichten

Beim ersten Aufruf startet der Onboarding-Assistent automatisch und führt Sie durch: Account erstellen (Name, E-Mail, Passwort des ersten Admins), Account-Name des Unternehmens, erste Inbox anlegen. Wählen Sie für einen schnellen Test den Kanal „Website“ (Live-Chat-Widget). Nach Abschluss erhalten Sie ein JavaScript-Snippet; betten Sie es auf einer Test-HTML-Seite ein:

<script>
  (function(d,t) {
    var BASE_URL="https://chatwoot.meinedomain.de";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.chatwootSDK.run({
        websiteToken: 'IHR-TOKEN',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>

Verifizieren: Öffnen Sie Ihre Test-Seite im Browser. Das Chatwoot-Widget erscheint als Bubble rechts unten. Senden Sie eine Testnachricht; sie erscheint im Dashboard unter Konversationen als neue Anfrage. Das ist der Beweis, dass der gesamte Stack korrekt funktioniert: Rails verarbeitet die Anfrage, Sidekiq die Hintergrundprozesse, und WebSocket liefert die Echtzeit-Updates.

Schritt 7: E-Mail-Kanal konfigurieren (optional)

Für eingehende E-Mails richten Sie im Dashboard eine E-Mail-Inbox ein: Einstellungen → Inboxes → E-Mail-Postfach. Tragen Sie dort die IMAP-Zugangsdaten ein. Seit v4.18 lässt sich SMTP für den Versand unabhängig von IMAP konfigurieren. Alternativ nutzen Sie die von Chatwoot generierte Forward-Adresse: Eingehende E-Mails an Ihre Support-Adresse werden per Weiterleitung dorthin geleitet und tauchen automatisch als neue Konversationen auf.

Verifizieren: Senden Sie eine Test-E-Mail an die konfigurierte Inbox-Adresse. Nach wenigen Sekunden (Sidekiq verarbeitet die E-Mail im Hintergrund) erscheint sie als neue Konversation im Dashboard. Antworten Sie aus Chatwoot heraus und prüfen Sie, ob die Antwort beim Absender ankommt.

Upgrade-Prozess

Beim Upgrade auf eine neue Chatwoot-Version sichern Sie zuerst die Datenbank, passen dann den Image-Tag in der Compose-Datei an (im Container Manager: Projekt chatwoot anhalten, YAML bearbeiten, Projekt neu erstellen) und führen per SSH die Migrationen aus:

# vorher: Datenbank sichern
sudo docker exec Chatwoot-DB pg_dump -U chatwootuser chatwoot_production | gzip > /volume1/docker/chatwoot/backup_$(date +%Y%m%d).sql.gz

# nach dem Neuerstellen des Projekts mit dem neuen Tag:
cd /volume1/docker/chatwoot
sudo docker compose run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker restart Chatwoot-RAILS Chatwoot-SIDEKIQ

Der Befehl db:chatwoot_prepare ist idempotent: Er führt ausstehende Migrationen durch, ohne vorhandene Daten zu verlieren.

Von v4.18 auf v4.19

Für den Wechsel von v4.18.0 auf v4.19.0 ändern Sie nur den Image-Tag auf chatwoot/chatwoot:v4.19.0. Compose-Struktur und Umgebungsvariablen bleiben, neue Pflichtvariablen gibt es nicht. db:chatwoot_prepare führt 19 Migrationen aus und hebt das Schema auf die Version 20261019143116, darunter die neuen Tabellen für Conversation Monitors. Beachten Sie die Release Notes:

Captain V1 entfällt. Wer Captain mit V1-Anweisungen nutzt, überführt sie vor dem Update nach V2; die Konvertierungsaufgabe gibt es ab v4.16.0, sie muss noch auf einer Version mit V1 laufen. Installationen ohne V1-Anweisungen brauchen diesen Schritt nicht. Details: Hinweise des Projekts zur Abschaltung von Captain V1.
Bestehende API-Tokens funktionieren zusätzlich im Header Authorization: Bearer. Im Test antwortete /api/v1/profile mit diesem Header unter v4.18.0 mit 401, unter v4.19.0 mit 200.
Das Release enthält Sicherheitskorrekturen, das Projekt empfiehlt das Update ausdrücklich.

Im Test lief der Sprung von v4.18.0 auf v4.19.0 mit einem db:chatwoot_prepare-Lauf durch; Konto, Benutzer, Website-Inbox, Konversation und bestehende Anmeldungen blieben erhalten.

Von v4.14 auf v4.18

Der direkte Wechsel von v4.14.2 auf v4.18.0 übernimmt die Compose-Struktur. db:chatwoot_prepare führt alle ausstehenden Migrationen aus. Beachten Sie die Änderungen der Release Notes:

v4.16: Die Videoanruf-Integration wechselt von Dyte zu Cloudflare RealtimeKit. Wer Dyte nutzt, löscht die alte Integration und richtet sie mit Cloudflare-Account-ID, RealtimeKit-App-ID und API-Token neu ein.
v4.17: Chatwoot läuft auf Rails 7.2; Anpassungen am Image selbst sind dadurch eher betroffen als der Compose-Betrieb.
Compose-Datei: Wer den alten Dienst base übernommen hat, ersetzt ihn wie oben durch den Block x-base und entfernt die Zeile version: "3". Daten, Volumes und Umgebungsvariablen bleiben unverändert. Im Test lief der Sprung von v4.14.2 auf v4.18.0 mit einem einzigen db:chatwoot_prepare-Lauf durch; Benutzer und Konto blieben erhalten.
v4.18: SMTP lässt sich unabhängig von IMAP einrichten, außerdem enthält das Release Sicherheitskorrekturen, das Projekt empfiehlt das Update ausdrücklich.

Troubleshooting / Typische Fehler

relation does not exist / leere Seite nach Start: db:chatwoot_prepare wurde noch nicht ausgeführt (nach einem Update: Migrationen fehlen). Führen Sie den Befehl aus Schritt 4 aus und starten Sie den Rails-Container neu.
Live-Chat-Widget zeigt dauerhaft „Connecting…“: WebSocket-Header fehlen im Reverse Proxy. Öffnen Sie den Reverse-Proxy-Eintrag im DSM, gehen Sie zu „Benutzerdefinierter Header“ und aktivieren Sie die WebSocket-Option.
CORS-Fehler im Browser / Widget-Snippet mit falscher URL: FRONTEND_URL enthält einen abschließenden Slash oder nutzt HTTP statt HTTPS. Korrigieren Sie den Wert auf exakt https://chatwoot.meinedomain.de (ohne Slash), aktualisieren Sie beide Dienste und starten Sie neu.
FATAL: data directory has wrong ownership: Das Volume-Verzeichnis /volume1/docker/chatwoot/db existiert nicht oder hat falsche Berechtigungen. Legen Sie den Ordner manuell in der File Station an (Schritt 1) und starten Sie den Stack neu.
extension "vector" is not available bei db:chatwoot_prepare: Sie verwenden postgres:16 statt pgvector/pgvector:pg16. Ändern Sie das Image in der Compose-Datei; das Standard-Postgres-Image enthält die pgvector-Extension nicht.
NOAUTH Authentication required oder WRONGPASS invalid username-password pair or user is disabled (Redis-Fehler): Bei NOAUTH schickt Chatwoot kein Passwort mit, etwa weil es in REDIS_URL fehlt. WRONGPASS bedeutet, dass das Passwort nicht zu --requirepass im Redis-Dienst passt. Korrektes Format: redis://:PASSWORT@chatwoot-redis:6379 (Doppelpunkt vor dem Passwort nicht vergessen).

Häufige Fragen

Muss ich SECRET_KEY_BASE in Rails und Sidekiq wirklich doppelt eintragen?

Ja. Rails und Sidekiq teilen Sitzungs- und Verschlüsselungsgeheimnisse. Übernehmen Sie denselben Schlüssel in beide environment-Blöcke.

Wann und wie oft muss ich db:chatwoot_prepare ausführen?

Bei Erstinstallation und nach jedem Versionswechsel. Der Befehl führt ausstehende Migrationen aus und ist idempotent. Starten Sie anschließend Rails neu.

Kann ich Chatwoot ohne öffentliche Domain (nur im LAN) betreiben?

Grundsätzlich ja: Setzen Sie FRONTEND_URL=http://nas-ip:3248. Das Live-Chat-Widget funktioniert dann auf Seiten, die unter derselben IP laufen. Externe Kanal-Webhooks (WhatsApp, Facebook Messenger) benötigen jedoch eine öffentlich erreichbare HTTPS-URL; für diese Integrationen ist eine öffentliche Domain Pflicht.

Was unterscheidet Chatwoot von FreeScout und Mattermost?

FreeScout ist ein E-Mail-Helpdesk; Mattermost dient der internen Teamkommunikation. Chatwoot verbindet externe Kundenkanäle einschließlich Live-Chat.

Was ist der Unterschied zwischen latest, latest-ce und einem gepinnten Tag?

Verwenden Sie einen festen Tag wie v4.19.0 statt latest oder latest-ce. Prüfen Sie vor der Wahl einer Edition deren Funktionsumfang und Lizenzbedingungen.

Fazit

Für den Betrieb müssen SECRET_KEY_BASE, Datenbankinitialisierung und WebSocket-Proxy stimmen. Sichern Sie Datenbank und Uploads vor Updates. Selbsthosting allein gewährleistet keine DSGVO-Konformität; berücksichtigen Sie besonders die Datenübertragung an externe Kanalanbieter.

Weiterführende Anleitungen und Quellen

FreeScout auf dem Synology NAS installieren: Helpdesk-Postfach für Support-Teams: die Alternative für reinen E-Mail-Helpdesk ohne Live-Chat
Mattermost auf dem Synology NAS installieren: Team-Chat als Slack-Alternative: für interne Teamkommunikation neben dem Kundensupport
Nginx Proxy Manager auf der Synology mit Container Manager einrichten: Reverse Proxy mit Let's Encrypt als Alternative zum DSM-Reverse-Proxy
Portainer auf Synology NAS installieren: Container-Verwaltung mit erweiterter Web-Oberfläche

Offizielle Quellen: Chatwoot Docker-Deployment-Dokumentation (developers.chatwoot.com) und Environment-Variables-Referenz; beide bilden die fachliche Grundlage dieser Anleitung. Das Chatwoot GitHub-Repository enthält die aktuelle docker-compose.production.yaml als offizielle Compose-Referenz. Die Änderungen der aktuellen Version beschreiben die Release Notes zu Chatwoot v4.19.0.