Installation unter macOS: Handbuch

Florian wird unter macOS als eigenständiges Binary (self-contained Build für osx-arm64 bzw. osx-x64) ausgeliefert und als Hintergrunddienst über launchd betrieben. Diese Seite führt Sie durch die Freigabe des Binarys, das Anlegen des Datenverzeichnisses und die Einrichtung eines Autostarts, damit Florian nach jedem Neustart des Servers automatisch verfügbar ist.

Voraussetzungen

Anforderung	Empfehlung
macOS-Version	macOS 12 (Monterey) oder neuer
Architektur	Apple Silicon (`osx-arm64`) oder Intel (`osx-x64`) – passendes Binary wählen
Zugriff	Ein Administrator-Konto auf dem Zielrechner
Netzwerk	Erreichbarkeit des Lizenz-Servers für die einmalige Aktivierung

Hinweis: Florian ist ein Single-Prozess und benötigt keine externe Datenbank. Alle Daten liegen in einer lokalen SQLite-Datei innerhalb des Datenverzeichnisses (siehe unten).

Binary bereitstellen

Laden Sie das macOS-Paket für Ihre Architektur aus dem Kunden-Portal herunter (Bereich Downloads).
Entpacken Sie das Archiv an einen dauerhaften Ort. Bewährt hat sich ein eigenes Verzeichnis unterhalb von /opt:
```
sudo mkdir -p /opt/florian
sudo tar -xzf ~/Downloads/florian-osx-arm64.tar.gz -C /opt/florian
```
Setzen Sie das Ausführungsrecht auf das Binary:
```
sudo chmod +x /opt/florian/florian
```

Hinweis: Verwenden Sie einen festen Installationspfad. Die weiter unten gezeigte launchd-Konfiguration verweist direkt auf diesen Pfad; verschieben Sie das Binary später, muss die Konfiguration angepasst werden.

Gatekeeper und Quarantäne

