Technische Administration

• Architektur
• Konfiguration
• LDAP-Anmeldung
• Betrieb und Aktualisierung
• Sicherung und Wiederherstellung
• Fehlersuche
• Build und Auslieferung

Architektur

Zielgruppe: Technische Administration

Überblick

oPBWeb läuft als ein Docker-Compose-Projekt mit dem Namen opbweb. Die Datei docker-compose.yml beschreibt den Produktivbetrieb, docker-compose.dev.yml ergänzt sie für die Entwicklung. Dieses Kapitel zeigt, welche Dienste es gibt, wie sie miteinander verbunden sind und wo welche Daten liegen.

Dienste

API und Worker verwenden dasselbe Image; der Worker startet nur mit einem anderen Befehl (./start-worker.sh). Das Image von garage-init trägt auch im Produktivbetrieb das Tag :dev.

Alle Dienste außer garage-init laufen mit restart: unless-stopped und starten nach einem Neustart des Hosts automatisch.

Startreihenfolge

1. db, redis und garage starten und melden sich über ihre Healthchecks als bereit.
2. garage-init wartet auf die Admin-API von Garage, legt fehlende Ressourcen an und schreibt die S3-Zugangsdaten in das Volume garage-credentials.
3. api startet, sobald db und redis gesund sind und garage-init erfolgreich beendet ist. Sie wartet bis zu 60 Sekunden auf die Datenbank, führt alembic upgrade head aus und legt das erste Administrator-Konto an, solange die Benutzertabelle leer ist.
4. worker startet nach der API, schreibt einen ersten Heartbeat und prüft die Verbindung zu allen Configservern.
5. frontend startet nach der API und wählt anhand der Zertifikate HTTPS oder HTTP.

Netze

Von außen erreichbar sind nur die beiden Ports des Frontends (FRONTEND_HTTP_PORT, FRONTEND_HTTPS_PORT). Datenbank, Redis und Garage haben im Produktivbetrieb keine veröffentlichten Ports. Die API hat keinen Weg nach außen; nur der Worker erreicht über opsi-net die opsi-Configserver und ihre Depots (HTTPS, Port 4447). Die tatsächlichen Docker-Netze heißen mit Projektpräfix, zum Beispiel opbweb_opsi-net.

Datenfluss

 Browser
    │  HTTPS 443 (oder HTTP 80)
    ▼
 ┌──────────────────────── frontend (nginx) ────────────────────────┐
 │  /           Weboberfläche (Vue-SPA)                             │
 │  /manual/    Handbuch Deutsch, /manual/en/ Englisch              │
 │  /health     statische Antwort „healthy“                         │
 │  /api        Proxy inkl. WebSocket ──────────────┐               │
 └──────────────────────────────────────────────────┼───────────────┘
                                   frontend-net     ▼
                                          ┌──── api :8000 ────┐
                                          │ Anmeldung, REST,  │
                                          │ Job-Events (WS)   │
                                          └───┬──────┬─────┬──┘
                         backend-net (intern) │      │     │ Job einreihen
                    ┌─────────────────────────┘      │     ▼
                    ▼                                ▼   redis ◄──────┐
                 db (MariaDB)            garage (S3, Bucket packages) │
                    ▲                                ▲                │
                    └──────────────┬─────────────────┘                │
                                   │                                  │
                              ┌── worker ──┐ ─────────────────────────┘
                              │ arq-Jobs,  │   holt Jobs, Heartbeat
                              │ Cron       │
                              └─────┬──────┘
                                    │ opsi-net, HTTPS :4447
                                    ▼
                    opsi-Configserver und Depots (opsiconfd)
                    JSON-RPC sowie WebDAV /repository, /workbench, /depot

Typische Abläufe:

• Bearbeiten in der Oberfläche: Browser → nginx → API → Datenbank und Objektspeicher. Der Worker ist nicht beteiligt.
• Lange Vorgänge (Import, Bauen, Installieren, Depot-Abgleich, Workbench, Dateimanager-Kopien): Die API legt einen Job in der Datenbank an und reiht ihn in Redis ein. Der Worker führt ihn aus und schreibt Fortschritt und Protokoll. Der Browser verfolgt den Job live per WebSocket über /api/jobs/{id}/events.
• Dateimanager in den Depots: Einzelne Dateioperationen (Auflisten, Lesen, Speichern) reicht die API direkt an den Worker weiter und wartet bis zu 60 Sekunden auf die Antwort. Antwortet der Worker nicht, erscheint „Worker nicht erreichbar.“ bzw. „Der Worker antwortet nicht.“
• Uploads: nginx nimmt Uploads bis 20 GB an und reicht sie ungepuffert an die API weiter. Die API legt sie im Objektspeicher unter uploads/ ab, ein Job verarbeitet sie.
• Downloads: Gebaute Pakete liefert die API aus dem Objektspeicher über kurzlebige Download-Links (2 Minuten gültig). Dateien von einem Depot kopiert zuerst ein Job nach downloads/.

Datenhaltung

Datenbank

MariaDB (Datenbank opbweb, Zeichensatz utf8mb4) enthält alle Metadaten: Benutzer, Protokoll, Produkte und Versionen mit control-Daten, Properties, Abhängigkeiten, die Dateiliste je Version mit SHA-256-Prüfsumme, Build-Ergebnisse, Jobs mit Protokollen, Snippets, Anwendungseinstellungen, die Configserver mit ihren Verbindungsdaten und Stufen sowie die Depots, von denen jedes genau einem Configserver zugeordnet ist. Das Passwort des technischen opsi-Benutzers liegt je Configserver verschlüsselt dort (RSA-OAEP): Die API verschlüsselt es mit secrets/opsi_key_public.pem, entschlüsseln kann nur der Worker mit secrets/opsi_key_private.pem.

Objektspeicher

Garage speichert alle Dateiinhalte im Bucket packages. Die Objekte sind nach Präfix gegliedert:

Wegen der Deduplizierung bleiben nach dem Löschen von Paketen oder Versionen Blobs zurück, die keine Paketdatei mehr verwendet. Sie entfernt ein Administrator gezielt über Bereinigen … im Systemstatus .

Physisch liegen die Daten in zwei Docker-Volumes: garage-meta (Metadaten in LMDB, Schlüssel, Bucket) und garage-data (Datenblöcke). Die Präfixe oben sind Objektschlüssel im Bucket, keine Verzeichnisse im Volume. Die Layout-Kapazität von 100 GB, die garage-init setzt, ist eine Gewichtung für Garage und keine Quota; maßgeblich ist der freie Platz auf dem Host.

Volumes

Docker legt die Volumes mit dem Präfix opbweb_ an, zum Beispiel opbweb_mariadb-data. Was davon zu sichern ist, steht unter Sicherung und Wiederherstellung .

