Monica CRM mit Docker installieren: Persönliches CRM zum Verwalten von Kontakten

Monica ist ein quelloffenes persönliches CRM (Personal Relationship Management) auf Basis von Laravel/PHP. Sie verwalten damit Freunde, Familie und Geschäftskontakte samt Gesprächshistorie, Geburtstagen, Erinnerungen und Notizen. Anders als klassische Vertriebs-CRMs ist Monica auf Einzelpersonen und kleine Teams ausgelegt. Das offizielle Docker-Image läuft auf jedem Linux-Host, NAS oder VPS; diese Anleitung wurde mit Monica 4.1.2 und MariaDB 11 getestet.

Voraussetzungen

1. Docker Engine >= 20.10 und Docker Compose Plugin >= 2.0 (docker compose ohne Bindestrich) auf dem Host installiert – falls noch nicht vorhanden, siehe Docker und Docker Compose auf Linux installieren
2. Linux-Host, VM oder NAS mit Docker-Unterstützung (Ubuntu, Debian, Raspberry Pi OS, Synology DSM 7 usw.)
3. 1 CPU-Kern, mindestens 1 GB RAM frei (im Test belegten App und Datenbank zusammen rund 215 MB), etwa 2 GB Speicherplatz für Images und Daten; x86_64 oder arm64
4. openssl auf dem Host für die APP_KEY-Generierung (auf nahezu allen Linux-Systemen vorinstalliert)
5. Optional: Reverse Proxy für HTTPS-Terminierung, wenn Monica öffentlich erreichbar sein soll – siehe Caddy als Reverse Proxy mit automatischem HTTPS

Eckdaten im Überblick

Schritt 1: Projektordner anlegen

Legen Sie einen eigenen Ordner für Monica an. Alle folgenden Befehle führen Sie in diesem Verzeichnis aus:

mkdir -p /opt/monica
cd /opt/monica

Ohne root-Zugriff verwenden Sie ~/monica. compose.yaml und .env müssen im selben Verzeichnis liegen.

Verifizieren: ls /opt/monica gibt das (zunächst leere) Verzeichnis zurück – kein Fehler bedeutet korrekt angelegt.

Schritt 2: APP_KEY generieren und .env anlegen

Monica (Laravel) braucht einen 32-Byte-Schlüssel als APP_KEY. Erzeugen Sie ihn einmalig auf dem Host:

echo -n 'base64:'; openssl rand -base64 32

Beispielausgabe:

base64:AbCdEfGhIjKlMnOpQrStUvWxYz1234567890ab==

Wählen Sie außerdem ein sicheres Datenbankpasswort (mindestens 20 zufällige Zeichen, zum Beispiel mit openssl rand -hex 20) und erstellen Sie die .env-Datei:

# Monica CRM – Umgebungsvariablen
# APP_KEY: einmalig generiert, NIEMALS nach dem ersten Start ändern
APP_KEY=base64:AbCdEfGhIjKlMnOpQrStUvWxYz1234567890ab==

# URL der Instanz – exakt so wie im Browser aufgerufen (inkl. Port)
APP_URL=http://localhost:8080

# Datenbankpasswort – gleiches Passwort in beiden Variablen
DB_PASSWORD=SICHERES_PASSWORT_HIER_EINSETZEN

# Nach dem Anlegen des ersten Accounts auf true setzen:
APP_DISABLE_SIGNUP=false

# local = Betrieb per HTTP im LAN; production nur hinter HTTPS-Proxy (Schritt 7)
APP_ENV=local

Schützen Sie die Datei:

chmod 600 /opt/monica/.env

Verifizieren: cat /opt/monica/.env zeigt die fünf Variablen mit Ihren Werten. Der APP_KEY beginnt exakt mit base64:, gefolgt von einem Base64-String – kein Leerzeichen, keine Anführungszeichen.

Schritt 3: compose.yaml erstellen

Für eine Erklärung der Compose-Syntax und des Volume-Konzepts siehe Docker-Netzwerke und Volumes richtig nutzen. Erstellen Sie die Datei /opt/monica/compose.yaml:

