Dokumentation

Installation

Diese Seite führt von der heruntergeladenen Datei bis zum laufenden Dienst. Danach geht es weiter mit Erste Schritte.

Rechnen Sie mit einer halben Stunde, wenn Datenbank und DNS schon stehen.

Bevor Sie anfangen

Die Datenbank muss laufen, bevor der Dienst startet. Das Installationsskript richtet sie bewusst nicht ein — es weiß nicht, ob Sie eine eigene Instanz betreiben, und es rät nicht an Ihren Daten herum.

1. Paket prüfen

Zu jedem Paket steht auf der Download-Seite eine Prüfsumme. Rechnen Sie sie nach, bevor Sie etwas auspacken:

shasum -a 256 annexgroup-<fassung>-<plattform>.tar.gz

Stimmt sie nicht mit der angegebenen überein, brechen Sie ab und laden Sie erneut. Danach auspacken:

tar xzf annexgroup-<fassung>-<plattform>.tar.gz
cd annexgroup-<fassung>-<plattform>

Im Paket liegen: das Programm als eine einzige Datei, eine Beispielkonfiguration, die Dienstdefinition und ein Skript, das beides kann — installieren und, mit --uninstall, wieder entfernen.

2. Installieren

Linux:

sudo ./install-linux.sh

macOS:

sudo ./install-macos.sh

macOS 14 oder neuer ist Voraussetzung. Auf einem älteren System bricht der Installer ab, bevor er etwas ablegt, und nennt die Ursache: „AnnexGroup braucht macOS 14 oder neuer; dieser Mac hat macOS …". Geprüft ist die Installation auf Apple Silicon; das Intel-Paket ist gebaut, notarisiert und unter Rosetta gelaufen, an einem Intel-Mac mit macOS 14 aber noch nicht gemessen.

Das Skript legt den Dienstbenutzer, die Verzeichnisse und den Systemdienst an und startet den Dienst absichtlich noch nicht. Es endet mit den Schritten, die jetzt folgen — dieselben wie hier.

Wohin es schreibt:

Eine bereits vorhandene config.yaml wird nicht überschrieben.

3. Datenbank anlegen

mariadb -e "CREATE DATABASE annexgroup CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mariadb -e "CREATE USER 'annexgroup'@'localhost' IDENTIFIED BY '<passwort>';"
mariadb -e "GRANT ALL ON annexgroup.* TO 'annexgroup'@'localhost';"

utf8mb4 ist keine Empfehlung, sondern Voraussetzung: Ohne sie brechen Umlaute, Emoji und viele Anhangsnamen.

4. Konfiguration anpassen

In der config.yaml sind zwei Angaben nötig, alles andere hat brauchbare Vorgaben:

domain: ihre-domain.de
database_dsn: "annexgroup:<passwort>@tcp(127.0.0.1:3306)/annexgroup?parseTime=true&loc=UTC"

Hinter einem Vorschaltrechner (nginx und ähnliche): Tragen Sie ihn unter trusted_proxies ein, sonst gelten Anmeldesperre, Sperrliste und Protokoll immer als von ihm kommend:

trusted_proxies:
  - 192.168.1.5      # die Adresse des nginx, der auf diesen Server weiterleitet
  - 10.0.0.0/24      # oder ein Netz, aus dem nur Vorschaltrechner kommen

5. Dienst starten

Linux:

sudo systemctl enable --now annexgroup
systemctl status annexgroup

macOS:

sudo launchctl bootstrap system /Library/LaunchDaemons/biz.ma-kom.annexgroup.plist

6. Ports — unter macOS der Punkt, an dem es klemmt

Unter Linux lauscht der Dienst auf den üblichen Ports: 25, 143, 993, 443 und 587.

Unter macOS nicht. Der Dienst läuft als _annexgroup und darf deshalb keine Ports unterhalb von 1024 belegen. Er lauscht auf hohen Ports, und der Router bildet die öffentlichen darauf ab:

Ohne diese Abbildung erreicht Sie keine Post von außen — der Server selbst läuft trotzdem und meldet keinen Fehler. Das ist der häufigste Grund für „alles grün, aber es kommt nichts an".

6a. Das Zertifikat — sonst starten zwei Ports nicht

Zwischen „Dienst starten" und dem Assistenten liegt eine Stelle, die der Server nicht von allein löst. Die Ports mit sofortigem TLS — 465 (Einlieferung) und 993 (IMAP) — starten ohne Zertifikat nicht. Ein Port, den Mail-Programme für verschlüsselt halten, darf es nicht nur manchmal sein.

Drei Wege, und Sie brauchen genau einen:

Beim selbstsignierten Zertifikat warnt jedes Mail-Programm, und die Einrichtung mit bloßer Adresse funktioniert nicht: Die Auskunftswege autoconfig. und autodiscover. müssen im selben Zertifikat stehen, sonst bricht das Programm die Verbindung ab, bevor es die Angaben liest.

7. Einrichtungsassistent öffnen

https://<ihr-host>/setup          (Linux)
https://<ihr-host>:8443/setup     (macOS)

Dort legen Sie die erste Domain, den ersten Administrator und ein getrenntes Root-Kennwort an. Die ersten 14 Tage laufen mit vollem Funktionsumfang ohne Lizenz.

Wie es weitergeht — DNS-Einträge, Zustellbarkeit, die Einrichtung mit bloßer Adresse — steht in Erste Schritte.

Wenn etwas nicht läuft

Protokolle liegen unter /var/log/annexgroup (Linux) beziehungsweise /usr/local/var/log/annexgroup (macOS).

Deinstallieren

sudo ./install-linux.sh --uninstall     # bzw. install-macos.sh

Entfernt werden nur Programm und Dienst. Konfiguration, Daten, Protokolle, die Datenbank und der Dienstbenutzer bleiben absichtlich stehen — ein Deinstallationsskript, das Postfächer löscht, ist ein Fehler, kein Merkmal.