opnexus – das Kommandozeilen-Werkzeug

Mit opnexus aktualisierst du OPNexus mit einem Befehl, rollst bei Problemen zurück und sicherst die Datenbank – ohne Handarbeit an Containern oder Datenbank.

Überblick

opnexus ist ein Bash-Skript für Installationen aus fertigen Release-Images. Es liegt im Release-Bundle neben der docker-compose.yml und kennt vier Befehle:

Befehl	Was er tut
`opnexus status`	Zeigt Version, Dienste und Datenbank-Revision.
`opnexus update [VERSION]`	Zieht neue Images, wechselt, wartet auf „gesund“ und rollt bei Problemen automatisch zurück.
`opnexus rollback`	Macht das letzte Update rückgängig, bei Bedarf samt Datenbank.
`opnexus backup`	Schreibt sofort ein Backup der Datenbank.

Voraussetzungen

Docker mit Compose v2 und Bash auf dem Server.
Eine Installation aus dem Release-Bundle (fertige Images aus der Registry). In deiner .env steht OPNEXUS_IMAGE_REPO; das Bundle setzt es bereits. Fehlt der Eintrag, bricht das Werkzeug ab – es ist nicht für lokale Builds gedacht (dort: git pull && docker compose up -d --build).
Aufruf im Ordner mit docker-compose.yml und .env, oder von überall mit OPNEXUS_DIR=/pfad/zu/opnexus.

cd /opt/opnexus-1.15.0
./opnexus status

`status`

Zeigt, was gerade läuft, und – falls vorhanden – das letzte Update, das sich zurückrollen lässt.

$ ./opnexus status
Image-Repo:        git.opnexus.dev/opnexus
OPNEXUS_VERSION:   1
Laufende Version:  1.15.0
DB-Revision:       0004
backend: healthy
frontend: healthy
proxy: running

OPNEXUS_VERSION ist die „Spur“, der die Installation folgt: eine feste Version (1.15.0), eine Minor-Spur (1.15), eine Major-Spur (1) oder latest.

`update`

./opnexus update            # der in .env gewählten Spur folgen
./opnexus update 1.15.0     # feste Version
./opnexus update 1.15       # neueste 1.15.x

Der Ablauf, Schritt für Schritt:

Zustand lesen. Läuft das Backend nicht oder antwortet es nicht, bricht das Werkzeug ab – erst reparieren, dann updaten.
Images ziehen. Dabei ändert sich am laufenden System nichts. Schlägt der Pull fehl, ist nichts verändert worden.
Alten Zustand merken (Datei .opnexus-update-state), damit ein Rollback weiß, wohin.
Wechseln. OPNEXUS_VERSION in .env wird gesetzt, dann docker compose up -d --no-build. Braucht die neue Version eine Datenbank-Migration, sichert das Backend die Datenbank vorher selbst (pre-upgrade-…dump).
Warten. Bis backend, frontend und proxy gesund sind (höchstens 240 Sekunden).
Bei Fehlern zeigt das Werkzeug das Backend-Log und rollt automatisch zurück.

Vor einem Update lohnt sich ein Blick in den Changelog. Ein Update dauert typischerweise nur den Neustart der Dienste; die Weboberfläche ist dabei kurz nicht erreichbar.

`rollback`

./opnexus rollback

Setzt die Installation auf den Stand vor dem letzten update zurück: exakt auf den Image-Tag, der vorher eingestellt war.

Hat das Update die Datenbank nicht migriert, werden nur die Dienste auf die alte Version gesetzt.
Hat es sie migriert, wird die Sicherung vor dem Update zurückgespielt. Dabei gilt: Nur ein Backup, das nach dem Start dieses Updates entstanden ist, wird verwendet, und es wird vorher auf Lesbarkeit geprüft. Davor entsteht eine Sicherheitskopie des jetzigen Zustands (pre-rollback-…dump); scheitert das Zurückspielen, stellt das Werkzeug diese wieder her.
Danach ist OPNEXUS_VERSION in .env fest auf die alte Version gesetzt. Für den nächsten Versuch gibst du die Zielversion wieder an.

Wichtig: Log-Historie und Ressourcen-Messwerte sind in den Sicherungen nicht enthalten und nach einem Datenbank-Rollback leer. Alles andere – Hosts, Regeln, Benutzer, Audit-Verlauf – steht auf dem Stand vor dem Update. Zurückgerollt wird immer nur ein Schritt (das letzte Update).