services:
  app:
    image: monica:4.1.2-apache
    container_name: monica_app
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:80"
    environment:
      - APP_KEY=${APP_KEY}
      - APP_ENV=${APP_ENV:-production}
      - APP_DEBUG=false
      - APP_URL=${APP_URL:-http://localhost:8080}
      - DB_HOST=db
      - DB_PORT=3306
      - DB_DATABASE=monica
      - DB_USERNAME=monica
      - DB_PASSWORD=${DB_PASSWORD}
      - APP_DISABLE_SIGNUP=${APP_DISABLE_SIGNUP:-false}
    volumes:
      - monica_data:/var/www/html/storage
    restart: unless-stopped

  db:
    image: mariadb:11
    container_name: monica_db
    environment:
      - MYSQL_RANDOM_ROOT_PASSWORD=true
      - MYSQL_DATABASE=monica
      - MYSQL_USER=monica
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - monica_mysql:/var/lib/mysql
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  monica_data:
    name: monica_data
  monica_mysql:
    name: monica_mysql

depends_on mit condition: service_healthy startet Monica erst, wenn MariaDB bereit ist. Ohne das Volume monica_data gehen Uploads, Sessions und Logs bei jedem Neuaufbau verloren. MYSQL_RANDOM_ROOT_PASSWORD=true verhindert ein bekanntes root-Passwort in der Datenbank. APP_ENV kommt aus der .env: Mit production erzeugt Monica ausschließlich HTTPS-Links. Im Test leitete die Startseite per HTTP dann auf https://…/register um, auch Stylesheets zeigten auf HTTPS; ohne Proxy ist die Oberfläche so nicht bedienbar.

Verifizieren: Syntaxcheck mit docker compose config im Projektverzeichnis – der Befehl gibt die interpolierte Compose-Konfiguration ohne Fehlermeldung aus.

Schritt 4: Container starten

Starten Sie beide Container im Hintergrund:

docker compose up -d

Docker lädt zunächst die Images herunter (monica:4.1.2-apache ca. 600 MB, mariadb:11 ca. 400 MB). Der App-Container wartet auf den Healthcheck der Datenbank und führt beim Start die Migrationen aus. Im Test endete das Log nach etwa einer Minute mit Monica v4.1.2 is set up, enjoy.

Verifizieren:

docker compose ps

Erwartete Ausgabe nach 30–60 Sekunden:

NAME          IMAGE                  STATUS
monica_db     mariadb:11             Up X seconds (healthy)
monica_app    monica:4.1.2-apache    Up X seconds

Beide Container zeigen Up, monica_db zusätzlich (healthy). Bei Restarting prüfen Sie die Logs:

docker compose logs app
docker compose logs db

Schritt 5: Datenbank initialisieren (setup:production)

Das Einstiegsskript des Images legt die Tabellen beim Start bereits an (monica:update). Die offizielle Image-Beschreibung sieht zusätzlich einmalig setup:production vor; der Befehl prüft die Installation und baut die Caches neu auf. Er fragt vorher interaktiv nach einer Bestätigung, die Sie mit yes beantworten:

docker compose exec app php artisan setup:production

In Skripten ohne Terminal ergänzen Sie --force. Mit --email und --password legt der Befehl gleich den ersten Account an.

Verifizieren:

docker compose logs app --tail=20

Das Log enthält keine ERROR- oder SQLSTATE-Einträge. Dann prüfen Sie per curl:

curl -I http://localhost:8080

Erwartet: HTTP/1.1 302 Found (Weiterleitung auf die Login-Seite) oder HTTP/1.1 200 OK.

Schritt 6: Ersten Account anlegen und Registrierung sperren

Öffnen Sie http://localhost:8080 im Browser. Monica zeigt die Registrierungsseite. Legen Sie Ihren ersten Account mit E-Mail-Adresse und Passwort an.

Sperren Sie danach neue Registrierungen, sonst kann sich jede Person mit Zugang zur URL registrieren. Setzen Sie in /opt/monica/.env:

APP_DISABLE_SIGNUP=true

Übernehmen Sie die Änderung; Compose erstellt den App-Container dabei neu:

docker compose up -d

Verifizieren: curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/register liefert 403. Die Sperre greift erst, wenn mindestens ein Account existiert; vorher bleibt die Registrierung für den ersten Account offen.

Schritt 7: Reverse Proxy und HTTPS einrichten (für öffentlichen Zugriff)

Für den Betrieb im lokalen Netz reicht HTTP auf Port 8080 mit APP_ENV=local. Sobald Monica von außen erreichbar sein soll, ist HTTPS Pflicht. Setzen Sie dann APP_ENV=production; Monica erzeugt damit nur noch HTTPS-Links.

Geeignete Optionen: Traefik als Docker-Reverse-Proxy mit automatischem HTTPS oder Caddy. Passe anschließend in der .env die URL an:

APP_URL=https://monica.example.com

Dann neu starten:

docker compose up -d

Port 8080 geben Sie dann nicht mehr öffentlich frei, der Proxy übernimmt Port 443. Binden Sie ihn am besten nur an 127.0.0.1 ("127.0.0.1:8080:80").

Verifizieren: curl -I https://monica.example.com gibt HTTP/2 200 oder 302 zurück. Im Browser erscheint das Schloss-Symbol.

Schritt 8: Optionale Erweiterungen

Optionale Funktionen aktivieren Sie über Umgebungsvariablen:

Für Redis als optionalen Cache ergänzen Sie den Compose-Stack um einen Redis-Dienst und setze zusätzlich REDIS_HOST=redis, CACHE_DRIVER=redis und QUEUE_CONNECTION=redis in der .env und reichen die Variablen im environment-Block des Dienstes app durch.

Verifizieren: docker compose exec app printenv | grep -E 'MFA|DAV|MAIL|REDIS' zeigt die gesetzten Werte, und docker compose logs app --tail=20 enthält keine Verbindungsfehler zu SMTP oder Redis.

Updates durchführen

Updates laufen über Docker Compose:

cd /opt/monica
docker compose pull
docker compose up -d
docker compose exec app php artisan setup:production

Neue Migrationen spielt der Container beim Start selbst ein; setup:production prüft danach die Installation. Für Update-Benachrichtigungen eignet sich Diun oder WUD, ohne automatisch zu aktualisieren.

Verifizieren: docker compose ps zeigt die aktualisierten Images; im Monica-UI unter „Einstellungen → Über Monica“ steht die neue Versionsnummer.

Backup

Die Daten liegen in zwei Volumes:

1. monica_data: Uploads, Logs, Sessions (/var/www/html/storage)
2. monica_mysql: Alle Datenbankdaten (/var/lib/mysql)

Für ein konsistentes Datenbank-Backup erstellen Sie einen Dump mit mariadb-dump (das Image mariadb:11 enthält kein mysqldump mehr). Das Passwort liest der Befehl aus der Umgebung des Containers:

docker compose exec -T db sh -c 'mariadb-dump -u monica -p"$MYSQL_PASSWORD" monica' > monica_backup_$(date +%Y%m%d).sql

Den SQL-Dump kombinieren Sie am besten mit einer Volume-Sicherung über Restic. Das Volume monica_data liegt unter /var/lib/docker/volumes/monica_data/_data.

Troubleshooting / Typische Fehler

1. „No application encryption key has been specified“: Der APP_KEY ist leer oder falsch formatiert. Er beginnt mit base64:, gefolgt von 44 Base64-Zeichen ohne Anführungszeichen und Leerzeichen.
2. Weiße Seite oder Datenbankfehler beim ersten Aufruf: Die Migrationen beim Start sind noch nicht fertig oder schlugen fehl. Prüfen Sie docker compose logs app auf is set up, enjoy und führen Sie bei Fehlern docker compose exec app php artisan setup:production aus.
3. monica_app startet, monica_db zeigt „Restarting“: MariaDB konnte sich nicht initialisieren. Häufig fehlt DB_PASSWORD in der .env; prüfen Sie docker compose logs db.
4. Weiterleitung auf https:// oder Seite ohne Layout bei HTTP-Zugriff: APP_ENV=production erzwingt HTTPS-Links. Ohne Reverse Proxy mit TLS setzen Sie für rein lokale Nutzung APP_ENV=local in der .env und führen docker compose up -d aus.
5. APP_URL stimmt nicht überein: Links und OAuth-Weiterleitungen scheitern, wenn APP_URL nicht exakt der aufgerufenen URL samt Port entspricht; hinter einem Proxy gilt die externe HTTPS-URL.
6. Altes Image monicahq/monicahq verwendet: veraltet, ohne Sicherheitsupdates. Wechseln Sie auf monica:4.1.2-apache.
7. Registrierung nach Update wieder offen: APP_DISABLE_SIGNUP=true muss dauerhaft in der .env stehen.

Häufige Fragen

Wie generiere ich den APP_KEY korrekt?

Auf dem Host ausführen: echo -n 'base64:'; openssl rand -base64 32. Tragen Sie die komplette Ausgabe inklusive base64: als APP_KEY in die .env ein. Ändern Sie den Schlüssel danach nicht mehr, sonst sind verschlüsselte Daten unlesbar.

Welche Datenbank wird unterstützt?

Monica unterstützt nur MySQL und MariaDB, weder PostgreSQL noch SQLite. Das offizielle Beispiel nutzt mariadb:11; das in älteren Anleitungen genannte mysql:5.7 ist End-of-Life.

Was macht php artisan setup:production genau?

Der Befehl führt ausstehende Migrationen aus, baut Config- und Route-Cache neu und prüft die Systemvoraussetzungen. Da das Docker-Image die Migrationen beim Start selbst ausführt, dient er im Container vor allem als Prüfung und zum Anlegen des ersten Accounts (--email, --password).

Kann ich Monica hinter Traefik oder Caddy betreiben?

Ja, für öffentlich erreichbaren Betrieb ist das der empfohlene Weg. Setzen Sie APP_URL auf die externe HTTPS-URL (z. B. https://monica.example.com) und APP_ENV=production. Öffentlich erreichbar ist dann nur der Proxy auf Port 443.

Gibt es bereits eine stabile Version 5?

Nein. Monica v5 (intern „Chandler“) ist Stand September 2026 weiterhin Beta, das offizielle Image steht als monica:5.0.0-beta.5-apache auf Docker Hub. Für den produktiven Einsatz verwenden Sie die stabile 4.x-Reihe (monica:4.1.2-apache). v5 ist keine Aktualisierung von v4, sondern eine Neuentwicklung mit eigenem Datenmodell.

Unterstützt Monica CardDAV/CalDAV-Synchronisation?

Ja. Mit DAV_ENABLED=true aktivieren Sie WebDAV und synchronisieren Kontakte und Kalendereinträge mit kompatiblen Apps (z. B. macOS Kontakte, Thunderbird, DAVx⁵ auf Android). Reichen Sie die Variable in der compose.yaml durch und führen Sie docker compose up -d aus.

Fazit

Monica CRM verwaltet Kontakte, Gespräche und persönliche Ereignisse ohne Cloud-Abhängigkeit. Der Docker-Betrieb ist offiziell unterstützt und in etwa 20 Minuten eingerichtet. Die wichtigsten Fallstricke sind der APP_KEY (Format base64:…), das zum Zugriff passende APP_ENV (HTTP im LAN: local, hinter HTTPS: production) und die korrekte APP_URL.

Monica v5 (Chandler) ist noch Beta; aktuelle Informationen finden Sie im GitHub-Repository. Für den produktiven Einsatz bleibt die 4.x-Reihe die zuverlässige Wahl.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren (Ubuntu/Debian)
2. Docker-Netzwerke und Volumes richtig nutzen
3. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS
4. Restic Backup auf Linux einrichten und automatisieren
5. Docker-Container automatisch aktualisieren: Diun, WUD und Renovate
6. Firefly III mit Docker installieren: Self-Hosted-Finanzverwaltung

Offizielle Quellen: Monica auf Docker Hub, Monica GitHub, Monica Docker-Dokumentation.

Passende Anleitungen auf S-EDV

1. Automatische Sicherheitsupdates unter Debian/Ubuntu mit unattended-upgrades rich
2. Twenty CRM mit Docker installieren: Open-Source-CRM für Vertrieb und Kundenpflege
3. netcup Local Block Storage bestellen, einrichten und unter Linux einbinden