macOS versieht heruntergeladene Programme mit einem Quarantäne-Attribut. Beim ersten Start kann Gatekeeper die Ausführung deshalb blockieren („… kann nicht geöffnet werden, da der Entwickler nicht überprüft werden kann").

Prüfen Sie zunächst, ob das Quarantäne-Attribut gesetzt ist:

xattr -p com.apple.quarantine /opt/florian/florian

Liefert der Befehl einen Wert zurück, entfernen Sie das Attribut vom gesamten Installationsverzeichnis:

sudo xattr -dr com.apple.quarantine /opt/florian

Danach lässt sich Florian ohne weitere Sicherheitsabfrage starten.

Achtung: Entfernen Sie das Quarantäne-Attribut nur bei Dateien, die Sie bewusst aus dem Kunden-Portal geladen und deren Herkunft Sie geprüft haben. Vergleichen Sie im Zweifel die Prüfsumme des Downloads mit der im Portal angegebenen SHA-256-Signatur, bevor Sie die Freigabe erteilen.

Alternativ können Sie die Freigabe nach einem blockierten Erststart über Systemeinstellungen → Datenschutz & Sicherheit → „Dennoch öffnen" erteilen. Für den unbeaufsichtigten Serverbetrieb ist das Entfernen des Attributs per Terminal die verlässlichere Variante.

Datenverzeichnis

Florian legt Datenbank, Uploads, Backups und Logs in einem Datenverzeichnis ab. Trennen Sie dieses bewusst vom Installationsverzeichnis des Binarys – so bleiben Ihre Daten bei einem Update unberührt.

Legen Sie ein Datenverzeichnis an und geben Sie es dem späteren Dienstbenutzer frei:

sudo mkdir -p /Library/Application\ Support/Florian
sudo chown -R _florian:_florian /Library/Application\ Support/Florian

Den Pfad übergeben Sie Florian über die Umgebungsvariable FLORIAN_DATA_DIR (siehe die plist im nächsten Abschnitt).

Inhalt	Ablageort im Datenverzeichnis
SQLite-Datenbank	`data/florian.db`
Hochgeladene Dateien	`uploads/`
Automatische Backups	`backups/`
Log-Dateien	`logs/`

Achtung: Das Datenverzeichnis enthält personenbezogene Mitgliederdaten. Beschränken Sie die Zugriffsrechte auf den Dienstbenutzer und beziehen Sie das Verzeichnis in Ihre reguläre Datensicherung ein.

Dienstbenutzer anlegen (empfohlen)

Betreiben Sie Florian nicht als root, sondern unter einem eigenen, rechtearmen Systembenutzer. Legen Sie diesen einmalig an:

sudo dscl . -create /Users/_florian UserShell /usr/bin/false
sudo dscl . -create /Users/_florian RealName "Florian Service"
sudo dscl . -create /Users/_florian UniqueID 460
sudo dscl . -create /Users/_florian PrimaryGroupID 460
sudo dscl . -create /Groups/_florian
sudo dscl . -create /Groups/_florian PrimaryGroupID 460

Hinweis: Wählen Sie eine UniqueID/PrimaryGroupID, die auf dem System noch frei ist. Bestehende IDs prüfen Sie mit dscl . -list /Users UniqueID.

launchd-Agent bzw. -Daemon

Für den dauerhaften Serverbetrieb – unabhängig von einer angemeldeten Sitzung – richten Sie einen LaunchDaemon ein. Diese plist liegt in /Library/LaunchDaemons/ und startet Florian systemweit beim Hochfahren.

Hinweis: Ein LaunchDaemon läuft ohne Benutzeranmeldung und eignet sich für Server. Ein LaunchAgent in ~/Library/LaunchAgents/ startet erst nach der Anmeldung eines bestimmten Benutzers – das ist nur sinnvoll, wenn Florian ausschließlich während einer aktiven Sitzung laufen soll.

Erstellen Sie die Datei /Library/LaunchDaemons/de.florian.server.plist mit folgendem Inhalt:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>de.florian.server</string>

    <key>ProgramArguments</key>
    <array>
        <string>/opt/florian/florian</string>
    </array>

    <key>EnvironmentVariables</key>
    <dict>
        <key>FLORIAN_DATA_DIR</key>
        <string>/Library/Application Support/Florian</string>
        <key>FLORIAN_URLS</key>
        <string>http://0.0.0.0:5000</string>
    </dict>

    <key>UserName</key>
    <string>_florian</string>

    <key>WorkingDirectory</key>
    <string>/opt/florian</string>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Library/Application Support/Florian/logs/florian.out.log</string>

    <key>StandardErrorPath</key>
    <string>/Library/Application Support/Florian/logs/florian.err.log</string>
</dict>
</plist>

Passen Sie mindestens diese Werte an Ihre Umgebung an:

Schlüssel	Bedeutung
`ProgramArguments`	Vollständiger Pfad zum Florian-Binary
`FLORIAN_DATA_DIR`	Pfad zum Datenverzeichnis aus dem vorigen Abschnitt
`FLORIAN_URLS`	Adresse und Port, auf denen Florian lauscht
`UserName`	Rechtearmer Dienstbenutzer
`KeepAlive`	`true` startet den Prozess nach einem Absturz automatisch neu

Setzen Sie abschließend Eigentümer und Rechte der plist – launchd lädt Daemon-Dateien nur, wenn sie root gehören:

sudo chown root:wheel /Library/LaunchDaemons/de.florian.server.plist
sudo chmod 644 /Library/LaunchDaemons/de.florian.server.plist

Autostart aktivieren

Registrieren Sie den Daemon bei launchd und starten Sie ihn. Verwenden Sie die aktuelle launchctl-Syntax (bootstrap/enable):

# Beim Systemstart-Domain registrieren
sudo launchctl bootstrap system /Library/LaunchDaemons/de.florian.server.plist

# Dauerhaft aktivieren, damit er auch nach Neustarts geladen wird
sudo launchctl enable system/de.florian.server

# Sofort starten
sudo launchctl kickstart -k system/de.florian.server

Den Status prüfen Sie mit:

sudo launchctl print system/de.florian.server

Ein Beenden bzw. Entladen des Dienstes – etwa vor einem manuellen Update im Wartungsfenster – erfolgt spiegelbildlich:

sudo launchctl bootout system/de.florian.server

Hinweis: Auf älteren macOS-Versionen können statt bootstrap/bootout die Befehle launchctl load -w bzw. launchctl unload -w erforderlich sein. Die oben gezeigte Syntax ist unter macOS 12 und neuer die empfohlene Variante.

Nach dem Start ist Florian im Browser unter der in FLORIAN_URLS konfigurierten Adresse erreichbar. Führen Sie beim ersten Aufruf den Setup-Assistenten aus und hinterlegen Sie Ihren Lizenzschlüssel zur einmaligen Aktivierung.

Logs und Fehlersuche

Startet der Dienst nicht wie erwartet, liefern die Log-Dateien den ersten Anhaltspunkt:

# Laufende Ausgabe von Florian verfolgen
tail -f "/Library/Application Support/Florian/logs/florian.out.log"

# Fehlerausgabe verfolgen
tail -f "/Library/Application Support/Florian/logs/florian.err.log"

Meldungen von launchd selbst – etwa zu blockierten Starts oder fehlenden Rechten – finden Sie im Unified Log des Systems:

sudo log show --predicate 'process == "launchd"' --last 15m

Symptom	Häufige Ursache	Abhilfe
Dienst startet nicht, keine Logdatei	`plist` gehört nicht `root:wheel` oder hat falsche Rechte	Eigentümer/Rechte gemäß Abschnitt launchd setzen
„kann nicht geöffnet werden" im Log	Quarantäne-Attribut noch gesetzt	`xattr -dr com.apple.quarantine` ausführen
Sofortiger Neustart in Endlosschleife	Falscher Datenverzeichnis-Pfad oder fehlende Schreibrechte	`FLORIAN_DATA_DIR` prüfen, Eigentümer des Verzeichnisses korrigieren
Port nicht erreichbar	Belegter Port oder Firewall	`FLORIAN_URLS` anpassen, Firewall-Regel ergänzen

Achtung: Die Log-Dateien können Diagnosedaten enthalten. Geben Sie sie nur an den Support weiter, nachdem Sie personenbezogene Inhalte geprüft haben.

Installation unter macOS