Worker und Jobs

Der Worker arbeitet die Jobs aus Redis ab:

• bis zu 10 Jobs gleichzeitig, damit kurze Dateimanager-Aufrufe nicht hinter langen Installationen warten,
• Zeitlimit für Jobs: 8 Stunden (JOB_TIMEOUT_SECONDS), für die übrigen Worker-Funktionen 3600 Sekunden,
• Jobs für dasselbe Depot laufen nacheinander. Eine Depot-Sperre in Redis sorgt dafür; ein Job wartet bis zu 6 Stunden darauf, sonst bricht er mit „Depot ist zu lange durch einen anderen Job belegt.“ ab.

Zusätzlich laufen im Worker zeitgesteuerte Aufgaben:

Die Uhrzeit richtet sich nach TZ (Standard Europe/Berlin). Blobs und Build-Ergebnisse löscht die automatische Bereinigung nicht.

Handbuch

Dieses Handbuch ist Teil des Frontend-Images. Beim Bauen erzeugt eine eigene Hugo-Stufe die statische Website, nginx liefert sie aus:

• Deutsch unter /manual/,
• Englisch unter /manual/en/.

Das Buch-Symbol in der Kopfleiste öffnet die Sprache der Oberfläche in einem neuen Tab. Das Handbuch ist statisch und ohne Anmeldung erreichbar. Änderungen am Handbuch erscheinen erst mit einem neu gebauten Frontend-Image, siehe Build und Auslieferung .

Konfiguration

Zielgruppe: Technische Administration

Überblick

oPBWeb trennt die Konfiguration in drei Ebenen:

• .env im Projektverzeichnis: nicht geheime Einstellungen wie Ports, LDAP-Server, Zeitlimits. Docker Compose liest die Datei und setzt die Werte in docker-compose.yml ein.
• secrets/: alle Passwörter und Schlüssel als einzelne Dateien. Sie erreichen die Container als Docker-Secrets und werden nie in der .env abgelegt.
• Oberfläche: die Verbindungen zu den opsi-Configservern (URL, technischer Benutzer, Passwort, Stufe, CA-Zertifikat; in der Ansicht Depots) und die Vorgaben für neue Pakete. Diese Einstellungen liegen in der Datenbank, siehe Configserver und Einstellungen für neue Pakete .

Die .env und die fehlenden Secrets erzeugt ./setup-opbweb.sh, siehe Installation . Du kannst die .env danach direkt bearbeiten oder das Skript erneut aufrufen; die vorhandenen Werte sind dann die Vorgaben. Änderungen an .env werden mit dem nächsten ./start.sh wirksam; Docker Compose erzeugt dabei die betroffenen Container neu.

Variablen in der .env

Die Vorlage .env.example enthält alle Variablen der folgenden Tabellen; auskommentierte Zeilen zeigen den Standardwert. Fehlt eine Variable in der .env, gilt der Standardwert. setup-opbweb.sh schreibt die Variablen für Datenbank, Redis, Objektspeicher und CORS_ORIGINS nur, wenn sie schon in der bisherigen .env standen; Variablen, die das Skript nicht kennt, behält es am Ende der Datei.

Allgemein und Anmeldung

opsi und Pakete

BUILD_COMPRESSION wirkt nur auf neue Builds. Bereits gebaute Pakete behalten ihre Kompression bis zum nächsten Bauen.

Frontend und Images

Bleiben die drei Image-Variablen leer, gelten die lokal gebauten Images, siehe Image-Overrides und Registry-Mirror .

Datenbank, Redis, Objektspeicher

Diese Variablen musst du normalerweise nicht setzen. Sie sind für Sonderfälle da, etwa externe Dienste statt der mitgelieferten Container; in .env.example stehen sie auskommentiert.

Secrets

scripts/init-secrets.sh legt fehlende Secrets im Verzeichnis secrets/ an. setup-opbweb.sh und start.sh rufen das Skript auf, start.sh bei jedem Start. Vorhandene Dateien überschreibt es nie. Gib Inhalte von Secrets nicht in Tickets oder Logs weiter.

Das Verzeichnis secrets/ hat die Rechte 750, die Dateien 444; das Skript setzt sie bei jedem Lauf neu. Docker reicht die Secret-Dateien mit den Rechten des Hosts in die Container durch, deren Prozesse unter anderen Benutzern laufen (MariaDB, Redis, die Anwendung als appuser mit UID 1000). Mit 600 könnten sie die Dateien auf einem Linux-Host nicht lesen. Andere Benutzer des Hosts hält das Verzeichnis mit 750 fern.

Die S3-Zugangsdaten stehen nicht in secrets/. garage-init erzeugt den Schlüssel in Garage und schreibt ihn in das Volume garage-credentials.

Secrets nachträglich ändern

Nicht jedes Secret lässt sich nach dem ersten Start einfach austauschen:

Die Dateien sind schreibgeschützt (444). Zum Ändern hebst du den Schutz kurz auf und setzt ihn danach wieder, zum Beispiel:

chmod u+w secrets/ldap_bind_password.txt
# Datei bearbeiten
chmod 444 secrets/ldap_bind_password.txt

Das LDAP-Passwort kannst du auch mit ./setup-opbweb.sh neu eingeben. Die Dienste lesen die Secrets beim Start. Starte nach einer Änderung den Stack neu (./stop.sh, dann ./start.sh).

TLS und COOKIE_SECURE

Der Frontend-Container entscheidet bei jedem Start anhand der Dateien im Verzeichnis certs/:

setup-opbweb.sh sorgt außerhalb des Entwicklungs-Stacks immer für ein Zertifikat: mitgebracht (fullchain.pem und key.pem neben dem Skript), vorhanden oder self-signed, siehe Installation . Das Log des Containers zeigt die Wahl: „TLS-Zertifikat gefunden – HTTPS auf Port 443“ bzw. „Kein TLS-Zertifikat – HTTP auf Port 80“. fullchain.pem enthält das Serverzertifikat mit allen Zwischenzertifikaten. Den Zielport der Weiterleitung bekommt der Container als HTTPS_PORT (= FRONTEND_HTTPS_PORT).

Mit HTTPS sendet nginx den Header Strict-Transport-Security (ein Jahr). Browser, die oPBWeb einmal per HTTPS geöffnet haben, verweigern danach HTTP für diesen Hostnamen.

Nach dem Austausch eines Zertifikats (neue Dateien neben das Skript legen und ./setup-opbweb.sh --updateonly, oder direkt in certs/ ersetzen) genügt ein Neustart des Frontends:

docker restart opbweb-frontend

