Self-Hosting

Self-Hosting erfordert zwei Dateien (docker-compose.yml und .env) plus docker compose up -d. Beide Dateien liegen im Customermates-Repo und Sie holen sie mit curl. Ein git clone und ein Build-Schritt sind nicht nötig. Das veröffentlichte Image unter ghcr.io/customermates/customermates:latest wendet die Datenbank-Migrationen beim ersten Boot an.

Self-Host vs Cloud

Beide betreiben dieselbe Kernanwendung. Der Self-Host-Build entspricht dem Starter-Funktionsumfang: das volle Kern-CRM inklusive Audit-Logging. Das gemeinsame Postfach, Kalender-Sync, Enterprise-SSO und White-Labeling sind Enterprise-Edition-Features (die ee/-Komponenten); in der Cloud sind Postfach und Kalender-Sync Teil des Pro-Tarifs, SSO und White-Label Teil des Enterprise-Tarifs. Für ein Self-Hosted-Deployment mit diesen Features kontaktieren Sie uns für eine Enterprise-Edition-Vereinbarung. Anmeldung per Google- und Microsoft-OAuth funktioniert in beiden Varianten, sobald Sie die Provider-Env-Vars setzen; ohne sie melden sich Self-Hosted-Installationen per E-Mail an.

Datenhoheit: Die Cloud speichert Daten in unserer EU-Region, DSGVO-konform, mit üblicher Verschlüsselung at-rest und in-transit. Wenn Ihre Compliance verlangt, dass Daten auf Ihrer Infra liegen: Self-Host.

Kostenform: Cloud ist pro Nutzer über Tarife bepreist, ab 12 €/Nutzer/Monat, und skaliert mit Ihrem Messaging-Umfang. Self-Host ist kostenlos für die Kernanwendung plus was Sie für Infrastruktur zahlen (ein kleiner VPS trägt Hunderte User). Für ein kleines Team ist Cloud oft günstiger, wenn Sie die Zeit fürs eigene Postgres-Backup einrechnen. Für ein größeres Team ist Self-Host meist die günstigere Variante.

Sie können zwischen beiden wechseln: Export von einem, Import ins andere. Das Datenmodell ist identisch.

Installation

Voraussetzungen

• Docker und Docker Compose v2.
• Domain-Name, falls Sie TLS wollen (lokal nicht nötig).
• ~2 GB RAM und ein paar GB Disk pro tausend Records.

1. Verzeichnis anlegen und beide Config-Dateien holen

mkdir customermates && cd customermates
curl -fsSL https://raw.githubusercontent.com/customermates/customermates/main/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/customermates/customermates/main/.env.selfhost.template -o .env

Anschließend .env mit echten Werten editieren:

• BETTER_AUTH_SECRET: langer Zufallsstring (openssl rand -hex 32).
• POSTGRES_PASSWORD: default ändern.
• BASE_URL: Ihre Public-URL (z.B. https://crm.example.com). Lokal default http://localhost:4000.
• RESEND_API_KEY und RESEND_OPERATOR_EMAIL: ein kostenloses Resend-Projekt. Nötig für Signup-Verifizierung, Passwort-Reset und Einladungs-Mails.

2. Starten

docker compose up -d

First-Boot dauert eine Minute, während Prisma-Migrationen laufen. Logs ansehen:

docker compose logs -f app

Wenn die App ready ist, http://localhost:4000 öffnen (oder Ihr eigenes APP_PORT).

3. Erster Account

URL öffnen. Mit E-Mail registrieren, Verifizierungs-Link aus dem Postfach klicken, dann Workspace-Namen wählen. Weitere User und Rollen verwalten über Unternehmen → Benutzer und Unternehmen → Rollen.

4. Reverse-Proxy und TLS

Reverse-Proxy (Caddy, nginx, Traefik) auf den App-Port zeigen (4000 by default, oder Ihr eigenes APP_PORT). Caddy:

crm.example.com {
  reverse_proxy localhost:4000
}

Customermates setzt Secure-Cookies, wenn BASE_URL mit https:// startet. Der Proxy muss X-Forwarded-Proto korrekt weiterreichen.

5. API-Key anlegen

Profil → API Keys → Neuer Key. Genau wie in der Cloud. Siehe API-Keys.

Tagesbetrieb

Update

docker compose pull
docker compose up -d

Pullt das neueste App-Image und startet die betroffenen Services neu. Migrationen laufen beim Container-Boot automatisch. Status mit docker compose ps prüfen.

Neu starten

docker compose restart

Startet den Stack ohne neues Image-Pull neu. Nach .env-Änderungen.

Logs und Troubleshooting

docker compose logs -f app
docker compose logs -f postgres
docker compose ps
docker compose exec app sh

Hintergrund-Jobs (Webhook-Auslieferungen, Inbox-Sync und Nachrichten-Backfill) laufen prozessintern über einen eingebetteten, Postgres-gestützten Worker, der mit der App startet. Es gibt keinen externen Job-Dienst zu konfigurieren. Den Fortschritt sehen Sie in den App-Logs (docker compose logs -f app).

Alle Daten zurücksetzen

docker compose down -v
docker compose up -d

-v löscht das Postgres-Volume. IRREVERSIBLE. Vorher Backup ziehen, falls die Daten benötigt werden.

Backups

Postgres per pg_dump auf Zeitplan. Der App-Container ist stateless.

docker compose exec -T postgres pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" \
  | gzip > /var/backups/customermates-$(date +%Y%m%d).sql.gz

Für Produktion:

• Tägliche Dumps auf separates Volume oder Off-Site.
• Restore-Prozeduren in einer Nicht-Produktion testen.
• .env und Secrets nicht ins Source-Repo.

Enterprise-Features

Das gemeinsame Postfach, Kalender-Sync, Enterprise-SSO und White-Labeling sind Enterprise-Edition-Features (die ee/-Komponenten). In der Cloud sind sie Teil der Tarife: Postfach und Kalender ab Pro, SSO und White-Label im Enterprise-Tarif. Der kostenlose Community-Self-Host-Build enthält sie nicht; Audit-Logging gehört zu jedem Deployment, auch self-hosted. Wenn Sie diese Features auf eigener Infrastruktur benötigen, kontaktieren Sie uns für eine Enterprise-Edition-Vereinbarung. Anmeldung per Google- und Microsoft-OAuth gehört zum Core und funktioniert self-hosted, sobald Sie die Provider-Env-Vars setzen.

Weiter

• Architektur und Sicherheit: was Sie betreiben.
• API-Keys: Key-Hygiene.
• KI verbinden: nach dem Install einen MCP-Client auf Ihre Instanz zeigen.