Einstieg

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

Self-Hosting verwendet die Starter-Berechtigungen. Enthalten sind die Kern-CRM-Datensätze und Ansichten sowie REST, Webhooks und MCP für einen externen KI-Client, den Sie auswählen und bezahlen. Verbundene Messaging-Konten, einheitlicher Posteingang, verbundene Kalenderansicht, gehostetes Mate und gehostete KI-Credits sind nicht enthalten. Ein anderer bezahlter Cloud-Tarif erweitert die Self-Hosted-Berechtigungen nicht.

Beim Self-Hosting wählen Sie, wo Anwendung und Datenbank laufen. Daraus entsteht nicht automatisch eine Garantie für Sicherheit, Compliance, Datenschutz oder einen isolierten Betrieb. Ihr Unternehmen bleibt für Konfiguration, Anbieter, Verträge, Aufbewahrung und Betriebskontrollen verantwortlich.

Vergleichen Sie die gesamten Betriebskosten, statt pauschal von einem günstigeren Modell auszugehen. Berücksichtigen Sie Infrastruktur, Backups, Wiederherstellungstests, Monitoring, Updates, Störungsbehandlung und externe Anbieter ebenso wie Abonnementpreise.

Customermates exportiert und importiert CRM-Datensätze als Excel-Arbeitsmappen, jeweils für einen Datensatztyp, sodass sich ein Arbeitsbestand zwischen Systemen bewegen lässt. Ein vollständiger Plattformwechsel bleibt ein separat entworfenes und geprüftes Projekt.

Installation

Voraussetzungen

• Docker und Docker Compose v2.
• Domain-Name, falls Sie TLS wollen (lokal nicht nötig).

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 konfiguriertes 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.

Konfigurationsänderungen anwenden

docker compose up -d

Gleicht den Stack ab und erstellt betroffene Container neu, wenn sich die Konfiguration geändert hat. Verwenden Sie den Befehl nach .env-Änderungen. Für einen einfachen Neustart bei unveränderter Konfiguration genügt docker compose restart.

Logs und Troubleshooting

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

Aktivierte Hintergrund-Jobs laufen prozessintern über den Postgres-gestützten Worker, der mit der Anwendung startet. Die Compose-Datei enthält keinen separaten Worker-Dienst. Prüfen Sie die Anwendungs-Logs mit 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.

mkdir -p backups
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' \
  | gzip > 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.

Editionsgrenze

Jedes Self-Hosted-Deployment nutzt Starter-Berechtigungen. Verbundene Messaging-Konten, einheitlicher Posteingang, verbundene Kalenderansicht, gehostetes Mate und gehostete KI-Credits bleiben Cloud-Funktionen und werden beim Self-Hosting nicht durch einen bezahlten Cloud-Tarif freigeschaltet. Externe KI-Clients bleiben über MCP verfügbar. Die genaue Lizenzgrenze des Codes steht in LICENSE und ee/LICENSE.md im Repository.

Der gehostete In-App-Assistent ist nur in der Cloud verfügbar und bleibt freigabegebunden. Externes MCP nutzt Ihren eigenen KI-Anbieter. Enterprise-SSO und White-Labeling sind in keiner Variante implementiert.

Weiter

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