Zusätzlich lässt nginx pro Adresse höchstens 10 Anmeldeversuche pro Minute durch (kurzzeitig 10 mehr). Beide Grenzen setzen voraus, dass oPBWeb die echte Adresse der Clients sieht; steht ein weiterer Proxy davor oder verdeckt Docker die Adressen, teilen sich alle Benutzer eine Adresse.

COOKIE_SECURE steuert das Secure-Flag des Refresh-Cookies opbweb_refresh (7 Tage gültig, httpOnly, SameSite=Strict). Kommt die Anmeldung über HTTPS, setzt die API das Flag immer, auch bei false. Für die Einstellung gilt:

Ports

Beide Ports werden immer veröffentlicht, aber nur einer antwortet. Alle anderen Dienste sind im Produktivbetrieb nicht von außen erreichbar. Die zusätzlichen Ports des Entwicklungs-Stacks stehen unter Betrieb und Aktualisierung .

Ausgehend braucht der Worker HTTPS auf Port 4447 zum opsi-Configserver und zu den Depots.

Zeitlimits und Größen

Image-Overrides und Registry-Mirror

Ohne Overrides baut ./start.sh --build die eigenen Images lokal und nennt sie opbweb-backend:latest, opbweb-frontend:latest und opbweb-garage-init:1.0.0. Mit BACKEND_IMAGE, FRONTEND_IMAGE und GARAGE_INIT_IMAGE verwendest du stattdessen fertige Images, zum Beispiel aus der GitLab-Registry (siehe Build und Auslieferung ). setup-opbweb.sh setzt die drei Variablen, wenn du bei der Frage nach den Images r wählst; das Präfix kommt aus OPBWEB_REGISTRY. Von Hand sieht das so aus (Beispiel, an deine Registry anzupassen):

BACKEND_IMAGE=registry.example.com/gruppe/opsipackagebuilder-web/backend:<version>
FRONTEND_IMAGE=registry.example.com/gruppe/opsipackagebuilder-web/frontend:<version>
GARAGE_INIT_IMAGE=registry.example.com/gruppe/opsipackagebuilder-web/garage-init:latest

Danach holst du die Images und startest ohne --build:

docker login registry.example.com
docker compose pull
./start.sh

LDAP-Anmeldung

Zielgruppe: Technische Administration

Überblick

Neben lokalen Konten kann oPBWeb Benutzer gegen ein LDAP-Verzeichnis oder Active Directory anmelden. Die Rolle in oPBWeb ergibt sich dann aus den Gruppenmitgliedschaften im Verzeichnis. Du konfigurierst die Anbindung über LDAP_*-Variablen in der .env und das Passwort des Dienstkontos in secrets/ldap_bind_password.txt. In der Oberfläche gibt es dafür keine Einstellungen.

So läuft die Anmeldung ab

1. Gibt es in oPBWeb ein lokales Konto mit dem eingegebenen Benutzernamen, meldet oPBWeb ausschließlich lokal an. Das Verzeichnis wird nicht gefragt, auch wenn das Passwort falsch ist.
2. Sonst, bei LDAP_ENABLED=true, verbindet sich oPBWeb mit dem Dienstkonto (LDAP_BIND_DN) oder anonym, wenn kein Bind-DN gesetzt ist.
3. oPBWeb sucht mit LDAP_USER_FILTER unterhalb von LDAP_USER_SEARCH_BASE (leer: LDAP_BASE_DN). Die Suche muss genau einen Eintrag liefern.
4. Mit dem gefundenen DN und dem eingegebenen Passwort meldet sich oPBWeb als Benutzer an und prüft so das Passwort.
5. Aus dem Attribut memberOf bestimmt oPBWeb die Rolle (siehe unten). Ohne passende Gruppe gibt es keinen Zugang.
6. Beim ersten erfolgreichen Login legt oPBWeb das Konto mit der Herkunft „Verzeichnis (LDAP)“ an. Anzeigename (displayName), E-Mail (mail) und Rolle werden bei jeder Anmeldung neu aus dem Verzeichnis übernommen.

Lokale Konten bleiben also immer lokal, auch das erste Administrator-Konto. So kommst du auch bei einem Ausfall des Verzeichnisses noch an oPBWeb heran.

Variablen

Das Passwort des Dienstkontos steht nicht in der .env, sondern in secrets/ldap_bind_password.txt (von init-secrets.sh leer angelegt). Die Verbindung hat ein Zeitlimit von 10 Sekunden für den Aufbau und 15 Sekunden für Antworten.

Beispiel Active Directory

Ein Beispiel für eine Domäne example.local. Ersetze alle Namen durch deine Werte:

LDAP_ENABLED=true
LDAP_HOST=dc01.example.local
LDAP_PORT=636
LDAP_USE_SSL=true
LDAP_TLS_VERIFY=true
LDAP_CA_CERTS_FILE=/run/certs/ldap/ca.pem
LDAP_BASE_DN=dc=example,dc=local
LDAP_USER_SEARCH_BASE=ou=Benutzer,dc=example,dc=local
LDAP_USER_FILTER=(&(objectClass=user)(sAMAccountName={username}))
LDAP_BIND_DN=cn=svc-opbweb,ou=Dienstkonten,dc=example,dc=local
LDAP_ADMIN_GROUPS=cn=opbweb-admins,ou=Gruppen,dc=example,dc=local
LDAP_RELEASER_GROUPS=cn=opbweb-releaser,ou=Gruppen,dc=example,dc=local
LDAP_PACKAGER_GROUPS=cn=opbweb-packager,ou=Gruppen,dc=example,dc=local;cn=client-team,ou=Gruppen,dc=example,dc=local
LDAP_VIEWER_GROUPS=cn=opbweb-leser,ou=Gruppen,dc=example,dc=local

Weitere Filter, an dein Verzeichnis anzupassen:

Einrichten

1. Trage die Variablen wie oben in die .env ein.

2. Schreibe das Passwort des Dienstkontos in secrets/ldap_bind_password.txt (ohne Zeilenumbruch am Ende ist am sichersten; führende und abschließende Leerzeichen entfernt oPBWeb).

3. Lege bei einer eigenen Unternehmens-CA das CA-Zertifikat im PEM-Format vor dem Setup als ldap-ca.pem neben setup-opbweb.sh (das Setup verschiebt es nach certs/ldap/ldap-ca.pem und schlägt es als CA-Datei vor) oder direkt unter certs/ldap/ ab. Das Verzeichnis certs/ldap/ ist im Container als /run/certs/ldap/ schreibgeschützt eingebunden; LDAP_CA_CERTS_FILE gibt den Pfad im Container an. Ohne CA-Datei prüft oPBWeb gegen die Standard-CAs des Containers.

4. Starte den Stack neu, damit die API die neuen Werte und das Secret liest:

   ./stop.sh
   ./start.sh
   

