Überblick

Worum es in diesem Handbuch geht

Dieses Handbuch richtet sich an Betreiber, die Nova Control Panel (kurz „Nova“) 1.0 auf eigenen Servern betreiben. Unterstützte Plattformen sind Ubuntu 24.04 (primär) und Debian 13, typischerweise in der Hetzner Cloud. Das Handbuch deckt Planung, Installation, Lizenzierung, Updates und den Update-Kanal, Wiederherstellung, den Umzug vom bisherigen Hosting-Panel, den Tagesbetrieb, Support, Sicherheit und Fehlersuche ab. Es ist so geschrieben, dass du es Schritt für Schritt abarbeiten kannst.

Hinweis: Das signierte Release-Bundle stellen wir für den Release Candidate auf Anfrage bereit; öffentlich erscheint es mit Release 1.0 am 1. Dezember 2026. Probe jede Prozedur zuerst auf einem Testserver, bevor du sie auf einem Server ausführst, auf den es ankommt.

Konventionen

• Befehle laufen als root, sofern nichts anderes angegeben ist.
• Wörter in GROSSBUCHSTABEN (SRC, IN, PKI, KEYS, PANEL, FLEET, …) sind Platzhalter. Sie sind im Kapitel Installation definiert.
• API-Pfade sind relativ zu https://PANEL:PORT/api/next/v1.
• „Profil“ meint die JSON-Datei des Installationsprofils; „Rekonfiguration“ meint ein kombiniertes reconfigure plus accept mit einer neuen Profildatei.
• Wo ein Werkzeug eine feste Zeile ausgibt, ist die erwartete Ausgabe wörtlich zitiert.

Komponenten

Nova bearbeitet die Konfiguration der Kundendienste nie von Hand. Der Node Agent erzeugt sie aus dem Soll-Zustand, den die Application vorgibt.

Der Operations-Store läuft im WAL-Modus: Die Dateien operations.sqlite-wal und operations.sqlite-shm daneben sind normal.

Wichtig: Kopiere die Live-Dateien des Operations-Stores nie von Hand. Die Operations-Sicherung (backup.php create, per VACUUM INTO) schreibt eine konsistente Einzeldatei. Stoppe vor einem Host-Snapshot die Operations-Timer und -Dienste oder stütze dich auf diese Sicherungsdatei.

Rollen

Eine Flotte (Fleet) wird durch die Topologie-Datei beschrieben (Fleet-Topologie-Schema 3). Der Installer übernimmt sie aus native_dns.topology_source_file und legt sie als /etc/nova-controlpanel/operations-client/agent-fleet.json ab.

Welche Bereiche des Panels welche Benutzerrolle sieht, beschreibt das Kapitel Rollen und Panel.

Topologie

Regeln:

• 1 bis 64 Nodes, eindeutige Node-IDs und Server-IDs.
• Der Rollensatz eines Nodes wird bei der Aufnahme (Enrollment) festgehalten. Er ändert sich nur über den Rollenablauf der Fabric (node-role-request … node-role-install, die Identität bleibt erhalten) plus eine Topologieänderung (siehe Anleitungen).
• Ein DNS-Secondary braucht einen eigenen Host.
• Die Lizenz begrenzt die Zahl der Nodes: Die Community-Edition erlaubt genau 1 Server. Weitere Nodes brauchen eine Abonnement-Lizenz, die vor der zweiten Aufnahme installiert sein muss (siehe Lizenz).

Ein einzelner Host

Ein Host trägt database,dns-primary,mail,master,web. Alles Interne bindet an 127.0.0.1. Es gibt keinen DNS-Secondary.

Mehrere Hosts

Das bewährte Layout auf Ubuntu 24.04 und Debian 13:

Eine Website auf einem Node erreicht eine Datenbank auf einem anderen Node über die remote_access-Liste der Datenbank.

Topologie vor der Installation planen

Die Topologie wird mit der ersten Installation installiert. Danach ändert sie sich nur über eine ausdrückliche, abgesicherte Topologieänderung (ein kombiniertes reconfigure --topology-change, siehe Anleitungen). Jede andere Rekonfiguration und jedes Upgrade verweigert eine geänderte Topologie-Datei. Eine Änderung fügt einen Node oder eine Rolle hinzu, entfernt eine leere Rolle oder einen leeren Node und benennt nie etwas um. Vorausplanen spart trotzdem Arbeit:

• Liste den Steuer-Node, den DNS-Primary, die DNS-Secondaries und die bekannten Mail-Nodes vor der ersten Installation auf.
• Zusätzliche Web-Nodes lassen sich nach der Installation auch ohne Topologie-Eintrag hinzufügen; ihre Platzierung ergibt sich aus Platform-Servern und Plan-Selektoren.
• Node-IDs und Server-IDs sind dauerhaft. Der Steuer-Node ist fest und behält master und web.

Fleet-Netzwerk

Interner Verkehr nutzt nie eine öffentliche Adresse:

