Self-Hosted Installationsanleitung

Voraussetzungen

1. Entpacken und laden

tar xzf maildesk-selfhosted.tar.gz
cd maildesk

docker load < maildesk-images.tar.gz

2. Umgebung konfigurieren

./setup.sh

Führe ./setup.sh aus, um alle Secrets automatisch zu generieren. Dann editiere .env und setze deine APP_URL und den Lizenzschlüssel.

Öffne .env und setze folgende Werte:

Erforderliche Variablen

Auto-generiert durch setup.sh

Diese werden automatisch beim Ausführen von setup.sh generiert. Nicht ändern, außer bei Datenmigration.

Optionale Variablen

Beispiel .env für Self-Hosted

# Only these 2 lines need manual editing after running ./setup.sh:
APP_URL=https://tickets.example.com
MAILDESK_LICENSE_KEY=eyJhbGciOiJFZERTQSIs...your-key-here

# Everything else is auto-generated by ./setup.sh

3. Starten

docker compose up -d

Dies startet 6 Services:

Der migrate-Service läuft automatisch bevor App und Worker starten. Er erstellt alle Tabellen idempotent — sicher für neue und bestehende Datenbanken.

4. Deployment verifizieren

# Check all services are healthy
docker compose ps

# Check app logs
docker compose logs app

# Check worker logs
docker compose logs worker

# Health check endpoint
curl http://localhost:3000/api/health

Sobald alles healthy ist, öffne deine APP_URL im Browser. Du solltest die Login-/Registrierungsseite sehen.

5. Ersteinrichtung

1. 1Registriere das erste Admin-Konto unter deine-domain.de/register
2. 2Erstelle eine Organisation — das ist dein Workspace
3. 3Füge eine Mailbox unter Einstellungen > Mailboxen hinzu (IMAP/SMTP-Zugangsdaten)
4. 4Eingehende E-Mails erstellen automatisch Tickets

E-Mail-Verifizierung (Optional)

Konfiguriere SMTP, um E-Mail-Verifizierung für neue Benutzer zu aktivieren. Ohne SMTP werden neue Benutzer automatisch verifiziert und können sich sofort anmelden.

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=MailDesk <noreply@yourdomain.com>

Reverse Proxy einrichten

MailDesk benötigt einen Reverse Proxy für TLS-Terminierung. Hier sind Beispiele für gängige Setups:

tickets.example.com {
    handle /ws* {
        reverse_proxy localhost:3002
    }
    handle {
        reverse_proxy localhost:3000
    }
}

Lizenzschlüssel

Dein Lizenzschlüssel ist ein Ed25519-signiertes JWT, das deinen Plan, Limits und Feature-Flags enthält.

Was der Schlüssel steuert:

• Plan-Stufe (Free, Pro, Business)
• Limits: max. Agenten, Mailboxen, Tickets/Monat, Speicher
• Features: KI-Antworten, Wissensdatenbank, Auto-Übersetzung

Validierung:

• Der Schlüssel wird standardmäßig offline mit dem eingebetteten Ed25519 Public Key validiert — keine externen Aufrufe nötig
• Wenn MAILDESK_LICENSE_SERVER_URL gesetzt ist, verifiziert MailDesk den Schlüssel regelmäßig online (optional)
• Validierte Lizenzdaten werden 24 Stunden in Redis gecacht
• Bei Redis-Ausfall wird das JWT direkt verifiziert (Ed25519 braucht keinen Server)

Abgelaufener oder ungültiger Schlüssel:

• Die App wechselt in den Nur-Lesen-Modus — bestehende Daten bleiben zugänglich
• Ticket-Erstellung, Antworten senden und KI-Features sind deaktiviert
• Ein Banner zeigt "Lizenz abgelaufen" mit einem Verlängerungslink

Aktualisierung

# Load new images
docker load < maildesk-images.tar.gz

# Restart (migrations run automatically)
docker compose up -d

Migrationen laufen automatisch bei jedem Start — kein manueller Migrationsschritt nötig.

Backup & Wiederherstellung

Backup

docker compose exec postgres pg_dump -U maildesk maildesk > backup_$(date +%Y%m%d).sql

docker compose cp worker:/data/attachments ./attachments-backup

docker compose exec redis redis-cli BGSAVE

Wiederherstellung

docker compose exec -T postgres psql -U maildesk maildesk < backup_20260317.sql

docker compose cp ./attachments-backup/. worker:/data/attachments

Fehlerbehebung

docker compose logs app
docker compose logs migrate

docker compose logs app | grep -i license

docker compose logs clamav

docker compose logs worker

Architekturübersicht

        ┌─────────────┐
        │  Reverse    │
        │  Proxy      │
        │  (TLS)      │
        └──────┬──────┘
               │ :3000
        ┌──────▼──────┐
        │    App      │
        │  (Next.js)  │
        └──┬──────┬───┘
           │      │
  ┌────────▼─┐  ┌─▼────────┐
  │ Postgres │  │  Redis   │
  │ (pgvec)  │  │ (queue)  │
  └────────▲─┘  └─▲────────┘
           │      │
        ┌──┴──────┴───┐
        │   Worker    │
        │ (IMAP/SMTP) │
        └──────┬──────┘
               │
        ┌──────▼──────┐
        │   ClamAV    │
        │ (antivirus) │
        └─────────────┘

• App — App stellt die Web-UI und API-Routen bereit
• Worker — Worker verbindet sich per IMAP mit Mailboxen, sendet Antworten per SMTP, verarbeitet Hintergrund-Jobs
• Postgres — Postgres speichert alle Anwendungsdaten (mit pgvector für KI-Embeddings)
• Redis — Redis verwaltet Job-Queues (BullMQ) und Echtzeit-Pub/Sub (WebSocket)
• ClamAV — ClamAV scannt E-Mail-Anhänge auf Malware