OPNexus unter macOS installieren

OPNexus läuft als Docker-Stack. Auf dem Mac nutzt du dafür die App Docker Desktop: Herunterladen und Entpacken im Finder, Einrichten und Starten mit wenigen Befehlen im Terminal, alles Weitere in der App. Diese Anleitung führt vom leeren Mac bis zur Anmeldung.

Vorab: Was du wissen solltest

Entwickelt und getestet wird OPNexus unter Linux. Auf dem Mac läuft derselbe Stack in Docker Desktop, auf Apple-Chips (M1 und neuer) wie auf Intel-Macs; die Images gibt es für beide. Dieser Weg ist nicht auf jeder macOS-Version geprüft; Rückmeldungen sind willkommen.
Für den Dauerbetrieb ist ein Linux-Server oder eine Linux-VM besser. Ein Mac, der schläft oder abgemeldet ist, überwacht nichts und verschickt keine Benachrichtigungen. Ein Mac mini, der durchläuft, ist eine brauchbare Ausnahme (siehe unten).
Lizenz von Docker Desktop: Für Privatpersonen, Ausbildung, Open-Source-Projekte und kleine Unternehmen kostenlos, für größere Unternehmen kostenpflichtig. Die aktuellen Bedingungen stehen bei Docker.

Voraussetzungen

Eine aktuelle macOS-Version (Docker Desktop unterstützt die aktuelle und die beiden vorherigen Hauptversionen) und ein Administratorkonto für die Installation.
8 GB Arbeitsspeicher im Mac als sinnvoller Mindestwert.
Die Ports 80 und 443 sind frei (normalerweise der Fall).
Der Mac erreicht deine OPNsense-Firewalls per HTTPS (zum Beispiel im selben Netz oder über ein VPN).

Schritt 1: Docker Desktop installieren

Lade Docker Desktop von docker.com, passend zu deinem Mac: „Apple Chip“ oder „Intel Chip“ (welcher es ist, zeigt › Über diesen Mac).
Öffne die .dmg-Datei und ziehe Docker in den Ordner Programme. Starte Docker aus dem Programme-Ordner, akzeptiere die Nutzungsbedingungen und bestätige die Einrichtung mit deinem Passwort. Die Anmeldung bei Docker kannst du überspringen.
Warte, bis unten links „Engine running“ steht.
Schalte unter Settings › General „Start Docker Desktop when you sign in to your computer“ ein.

Schritt 2: OPNexus herunterladen und einrichten

Lade das Release-Bundle opnexus-1.34.1.tar.gz herunter (alle Versionen auf der Release-Seite). Ein Doppelklick im Finder entpackt es zum Ordner opnexus-1.34.1. Verschiebe den Ordner an einen festen Platz, zum Beispiel in deinen Benutzerordner.
Öffne das Programm Terminal (Programme › Dienstprogramme). Tippe cd (mit Leerzeichen), ziehe den Ordner opnexus-1.34.1 aus dem Finder ins Terminal-Fenster und drücke Enter.
Lege die Einstellungsdatei an und öffne sie in TextEdit. Der Finder erlaubt keine Dateinamen, die mit einem Punkt beginnen, deshalb geht das nur im Terminal:
```
cp .env.example .env
open -e .env
```
Trage in TextEdit ein und speichere (⌘S):
```
POSTGRES_PASSWORD=ein-langes-eigenes-passwort
ADMIN_PASSWORD=dein-anmeldepasswort-mindestens-12-zeichen
```
Schalte vorher unter Bearbeiten › Ersetzungen die „Intelligenten Anführungszeichen“ aus, falls dein Passwort Anführungszeichen enthält.

Schritt 3: OPNexus starten

Gib im Terminal (weiter im OPNexus-Ordner) ein:
```
docker compose up -d
```
Beim ersten Mal lädt Docker die Images herunter; das dauert einige Minuten.
Wechsle zu Docker Desktop › Containers. Dort erscheint die Gruppe opnexus. Klappe sie auf und warte, bis alle Dienste einen grünen Punkt haben und backend und frontend „healthy“ zeigen.

Anmelden und der Zertifizierungsstelle vertrauen

Öffne https://localhost und melde dich als admin mit dem ADMIN_PASSWORD aus der .env an; der Einrichtungsassistent führt durch die ersten Schritte. OPNexus nutzt eine eigene Zertifizierungsstelle, deshalb warnt der Browser zunächst. Die Verbindung ist trotzdem verschlüsselt.

Die Warnung dauerhaft beseitigen:

Lade https://localhost/opnexus-ca.crt herunter (im Browser über „Weiter zur Seite“).

Vergleiche vor dem Import den Fingerabdruck. Im Terminal, im OPNexus-Ordner:

openssl x509 -in ~/Downloads/opnexus-ca.crt -noout -fingerprint -sha256
docker compose exec -T proxy cat /data/caddy/pki/authorities/local/root.crt | openssl x509 -noout -fingerprint -sha256

Beide Zeilen müssen denselben Wert zeigen.

Doppelklick auf opnexus-ca.crt öffnet die Schlüsselbundverwaltung; das Zertifikat landet im Schlüsselbund „Anmeldung“. Doppelklick auf den Eintrag „Caddy Local Authority“ › „Vertrauen“ › „Bei Verwendung dieses Zertifikats“: Immer vertrauen, Fenster schließen und mit deinem Passwort bestätigen.
Safari und Chrome übernehmen das sofort; Seite neu laden.
Firefox hat einen eigenen Speicher: Einstellungen › Datenschutz & Sicherheit › Zertifikate anzeigen › Zertifizierungsstellen › Importieren.