`backup`

./opnexus backup

Schreibt sofort ein Backup als manual-<Zeit>.dump in das Docker-Volume postgres_backups. Die Daten der beiden großen Tabellen (Firewall-Logs und Ressourcen-Messwerte) fehlen darin bewusst, sonst wäre der Dump riesig; alle Einstellungen und der Verlauf der Änderungen sind enthalten. Zusätzlich legt ein Begleit-Container regelmäßig automatische Sicherungen im selben Volume ab.

docker compose exec postgres-backup ls -l /backups

Konfiguration

Einstellung	Wirkung
`OPNEXUS_DIR`	Ordner mit `docker-compose.yml` und `.env`, falls nicht der des Skripts.
`OPNEXUS_UPDATE_TIMEOUT`	Sekunden, die auf „gesund“ gewartet wird (Standard 240).
`OPNEXUS_NO_AUTO_ROLLBACK=1`	Kein automatisches Zurückrollen bei fehlgeschlagenem Update; der Zustand bleibt zur Analyse stehen, manuell: `opnexus rollback`.
`.env`: `OPNEXUS_IMAGE_REPO`, `OPNEXUS_VERSION`	Registry und Spur der Installation.
`.env`: `POSTGRES_USER`, `POSTGRES_DB`, `POSTGRES_PASSWORD`	Zugang zur Datenbank für Backup und Rollback (Standard-Benutzer und -Datenbank: `opnexus`).

Schutzmechanismen

Erst ziehen, dann wechseln: Ein fehlgeschlagener Download verändert nichts.
Automatischer Rückfall: Wird die neue Version nicht gesund, wird zurückgerollt.
Backup vor der Migration und Prüfung vor dem Zurückspielen: kein Überschreiben mit einer zu alten oder defekten Sicherung.
Sicherheitskopie des Zustands vor einem Datenbank-Rollback.
Eingaben geprüft: Die Versionsangabe darf nur Zeichen enthalten, die ein Image-Tag haben darf.
Passwort nicht in der Prozessliste: Das Datenbank-Passwort geht über die Umgebung an die Werkzeuge, nicht als Argument.

Fehlerbehebung

Meldung	Was zu tun ist
„OPNEXUS_IMAGE_REPO ist in .env nicht gesetzt“	Die Installation läuft nicht aus Release-Images. Entweder auf Release-Images umstellen oder lokal mit `git pull && docker compose up -d --build` aktualisieren.
„Pull fehlgeschlagen — nichts wurde verändert“	Registry erreichbar? Gibt es die Version? Dann einfach erneut versuchen.
„Backend läuft nicht oder antwortet nicht“	Erst reparieren (`docker compose logs backend`), dann updaten.
„Update nicht gesund geworden“	Das Backend-Log steht darunter; das Werkzeug rollt selbst zurück. Mit `OPNEXUS_NO_AUTO_ROLLBACK=1` bleibt der Zustand zur Analyse stehen.
„Kein Update-Zustand … nichts zurückzurollen“	Ein Rollback geht nur, wenn vorher ein `opnexus update` gelaufen ist; dabei wird die Zustandsdatei angelegt.
„Datenbank wurde migriert, aber es gibt kein pre-upgrade-Backup“	Das Backup vor der Migration fehlt (z. B. wegen `SKIP_MIGRATION_BACKUP`). Das Backend bleibt gestoppt; manuell eingreifen, ein eigenes `opnexus backup` hilft für die Zukunft.

Grenzen

Nur für Installationen aus Release-Images (amd64).
Ein Rollback geht einen Schritt zurück – auf den Stand vor dem letzten Update.
Nach einem Datenbank-Rollback sind Log-Historie und Messwerte leer.
Das Werkzeug verwaltet die OPNexus-Installation, nicht deine Firewalls; dort ändert es nichts.

Weitere Hilfe

Ist der einzige Admin ohne Authenticator und ohne Wiederherstellungscodes ausgesperrt, schaltet dieser Befehl auf dem Server die Zwei-Faktor-Anmeldung für ein Konto ab (er braucht Shell-Zugriff auf den Server):

docker compose exec backend python -m app.reset_2fa BENUTZERNAME

Die vollständige Anleitung steht im Handbuch und in der README (Abschnitt „Release-Images & CI“).