5. Melde dich mit einem Verzeichniskonto an. Unter Benutzer und Rollen erscheint das Konto mit der Herkunft „Verzeichnis (LDAP)“ und der zugeordneten Rolle.

Gruppen und Rollen

• In jeder LDAP_*_GROUPS-Variablen stehen ein oder mehrere vollständige Gruppen-DNs, getrennt durch ;.
• oPBWeb vergleicht die DNs ohne Rücksicht auf Groß- und Kleinschreibung, aber sonst exakt mit den Werten aus memberOf.
• Die höchste Rolle gewinnt: Administrator vor Releaser vor Packager vor Leser.
• Keine passende Gruppe, kein Zugang: Die Anmeldung scheitert mit „Keine Berechtigung für oPBWeb (keine passende Gruppe).“ Ist keine der vier Variablen gesetzt, kann sich niemand über LDAP anmelden.
• Verschachtelte Gruppen löst oPBWeb nicht auf; maßgeblich ist nur, was memberOf direkt liefert. Die primäre Gruppe eines AD-Kontos (meist „Domänen-Benutzer“) steht nicht in memberOf.

Was die Rollen im Einzelnen dürfen, beschreibt Benutzer und Rollen .

Verhalten von Verzeichniskonten

Gleichnamige Konten: Existiert ein lokales Konto mit demselben Namen wie ein Verzeichniskonto, gilt immer das lokale Konto.

Fehlersuche

Fehler bei Verbindung und Suche schreibt die API ins Log:

docker logs opbweb-api 2>&1 | grep -i "LDAP search failed"

Typische Ursachen sind ein Hostname, der nicht zum Zertifikat passt, eine fehlende oder falsche CA-Datei (Pfad im Container, nicht auf dem Host), ein leeres secrets/ldap_bind_password.txt oder ein Domänencontroller, der vom Docker-Host aus nicht erreichbar ist.

Zum Gegenprüfen der Suche eignet sich ldapsearch auf einem Rechner mit den OpenLDAP-Werkzeugen. Beispiel, an deine Werte anzupassen:

ldapsearch -H ldaps://dc01.example.local:636 \
  -D "cn=svc-opbweb,ou=Dienstkonten,dc=example,dc=local" -W \
  -b "ou=Benutzer,dc=example,dc=local" \
  "(&(objectClass=user)(sAMAccountName=mmuster))" memberOf displayName mail

Die ausgegebenen memberOf-Werte kannst du direkt in die LDAP_*_GROUPS-Variablen übernehmen.

Betrieb und Aktualisierung

Zielgruppe: Technische Administration

Überblick

Für den täglichen Betrieb brauchst du zwei Skripte im Projektverzeichnis: start.sh und stop.sh. Dieses Kapitel beschreibt außerdem, wo du Logs und Zustand der Dienste findest, wie du oPBWeb aktualisierst und was du auf der opsi-Seite beachten musst. Alle Befehle führst du im Projektverzeichnis aus.

Stack starten und stoppen

start.sh

./start.sh [--build] [--logs] [--dev | --test] [--lang de|en]

Ablauf: Das Skript bricht ab, wenn .env fehlt („.env fehlt – bitte ./setup-opbweb.sh ausführen (im Entwickler-Checkout: ./setup-opbweb.sh –dev).“), ruft scripts/init-secrets.sh auf, führt docker compose up -d aus und zeigt mit docker compose ps den Status. Laufende Container, deren Konfiguration sich nicht geändert hat, bleiben dabei unberührt. start.sh holt keine neuen Fremd-Images; dafür siehe Aktualisieren .

stop.sh

./stop.sh

Das Skript hat keine Optionen. Es führt docker compose down mit docker-compose.yml und den vorhandenen Overlays (docker-compose.dev.yml, docker-compose.test.yml) aus und stoppt damit Produktiv-, Dev- und Testdienste gleichermaßen. Container und Netze werden entfernt, die Volumes mit Datenbank und Objektspeicher bleiben erhalten.

Einzelne Dienste neu starten

docker restart opbweb-worker
docker restart opbweb-frontend   # z. B. nach einem Zertifikatswechsel

Ein Neustart des Workers unterbricht laufende Jobs. Prüfe vorher unter Jobs, ob gerade Installationen laufen.

Container

Den Zustand zeigt docker compose ps (Produktiv-Stack) bzw. docker compose ps -a einschließlich beendeter Container wie garage-init.

Logs

docker logs -f --tail=100 opbweb-api
docker logs -f --tail=100 opbweb-worker
docker compose logs -f --tail=50          # alle Dienste

Den Detailgrad von api und worker steuert LOG_LEVEL in der .env (DEBUG, INFO, WARNING, ERROR; Standard INFO). Eine Änderung wird mit dem nächsten ./start.sh wirksam.

Bei der LDAP-Anmeldung protokolliert die API, woran eine Anmeldung scheitert: Benutzer nicht gefunden (null Treffer für den Suchfilter) und falsches Passwort auf Stufe INFO, keine Gruppe mit einer Rolle auf Stufe WARNING. Mit LOG_LEVEL=WARNING oder ERROR siehst du die ersten beiden Fälle also nicht. Zum Beispiel:

docker logs opbweb-api 2>&1 | grep "LDAP login"

python-opsi und der HTTP-Client httpx geben nur Warnungen und Fehler aus. Ihre Debug-Ausgaben schaltet erst DEBUG=true ein; das startet die API aber auch mit Hot Reload und ist nur für die Entwicklung gedacht, siehe Konfiguration .

Das vollständige Protokoll jedes Jobs findest du zusätzlich in der Oberfläche unter Jobs, siehe Jobs .

Zustand prüfen

Für ein einfaches Monitoring eignet sich /api/health:

curl -fsS https://opbweb.example.local/api/health

Die Detailprüfung bewertet so:

Administratoren sehen im Systemstatus zusätzlich Tabellengrößen der Datenbank, die Belegung des Objektspeichers und den Bucket-Browser, siehe Systemstatus .

Zeitgesteuerte Aufgaben

Der Worker führt diese Aufgaben selbst aus; einen Cron-Eintrag auf dem Host brauchst du nicht.

Die Zeiten der opsi-Prüfung und des Aufräumens stellst du unter Einstellungen → Worker ein; sie gelten ohne Neustart.

Nicht mehr verwendete Paketdateien (Blobs) und Build-Ergebnisse entfernt die automatische Aufgabe nicht. Das macht ein Administrator bei Bedarf mit Bereinigen … im Systemstatus : erst ein Probelauf, dann das bestätigte Löschen.

Aktualisieren

1. Sichere Datenbank und Objektspeicher, siehe Sicherung und Wiederherstellung . Datenbankmigrationen lassen sich nicht ohne Weiteres rückgängig machen.

2. Prüfe unter Jobs, dass keine Installationen laufen.