Aus dem Netz erreichen

Sollen andere Rechner OPNexus öffnen, braucht dein Mac eine feste Adresse im Netz (zum Beispiel per DHCP-Reservierung). Trage sie mit open -e .env in der .env ein (hier beispielhaft 10.0.0.5):

OPNEXUS_SITES=10.0.0.5
OPNEXUS_DEFAULT_SNI=10.0.0.5
FRONTEND_ORIGIN=https://10.0.0.5
COOKIE_SECURE=true
TRUST_PROXY_HEADERS=true

Übernimm die Änderung mit docker compose up -d im OPNexus-Ordner. Fragt macOS, ob Docker eingehende Verbindungen annehmen darf, wähle „Erlauben“. Soll der Mac dauerhaft erreichbar bleiben, verhindere unter Systemeinstellungen › Energie (bzw. Batterie › Optionen) den automatischen Ruhezustand. Importiere die Zertifizierungsstelle auf jedem Rechner, der OPNexus nutzt (mit der Adresse statt localhost). Einzelheiten stehen im Handbuch.

Im Alltag: OPNexus in Docker Desktop

Fast alles erledigst du in der Docker-Desktop-App, Bereich Containers. Dort steht OPNexus als Gruppe opnexus mit den Diensten backend, frontend, proxy, postgres und postgres-backup.

Aufgabe	In Docker Desktop
Läuft alles?	Grüner Punkt bei jedem Dienst; `backend` und `frontend` zeigen zusätzlich „healthy“.
OPNexus anhalten / starten	In der Zeile `opnexus` auf ■ (Stop) bzw. ▶ (Start). Die Daten bleiben erhalten.
Einen Dienst neu starten	In seiner Zeile auf ⟳ (Restart), z. B. `proxy` nach einer Änderung der Adressen.
Protokoll ansehen	Auf den Dienst klicken › Reiter „Logs“. Ohne `ADMIN_PASSWORD` steht im Log von `backend` beim ersten Start das erzeugte Anmeldepasswort.
Automatisch starten	Settings › General › Start Docker Desktop when you sign in einschalten; die Container starten dann von selbst.

Vorsicht: Unter Volumes liegen die Daten von OPNexus (Datenbank, Zugangsdaten der Firewalls, Schlüssel). Ein gelöschtes Volume ist unwiederbringlich weg; lege vorher eine Vollsicherung an (unten).

Updates, Sicherung und Passwort: das Werkzeug opnexus

Das mitgelieferte Werkzeug opnexus ist ein Bash-Skript für Linux. Unter macOS startest du es stattdessen aus seinem Docker-Image, das Bash, Docker Compose und die Signaturprüfung schon enthält. Gib die Befehle im Terminal im OPNexus-Ordner ein (cd und den Ordner ins Terminal ziehen):

docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock -v "$PWD:/project" git.opnexus.dev/opnexus/opnexus-updater:latest opnexus status

Aufgabe	Letztes Wort statt `status`
Zustand und Version	`status`
Auf die neueste Version aktualisieren (prüft Signaturen, sichert die Datenbank, rollt bei Problemen zurück)	`update`
Letztes Update zurücknehmen	`rollback`
Datenbank sichern	`backup`
Vollsicherung inkl. Zugangsdaten (fragt nach einer Passphrase)	`backup --full`
Neues Anmeldepasswort für `admin`	`password`

Ausführlich: Dokumentation des Werkzeugs. Ein Update ersetzt auch die docker-compose.yml im Ordner (die alte bleibt als Sicherung liegen); eigene Änderungen gehören in eine docker-compose.override.yml.

Fehlerbehebung

Problem	Lösung
`command not found: docker`	Docker Desktop läuft nicht oder wurde gerade installiert. Docker Desktop starten, warten bis „Engine running“, ein neues Terminal-Fenster öffnen.
`./opnexus` meldet Fehler (z. B. `mapfile: command not found`)	Das Skript braucht Linux-Werkzeuge. Unter macOS das Werkzeug aus dem Docker-Image starten (Abschnitt oben).
„port is already allocated“	Port 80 oder 443 ist belegt (z. B. ein lokaler Webserver). Den Dienst beenden oder in der `.env` `PROXY_HTTPS_PORT` und `PROXY_HTTP_PORT` ändern; dann `https://localhost:PORT` öffnen.
Ein Dienst bleibt rot oder startet immer neu	In Docker Desktop auf den Dienst › „Logs“. Häufig fehlt `POSTGRES_PASSWORD` in der `.env` oder TextEdit hat die Datei als `.env.rtf` gespeichert (dann neu mit `open -e .env`).
Zwei-Faktor-Codes werden abgelehnt	Die Uhr der Docker-Umgebung kann nach dem Ruhezustand abweichen. Docker Desktop beenden (Wal-Symbol in der Menüleiste › Quit) und neu starten.
Anmeldepasswort vergessen	`opnexus password` über das Werkzeug (Abschnitt oben) setzt ein neues und zeigt es an.

Weitere Hilfe steht im Handbuch.