Installation

Installation

ZPO ist ein einzelnes Go-Binary mit eingebetteter Web-Oberfläche und SQLite. Drei Wege führen dahin.

Debian-Paket

Das Paket liegt im Techeve-apt-Repository. Einmal einrichten:

# Signaturschlüssel hinterlegen (repo@techeve.de).
# Der Fingerprint steht auf https://doc.techeve.de — vor dem Import prüfen.
curl -fsSL https://repo.techeve.de/techeve.asc | sudo gpg --dearmor -o /usr/share/keyrings/techeve.gpg

# Quelle eintragen
echo "deb [signed-by=/usr/share/keyrings/techeve.gpg] https://repo.techeve.de stable main" \
  | sudo tee /etc/apt/sources.list.d/techeve.list

Dann installieren:

sudo apt update
sudo apt install zpo

Das Paket richtet einen systemd-Dienst ein und startet ihn sofort. Das einmalig erzeugte Admin-Passwort steht im Journal:

journalctl -u zpo | grep -A3 "First start"

Docker

Das Image liegt in der GitLab-Container-Registry. Ein Volume auf /data hält Konfiguration, Datenbank und den Hauptschlüssel:

docker run -d \
  --name zpo \
  -p 8080:8080 \
  -v zpo-data:/data \
  registry.techeve.de/techeve/zpo:latest

Das Admin-Passwort erscheint einmalig im Log:

docker logs zpo | grep -i passwort

Die Zeitzone lässt sich über -e TZ=Europe/Berlin setzen. Weitere Umgebungsvariablen stehen unter Konfiguration.

Binary aus dem Release

Für linux/amd64 und linux/arm64 gibt es fertige Binaries im Release. Das Binary liegt einfach in einem Verzeichnis und legt dort (oder im Verzeichnis aus -data) seine Daten ab:

./zpo

Erster Start

Beim ersten Start legt ZPO im Datenverzeichnis drei Dateien an:

Datei	Inhalt
config.json	Grundeinstellungen mit frisch erzeugtem JWT-Geheimnis
zpo.db	SQLite-Datenbank, alle Zustände und Einstellungen
secret.key	der Hauptschlüssel für gespeicherte Zugangsdaten

Fehlt admin_initial_password in der Konfiguration, erzeugt ZPO ein zufälliges Admin-Passwort und gibt es einmalig auf der Konsole aus (als Dienst: im Journal).

Danach ist die Oberfläche unter http://<host>:8080 erreichbar und der Standard-Benutzer admin kann sich anmelden.

Einen Proxy-Knoten einrichten

ZPO steuert HAProxy, es ersetzt ihn nicht — jeder Standort braucht mindestens einen Server mit HAProxy und dessen Data Plane API. Das Installationsskript setup-haproxy.sh nimmt einem das ab: Es installiert beides, schreibt die Grundkonfiguration, öffnet die Verwaltungs-Schnittstelle in der Firewall, erzeugt das Passwort und gibt am Ende die Angaben aus, die in ZPO einzutragen sind.

Auf dem künftigen Knoten, als root:

curl -fsSL https://repo.techeve.de/zpo/setup-haproxy.sh | sudo bash

Der Rechner behält dabei seinen Hostnamen. Soll er einen bestimmten bekommen, kommt der dahinter:

curl -fsSL https://repo.techeve.de/zpo/setup-haproxy.sh | sudo bash -s -- --name proxy-nord

Weitere Optionen zeigt --help; einstellbar sind Adresse, Port und Benutzername der Verwaltungs-Schnittstelle. Die Ausgabe endet mit:

== Fertig

In ZPO als Proxy-Knoten eintragen:
  Verwaltungs-Adresse   https://192.168.10.5:5555
  Fingerabdruck         8861ac49da34005fa1de3553baa1fdad14d369085bec513ddf3c1f2e50d8964c
  Benutzer              zpo
  Passwort              …

Diese Angaben unter Proxy-Knoten → Knoten anlegen eintragen — Adresse, Fingerabdruck, Benutzer und Passwort — dazu die Adressen:

• Interne Adressen — unter ihnen erreichen Clients im lokalen Netz den Proxy; sie wandern in die Einträge der lokalen DNS-Server. Meist dieselbe wie oben, aber das entscheidet die Netzführung.
• Öffentliche Adressen (optional) — unter ihnen ist der Proxy aus dem Internet erreichbar, bei einem Router davor dessen Adresse mit der Portweiterleitung. ZPO trägt sie nirgends ein; der Dienst-Dialog zeigt sie als Vorlage für Einträge im öffentlichen DNS, wenn ein Dienst ohne lokales DNS läuft.

Das Skript ist wiederholbar: Ein zweiter Lauf erzeugt kein neues Passwort und bringt einen älteren Knoten auf die aktuelle Grundkonfiguration. Es schreibt dabei haproxy.cfg neu, übernimmt aber die von ZPO angelegten Backends und Eingangsports und sichert die alte Datei vorher (haproxy.cfg.bak-…).

Voraussetzungen: Ubuntu oder Debian mit apt, root-Rechte, und der Knoten muss die Data-Plane-API-Version aus dem Netz laden können. Was das Skript genau anlegt, steht in doc/haproxy-grundkonfiguration.md.

Der Hauptschlüssel

Sicherungspasswort setzen — oder secret.key separat sichern!

secret.key verschlüsselt alle gespeicherten Zugangsdaten (Knoten, ACME-Konten, DNS-Provider, private Schlüssel der Zertifikate, SMTP- und SFTP-Passwörter) und liegt bewusst neben der Datenbank, nicht darin. Ohne den Schlüssel sind die Zugangsdaten unlesbar und müssen alle neu eingetragen werden.

Am einfachsten: In der Sicherung ein Sicherungspasswort setzen. Dann kommt der Schlüssel verschlüsselt in jede Sicherung, und eine Rücksicherung stellt auch auf einem neuen Host alles wieder her (siehe Betrieb). Ohne Passwort müssen beim Umzug zpo.db und secret.key mit.

Alternativ kommt der Schlüssel aus der Umgebungsvariable ZPO_SECRET_KEY (base64) oder aus der Datei, die ZPO_SECRET_KEY_FILE nennt. In diesem Fall gilt der Schlüssel aus der Umgebung auch nach einer Rücksicherung — ein mitgesicherter landet zwar als secret.key im Datenverzeichnis, wird aber nicht gelesen.