3. Hole den neuen Stand, zum Beispiel mit git pull oder mit einem neuen Stack-ZIP , das du über die Installation entpackst. .env, secrets/ und certs/ enthält das ZIP nicht, sie bleiben erhalten.

4. Bringe die .env auf den neuen Stand:

   ./setup-opbweb.sh --updateonly
   

   Das Skript übernimmt alle vorhandenen Werte, ergänzt neue Variablen mit ihrem Standardwert und legt neue Secrets an; vorhandene Secrets bleiben unverändert. Willst du dabei Werte ändern, rufe ./setup-opbweb.sh ohne Option auf.

5. Aktualisiere die Images und starte den Stack:

   • Lokal gebaute Images:

     ./start.sh --build
     

     --build nutzt den Build-Cache von Docker. Sicherheitsupdates der Basis-Images und der Systempakete kommen so nicht unbedingt an. Bau deshalb bei einem Sicherheitsupdate ohne Cache und mit frischen Basis-Images, danach ./start.sh:

     docker compose build --pull --no-cache
     

   • Images aus einer Registry: Trage die neuen Image-Versionen ein, entweder interaktiv mit ./setup-opbweb.sh (Fragen nach den Versionen der Images; die Vorgabe ist die bisherige Version) oder direkt in BACKEND_IMAGE, FRONTEND_IMAGE und GARAGE_INIT_IMAGE in der .env. --updateonly behält die bisherigen Versionen. Liegt eine versions.env daneben (Stack-ZIP), sind ihre Versionen die Vorgaben, auch für --updateonly; das Entpacken eines neuen ZIPs und --updateonly stellen die Images also auf dessen Versionen um. Danach:

     docker compose pull
     ./start.sh
     

     Verwendest du die Tags latest, genügen docker compose pull und ./start.sh.

6. Die API führt beim Start automatisch alembic upgrade head aus. Prüfe danach das Log:

   docker logs opbweb-api 2>&1 | head -50
   

7. Kontrolliere in der Oberfläche die Versionen in der Statusleiste („Frontend …“, „Backend …“) und den Systemstatus.

Neue Versionen der Fremd-Images (MariaDB 11.4, Redis 7, Garage v2.2.0) innerhalb ihrer Tags holt start.sh nicht automatisch. Beispiel, bei Bedarf auszuführen:

docker compose pull db redis garage
./start.sh

Um auch die Basis-Images der eigenen Images (node, nginx, python) zu aktualisieren, baue mit docker compose build --pull und starte danach mit ./start.sh. Das betrifft nur lokal gebaute Images.

Versionierung

Backend und Frontend haben getrennte Versionsnummern nach dem Schema MAJOR.MINOR.PATCH (Meilenstein, Phase, Fehlerbehebung). Die Oberfläche zeigt beide in der Statusleiste, /api/health liefert die Backend-Version.

Gesetzt werden die Versionen mit set-version.sh; welche Dateien betroffen sind, steht in version.yaml (Backend: backend/src/core/version.py und backend/pyproject.toml, Frontend: frontend/package.json über npm version).

Eine geänderte Versionsdatei auf dem Standard-Branch löst in der GitLab-CI den Build des passenden Images aus, siehe Build und Auslieferung .

opsiconfd: admin-networks

Der Worker ruft opsiconfd mit Admin-Rechten auf. Ist in der Konfiguration von opsiconfd die Option admin-networks gesetzt, muss die Absenderadresse des Workers darin liegen, sonst antwortet opsiconfd mit HTTP 403.

Welche Adresse opsiconfd sieht, hängt vom Standort ab (abgeleitet aus dem Docker-Netzverhalten, bitte im opsiconfd-Log gegenprüfen):

• oPBWeb auf dem Configserver selbst: die Adresse des Workers im Docker-Netz opbweb_opsi-net. Das Subnetz zeigt:

  docker network inspect opbweb_opsi-net --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'
  

• oPBWeb auf einem anderen Host: in der Regel die Adresse des Docker-Hosts, weil Docker ausgehenden Verkehr maskiert.

./stop.sh entfernt die Docker-Netze; beim nächsten Start kann opbweb_opsi-net ein anderes Subnetz bekommen. Trage daher entweder den gesamten Adressbereich ein, aus dem Docker seine Netze vergibt, oder prüfe das Subnetz nach jedem Neustart. Die Syntax der Option beschreibt das opsi-Handbuch; nach der Änderung muss opsiconfd neu starten.

Entwicklungs-Stack

Der Entwicklungs-Stack ist für die Weiterentwicklung gedacht, nicht für den Betrieb. In einem frischen Entwickler-Checkout legst du zuerst die .env an (aus .env.example, ohne Rückfragen) und startest dann mit lokal gebauten Images:

./setup-opbweb.sh --dev
./start.sh --dev --build

Er ergänzt den Produktiv-Stack um Hot Reload (Quellen als Bind-Mounts, DEBUG=true), zwei nachgebaute opsiconfd, eine Vorschau des Handbuchs und die Launcher-ZIPs. API und Worker laufen mit dem Image opbweb-backend:dev.