• Der Koordinator (19443), jeder Secret-Lease-Listener und das Workspace Gateway binden an fleet_network.listen_address.
• Auf einem einzelnen Host ist diese Adresse 127.0.0.1.
• Bei mehreren Hosts ist es die RFC-1918-Adresse des Steuerhosts in einem privaten Netzwerk. Alle Hosts müssen sich dieses private Netzwerk teilen.

Das Werkzeug nova-fleet-network.py erkennt und prüft die Adresse:

python3 nova-fleet-network.py detect                   # exactly one RFC 1918 address, or 127.0.0.1
python3 nova-fleet-network.py detect --address 10.0.0.10
python3 nova-fleet-network.py check-exposure 10.0.0.10 19443 8092 8093

Mehrere private Adressen auf einem Host werden abgelehnt, nicht geraten. Lege die Adresse in diesem Fall mit --address fest.

In der Hetzner Cloud ist das Fleet-Netzwerk ein privates Hetzner-Netzwerk (Networks), das an jeden Server angehängt ist; die Adresse des Steuerhosts darin ist die Fleet-Adresse. Dasselbe private Netzwerk trägt nach einer Übernahme der Primary IP auch die Übertragungen des Importers (siehe Umzug).

Die Bindung an eine private Adresse ist die erste Absicherung. Die zweite ist die Node-Admission: Der Koordinator und die internen mTLS-Listener der Application (Secret-Leases, Backup-Exporte) lassen einen Node nur zu, wenn er in der Operations-Registry aktiv und nicht aufgegeben ist. Der Koordinator verlangt außerdem den Fingerabdruck des Agent-Zertifikats, das aktuell für diesen Node eingetragen ist (siehe Tagesbetrieb).

Panel-Port

Die Steuerungsebene läuft in einer eigenen Apache-Instanz (apache2@nova, Konfiguration in /etc/apache2-nova, Laufzeitidentität nova-controlpanel-web). Kunden-Websites bleiben in apache2. Es gibt zwei Wege zum Panel:

Instanz und Port-Weg werden bei der Installation gewählt. Ein normales Update ändert sie nie. Auch trusted_origin kann sich durch ein Update nicht ändern.

Ports

Die Beispiele in diesem Handbuch verwenden die Lease-Ports 8092 (user-access), 8093 (web), 8094 (mail), 8095 (database), 8096 (dns) und den Gateway-Port 8091. Beliebige freie, voneinander verschiedene Ports funktionieren.

Transaktionen und Last-known-good

Jede Installation, jedes Upgrade und jede Rekonfiguration ist eine Transaktion mit einem Journal in /var/lib/nova-controlpanel/installer/combined/transaction.json. Das vorherige Release bleibt als Last-known-good auf der Platte, bis die nächste Abnahme (accept) erfolgt. Details stehen in Updates und Wiederherstellung.

Wichtig: Nach accept gibt es keinen Installer-Rollback mehr. Dann helfen nur noch Backups und Snapshots.

Was du vorab wissen solltest

• Lizenz: Die Installation erzeugt eine Installations-ID (ncpi_…, anzeigen mit nova-update license show-id). Ohne Lizenz läuft Nova als Community-Edition mit genau 1 Server. Die Lizenz installierst du mit nova-update license install – vor dem zweiten node-register.
• Stufenweises Einschalten: Der kombinierte Installer arbeitet mit stage, install, verify und accept. Danach schaltest du die Ebenen per Rekonfiguration stufenweise ein: Leser → MFA/Step-up → Schreiber.
• Backup-Download: Bei einer Neuinstallation ist der Backup-Download eingeschaltet. Ein Upgrade schaltet ihn dagegen nie ein. Details: Backups.
• Offsite-Backups sind nicht Teil von Version 1.0.
• Update-Kanal: Signierte Releases kommen vom Release-Server über die Kanäle stable, beta und dev. Angeboten werden nur Releases, für die die Lizenz berechtigt; die installierte Version läuft immer weiter, ein Downgrade gibt es nie.
• Node, der später zur Flotte kommt: Speichere nach dem Hinzufügen jede globale Konfigurationssektion und jede Direktive einmal, damit der neue Node die aktuellen Werte erhält. Bis dahin läuft er mit Standardwerten.

Aufbau des Handbuchs

Typische Wege durch das Handbuch

• Neue Produktionsflotte in der Hetzner Cloud: Überblick → Voraussetzungen → Installation (Lizenz vor dem zweiten Node) → Sicherheit.
• Umzug vom bisherigen Hosting-Panel: Installation auf neuen Hosts → Umzug (zuerst auf Wegwerf-Servern proben) → Tagesbetrieb.
• Monatliche Wartung: Updates (Betriebssystem-Updates, Upgrade; beim ersten Mal mit dem Plan für das Produktions-Upgrade).
• Etwas ist kaputt: Fehlersuche → Wiederherstellung.