Jeder Mock bildet einen Configserver und ein Depot nach, einschließlich Installieren, Deinstallieren und WebDAV. opbweb-opsi-mock ist das erste opsi-System: Solange kein Configserver eingerichtet ist, trägt die API ihn beim Start als „opsiconfd-Mock“ mit der Stufe Test ein (URL http://opsi-config.mock:4447, Benutzer opsiadm, Passwort mock, ohne TLS-Prüfung). opbweb-opsi-mock2 ist ein zweites, unabhängiges opsi-System für Tests mit mehreren Configservern; er wird nicht automatisch eingetragen. Wer ihn in der Oberfläche nutzen will, legt ihn unter Depots mit + an (URL http://opsi-config2.mock:4447, Benutzer opsiadm, Passwort mock, TLS-Prüfung aus).

Die End-to-End-Tests tragen beide Mocks selbst als Configserver ein (als „t-Mock 1“ und „t-Mock 2“, falls noch nicht vorhanden), entfernen sie danach wieder und arbeiten nur auf deren Depots. Sie setzen nicht voraus, dass der Mock der einzige oder voreingestellte Configserver ist, und laufen auch dann, wenn zusätzlich ein echter opsi-Server eingerichtet ist. Die Handbuch-Vorschau aktualisiert sich nicht von selbst; lade die Seite nach einer Änderung neu.

Sicherung und Wiederherstellung

Zielgruppe: Technische Administration

Überblick

Die Daten von oPBWeb liegen an zwei Stellen, die zusammengehören: In der Datenbank stehen alle Metadaten, im Objektspeicher die Dateiinhalte. Die Datenbank verweist über SHA-256-Prüfsummen und Schlüssel auf Objekte im Speicher (blobs/…, artifacts/…). Eine Sicherung ist nur brauchbar, wenn beide Teile aus demselben Zeitpunkt stammen und die passenden Secrets dabei sind.

Was du sicherst

Merke dir außerdem den Versionsstand von oPBWeb (Git-Commit oder Versionen aus der Statusleiste). Eine Datenbank lässt sich nur mit derselben oder einer neueren oPBWeb-Version weiterverwenden.

Sicherung erstellen

Damit Datenbank und Objektspeicher denselben Stand haben, stoppst du zuerst die Dienste, die Daten verändern, sicherst dann die Datenbank und anschließend bei gestopptem Stack den Objektspeicher.

1. Prüfe unter Jobs, dass keine Jobs laufen oder warten.

2. Lege ein geschütztes Sicherungsverzeichnis an:

   mkdir -p -m 700 backup
   

3. Stoppe Frontend, Worker und API. Datenbank und Objektspeicher laufen weiter:

   docker stop opbweb-frontend opbweb-worker opbweb-api
   

4. Sichere die Datenbank:

   docker exec opbweb-db sh -c 'mariadb-dump -uroot -p"$(cat /run/secrets/db_root_password)" --single-transaction opbweb' > backup/opbweb.sql
   

   Das Root-Passwort liest der Befehl im Container aus dem Docker-Secret; es erscheint nicht auf der Kommandozeile des Hosts.

5. Stoppe den Stack:

   ./stop.sh
   

6. Sichere die beiden Garage-Volumes (Beispiel mit einem Alpine-Hilfscontainer):

   docker run --rm -v opbweb_garage-meta:/v:ro -v "$PWD/backup":/b alpine tar czf /b/garage-meta.tgz -C /v .
   docker run --rm -v opbweb_garage-data:/v:ro -v "$PWD/backup":/b alpine tar czf /b/garage-data.tgz -C /v .
   

7. Sichere Secrets, Konfiguration und Zertifikate:

   tar czf backup/config.tgz secrets .env certs
   

8. Starte den Stack wieder:

   ./start.sh
   

Übertrage den Inhalt von backup/ anschließend auf dein Sicherungsziel. Die Ausfallzeit hängt vor allem von der Größe des Objektspeichers ab.

Wenn eine kurze Unterbrechung des ganzen Stacks ohnehin möglich ist, kannst du statt des Dumps auch das Volume opbweb_mariadb-data bei gestopptem Stack genauso wie die Garage-Volumes sichern. Dann gehören zur Datenbank zwingend die Passwörter aus secrets/db_password.txt und secrets/db_root_password.txt, die im Volume hinterlegt sind.

Wiederherstellen

Die Reihenfolge ist wichtig: erst Secrets und Konfiguration, dann der Objektspeicher, dann die Datenbank, zuletzt der Start.

1. Stack stoppen.

   ./stop.sh
   

2. Programmstand bereitstellen. Checke dieselbe oPBWeb-Version aus, die zur Sicherung gehört (oder eine neuere). Verwendest du Images aus einer Registry, stehen deren Versionen in der gesicherten .env (BACKEND_IMAGE usw.).

3. Secrets, .env und Zertifikate zurückspielen. Verwende die originalen Dateien aus der Sicherung, nicht neu erzeugte:

   tar xzf backup/config.tgz
   chmod 750 secrets && chmod 444 secrets/*
   

   Die Dateien brauchen die Rechte 444, damit die Prozesse in den Containern sie lesen können; start.sh setzt die Rechte über init-secrets.sh ohnehin bei jedem Start.

4. Objektspeicher zurückspielen. Entferne die vorhandenen Garage-Volumes einschließlich der S3-Zugangsdaten und spiele die Sicherung ein:

   docker volume rm opbweb_garage-meta opbweb_garage-data opbweb_garage-credentials
   docker volume create opbweb_garage-meta
   docker volume create opbweb_garage-data
   docker run --rm -v opbweb_garage-meta:/v -v "$PWD/backup":/b alpine tar xzf /b/garage-meta.tgz -C /v
   docker run --rm -v opbweb_garage-data:/v -v "$PWD/backup":/b alpine tar xzf /b/garage-data.tgz -C /v
   

   Das Volume garage-credentials musst du entfernen, damit garage-init die Zugangsdaten aus dem zurückgespielten Schlüssel neu schreibt. Bleibt ein altes Volume liegen, passen die Zugangsdaten nicht zum Objektspeicher. Im Log von garage-init erscheint beim nächsten Start „Credential files missing, writing from existing key…“.

5. Datenbank zurückspielen. Entferne das Datenbank-Volume, starte nur die Datenbank und spiele den Dump ein:

   docker volume rm opbweb_mariadb-data
   docker compose up -d db
   docker compose ps db        # warten, bis der Status "healthy" lautet
   docker exec -i opbweb-db sh -c 'mariadb -uroot -p"$(cat /run/secrets/db_root_password)" opbweb' < backup/opbweb.sql
   

   MariaDB legt beim ersten Start des leeren Volumes die Datenbank opbweb und den Anwendungsbenutzer mit den Passwörtern aus secrets/ an. Hast du das Volume statt eines Dumps gesichert, spielst du es wie die Garage-Volumes zurück.

6. Stack starten.

   ./start.sh
   

   Die API führt fehlende Migrationen aus, falls der Programmstand neuer ist als die Sicherung. Ein erstes Administrator-Konto legt sie nicht an, weil die Benutzertabelle aus der Sicherung gefüllt ist.

7. Prüfen.

   • Systemstatus: alle Dienste OK. Als Administrator prüfst du unter Objektspeicher, dass keine fehlenden Blobs gemeldet werden; fehlende Blobs deuten auf Datenbank und Objektspeicher aus unterschiedlichen Zeitpunkten hin.
   • Depots → Configserver: für jeden Configserver Verbindung testen. Schlägt die Anmeldung fehl, passt opsi_key_private.pem nicht zur Datenbank; trage dann das Passwort des technischen Benutzers neu ein.
   • Öffne ein Paket und lade eine Datei bzw. ein gebautes Paket herunter.

Jobs, die zum Zeitpunkt der Sicherung warteten oder liefen, setzt oPBWeb nach der Wiederherstellung nicht fort. Starte sie bei Bedarf neu.

Konsistenz

Bei regelmäßigen Sicherungen hilft eine feste Reihenfolge in einem Skript, das alle Schritte des Abschnitts Sicherung erstellen nacheinander ausführt.

Fehlersuche

Zielgruppe: Technische Administration

Überblick

Dieses Kapitel ordnet typische Störungen nach Symptom. Zu jedem Symptom findest du die wahrscheinliche Ursache und die Abhilfe. Am Ende steht eine Tabelle mit wichtigen Fehlermeldungen. Die Meldungen des Servers erscheinen in der Sprache der Oberfläche; dieses Kapitel zitiert sie in der deutschen Fassung.

Erste Anlaufstellen

Stack startet nicht

Anmeldung

„Benutzername oder Passwort falsch.“ Bei lokalen Konten zählt jeder Fehlversuch. Nach 5 Fehlversuchen von derselben Adresse ist das Konto für diese Adresse 15 Minuten gesperrt: „Konto gesperrt bis HH:MM Uhr.“ Von anderen Adressen kann sich der Benutzer weiter anmelden; für alle gesperrt wird das Konto erst nach 50 Fehlversuchen. Nach 20 Fehlversuchen von einer Adresse (über alle Konten) antwortet oPBWeb mit „Zu viele fehlgeschlagene Anmeldungen von dieser Adresse.“ Ein Administrator hebt die Sperre unter Benutzer und Rollen mit Sperre aufheben auf; auch Passwort setzen entsperrt das Konto. Siehe Benutzer und Rollen .

Passwort des einzigen Administrators vergessen. Ein Werkzeug zum Zurücksetzen ohne Anmeldung gibt es nicht. Ein anderer Administrator (lokal oder über eine LDAP-Gruppe) kann das Passwort setzen. Lege deshalb früh ein zweites Administrator-Konto an. secrets/admin_password.txt wirkt nur beim allerersten Start.

„Konto ist deaktiviert.“ Das Konto ist in oPBWeb deaktiviert. Ein Administrator aktiviert es unter Benutzer und Rollen wieder.

LDAP-Meldungen („Verzeichnisdienst nicht erreichbar.“, „Keine Berechtigung für oPBWeb (keine passende Gruppe).“): siehe LDAP-Anmeldung .

Nach dem Neuladen der Seite oder nach etwa 15 Minuten wieder abgemeldet. Die Sitzung wird über das Cookie opbweb_refresh erneuert. Steht COOKIE_SECURE=true, während oPBWeb nur per HTTP erreichbar ist, speichert der Browser das Cookie nicht. Setze COOKIE_SECURE passend zum Protokoll und starte mit ./start.sh neu.

„Sitzung abgelaufen.“ Das Token ist ungültig oder wurde widerrufen, zum Beispiel nach einer Abmeldung, nach 7 Tagen ohne Erneuerung oder nach einem Wechsel von secrets/jwt_secret_key.txt. Neu anmelden.

Verbindung zum opsi-Server

Den Zustand zeigt die Zeile opsi-Server im Systemstatus, mit einem Eintrag je Configserver; dazu kommt der farbige Punkt vor jedem Configserver in der Ansicht Depots. Der Worker prüft alle Configserver alle 5 Minuten; nach einer Änderung kannst du unter Depots → Configserver mit Verbindung testen sofort prüfen. Die Einrichtung beschreibt Configserver .

Erreichbarkeit aus dem Worker-Container prüfen (Beispiel; -k nur für diesen Test, weil die opsi-CA im Container nicht bekannt ist):

docker exec opbweb-worker curl -sk -o /dev/null -w '%{http_code}\n' https://opsi.example.local:4447/

Eine HTTP-Statusnummer zeigt, dass Namensauflösung und Verbindung funktionieren. Ein Fehler wie „Could not resolve host“ oder ein Timeout weist auf DNS oder Firewall hin.

Bauen

Fehler beim Bauen stehen im Protokoll des Jobs „Bauen“ unter Jobs.

Installieren und Deinstallieren

Worker nicht erreichbar

Symptome: Im Systemstatus meldet die Zeile Worker „kein Lebenszeichen“ oder „letztes Lebenszeichen vor N s“; Jobs bleiben im Zustand wartend; der Dateimanager unter Depots meldet „Worker nicht erreichbar.“ oder „Der Worker antwortet nicht.“

Ursachen und Abhilfe:

1. Prüfe, ob der Container läuft: docker compose ps worker.
2. Lies das Log: docker logs --tail=200 opbweb-worker. Häufige Ursachen sind fehlende Secrets, keine Verbindung zu Redis oder ein Fehler beim Start.
3. Starte den Worker neu: docker restart opbweb-worker.
4. „Der Worker antwortet nicht.“ kann auch bedeuten, dass der Worker ausgelastet ist. Er führt höchstens 10 Jobs gleichzeitig aus; Dateimanager-Aufrufe warten höchstens 60 Sekunden. Warte laufende Jobs ab und versuche es erneut.

Objektspeicher

Uploads und Zeitlimits

Hochgeladene Dateien, die nicht verarbeitet wurden, löscht der Worker nach 24 Stunden.

HTTPS und Zertifikate

Wichtige Fehlermeldungen

Build und Auslieferung

Zielgruppe: Technische Administration

Überblick

oPBWeb besteht aus drei eigenen Images: Backend (für api und worker), Frontend (nginx mit Oberfläche und Handbuch) und garage-init. Du baust sie entweder lokal mit ./start.sh --build oder lässt sie von der GitLab-CI bauen und in die Projekt-Registry schieben. Die CI erzeugt außerdem das Handbuch als PDF. Dieses Kapitel beschreibt die Images, die Pipeline und wie du das Handbuch lokal baust.

Images

Alle Dockerfiles verwenden das Projektverzeichnis als Build-Kontext. .dockerignore hält unter anderem secrets/, certs/, .env, node_modules/ sowie die Hugo-Ausgaben und manual/.doc-state/ aus dem Kontext heraus.

Backend

backend/Dockerfile, ein Image für api und worker:

Lokal entsteht opbweb-backend:latest (Produktion) bzw. opbweb-backend:dev (Dev-Stack).

Frontend

frontend/Dockerfile:

Das Handbuch ist damit fester Bestandteil des Frontend-Images. Eine Änderung am Handbuch erscheint in der Weboberfläche erst mit einem neu gebauten Frontend-Image.

garage-init

garage/Dockerfile.garage-init: alpine:3.21 mit bash, jq und curl sowie dem Skript garage/init-garage.sh. Lokal heißt das Image opbweb-garage-init:1.0.0. Die Version ist fest und ändert sich nur, wenn sich Dockerfile oder Skript ändern.

Netzzugang beim Bauen

Für einen Build braucht der Host Zugriff auf Docker Hub (Basis-Images), GitHub (python-opsi, Hugo-Module), PyPI, die npm-Registry und den Go-Modul-Proxy proxy.golang.org (Docsy). Der Launcher kommt ohne fremde Go-Module aus.

GitLab-CI-Pipeline

Die Pipeline steht in .gitlab-ci.yml. Die Jobs laufen auf Runnern mit dem Tag dind und bauen mit Docker-in-Docker.

Stufen und Jobs

Die Versionen liest die Pipeline aus backend/src/core/version.py und frontend/package.json. Die Images landen in der Registry des Projekts unter <Registry>/<Projektpfad>/backend, …/frontend und …/garage-init (Pfad in Kleinbuchstaben). Die Registry-Adresse steht als CI_REGISTRY in .gitlab-ci.yml.

Stack-ZIP

Der Job stack-release packt alles, was ein Docker-Host zum Einrichten und Starten mit den Registry-Images braucht, in oPBWeb-Stack-<Pipeline-Nr>.zip, ohne Quellen:

docker-compose.dev.yml fehlt bewusst: Der Entwicklungs-Stack bindet die Quellen ein. Ohne Quellen bietet setup-opbweb.sh keinen lokalen Build an, und start.sh --dev bricht mit einem Hinweis ab. Das ZIP liegt im generischen Paket stack/<Pipeline-Nr> der Projekt-Registry und ist im Release oPBWeb Stack (Tag stack-latest) verlinkt, das jeder Lauf neu anlegt.

Images aus der Registry verwenden

Auf dem Zielhost musst du die Images dann nicht bauen. Wähle in ./setup-opbweb.sh bei der Frage nach den Images r, gib das Registry-Präfix (Vorgabe: die Registry dieser CI, abweichend über OPBWEB_REGISTRY) und die gewünschten Versionen an. Das Skript trägt BACKEND_IMAGE, FRONTEND_IMAGE und GARAGE_INIT_IMAGE in die .env ein. Danach holst du die Images (verlangt die Registry eine Anmeldung, vorher docker login) mit docker compose pull und startest mit ./start.sh ohne --build. Details stehen unter Installation und Konfiguration .

Wann welcher Job läuft

Auf dem Standard-Branch des Projekts (in GitLab unter Einstellungen → Repository festgelegt, z. B. master oder main) starten die Jobs automatisch, wenn sich ihre Auslöser ändern:

Ein neues Backend- oder Frontend-Image entsteht also typischerweise durch das Setzen einer neuen Version mit set-version.sh, siehe Betrieb und Aktualisierung . Eine reine Handbuchänderung erzeugt neue PDFs, aber kein neues Frontend-Image; dafür brauchst du eine neue Frontend-Version oder einen manuellen Lauf von build-frontend.

Pipeline manuell starten

Beim manuellen Start einer Pipeline in GitLab wählst du über die Eingabe run_job, was laufen soll:

Die Scans prüfen das Image mit der aktuellen Versionsnummer aus der Registry. Es muss also vorher gebaut und hochgeladen worden sein.

Container-Scanning

Die Scan-Jobs nutzen die GitLab-Vorlage Jobs/Container-Scanning.gitlab-ci.yml mit der Schwelle HIGH. Die Berichte stehen als Job-Artefakte bereit (gl-container-scanning-report-backend.json, gl-container-scanning-report-frontend.json) und erscheinen in den Sicherheitsberichten von GitLab.

Handbuch-PDFs

Der Job build-manuals läuft im Image python:3, installiert WeasyPrint, Hugo extended in der Version 0.154.5 (Variable HUGO_VERSION), Go, Node.js und das GitLab-release-cli und ruft dann manual/build-pdf.sh output auf. Er erzeugt eine PDF-Datei pro Teil und Sprache:

<Version> ist die Frontend-Version. Der Job lädt die PDFs in das generische Paket manuals/latest der Projekt-Registry; gleichnamige Dateien löscht er vorher. Danach legt er das Release manuals-latest („oPBWeb Handbücher“) neu an, mit je einem Link pro PDF („DE: Installation“, „EN: User Guide“ usw.) sowie Build-Datum, Pipeline-Nummer und Frontend-Version in der Beschreibung. Zusätzlich bleiben die PDFs 30 Tage als Job-Artefakte erhalten.

Handbuch lokal bauen

Die Quellen liegen unter manual/ (Hugo mit dem Theme Docsy als Hugo-Modul). Deutsche Texte stehen in manual/content/de/, englische in manual/content/en/, Bilder unter manual/static/images/<Sprache>/. Auf dem Host musst du dafür nichts installieren; alle Wege laufen in Containern.

Vorschau im Dev-Stack

Der Entwicklungs-Stack startet den Dienst manual-dev (hugo server im Image hugomods/hugo:exts-0.154.5). Die Vorschau erreichst du über den Vite-Proxy:

http://localhost:3100/manual/

Live-Reload ist abgeschaltet; lade die Seite nach einer Änderung neu. Bei Problemen hilft docker logs opbweb-manual-dev. Den Dev-Stack beschreibt Betrieb und Aktualisierung .

Website wie im Image bauen

Das Frontend-Image baut das Handbuch selbst. Für eine Prüfung ohne Image kannst du denselben Befehl in einem Container ausführen (Beispiel):

docker run --rm -v "$PWD/manual":/src -w /src hugomods/hugo:exts-0.154.5 \
  sh -c 'npm ci --no-audit --no-fund && hugo --minify --baseURL /manual/'

Das Ergebnis liegt in manual/public/. Das Verzeichnis ist von Git und vom Docker-Build ausgeschlossen.

PDFs bauen

manual/build-pdf.sh braucht Hugo extended, Go, npm und Python mit WeasyPrint. Führe es wie in der CI in einem Container aus. Das Skript liest die Versionen aus backend/ und frontend/, daher bindest du das ganze Projektverzeichnis ein. Beispiel für einen x86-64-Host, angelehnt an den CI-Job:

docker run --rm -v "$PWD":/work -w /work python:3 bash -c '
  pip install --quiet weasyprint &&
  apt-get update -qq && apt-get install -y -qq wget git golang nodejs npm > /dev/null &&
  wget -q https://github.com/gohugoio/hugo/releases/download/v0.154.5/hugo_extended_0.154.5_linux-amd64.deb &&
  dpkg -i hugo_extended_0.154.5_linux-amd64.deb > /dev/null &&
  manual/build-pdf.sh output'

Die PDFs liegen danach in output/. Auf einem ARM-Rechner nimmst du das passende Hugo-Paket (linux-arm64) oder startest den Container mit --platform linux/amd64. Die im Container erzeugten Dateien gehören root.

Für den PDF-Druck erzeugt Hugo zusätzlich die Print-Ausgabe von Docsy; manual/scripts/combine_print_html.py setzt daraus je Teil und Sprache eine HTML-Datei mit Titelseite zusammen, die WeasyPrint in ein PDF umwandelt.

Versionen von Hugo und Docsy

Docsy ist in manual/go.mod auf v0.15.0 festgelegt, passend zu Hugo 0.154.5, das die CI für die PDFs verwendet. Aktualisiere Docsy nur zusammen mit einer dazu passenden Hugo-Version und prüfe danach Website und PDFs.