Technische Administration on oPBWeb Handbuch

Architektur

Mon, 01 Jan 0001 00:00:00 +0000

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

Dienst	Container	Image	Aufgabe
frontend	`opbweb-frontend`	`opbweb-frontend:latest` (nginx:stable-alpine)	liefert die Weboberfläche und das Handbuch aus, leitet `/api` an die API weiter; einziger Dienst mit veröffentlichten Ports
api	`opbweb-api`	`opbweb-backend:latest` (python:3.13-slim)	REST-API und WebSocket (FastAPI/uvicorn auf Port 8000), Anmeldung, Datenbankmigrationen beim Start, erstes Administrator-Konto
worker	`opbweb-worker`	`opbweb-backend:latest`	führt alle Jobs aus (arq auf Redis); einziger Dienst, der mit den opsi-Configservern spricht und deren Passwörter entschlüsselt
db	`opbweb-db`	`mariadb:11.4`	alle Anwendungsdaten (Pakete, Versionen, Benutzer, Jobs, Protokoll, Einstellungen)
redis	`opbweb-redis`	`redis:7-alpine`	Job-Warteschlange, Heartbeat des Workers, Status der opsi-Verbindung, Sperrliste abgemeldeter Tokens, Depot-Sperren
garage	`opbweb-garage`	`dxflrs/garage:v2.2.0`	S3-kompatibler Objektspeicher (ein Knoten, Replikationsfaktor 1) für Dateiinhalte und gebaute Pakete
garage-init	`opbweb-garage-init`	`opbweb-garage-init:1.0.0` (alpine:3.21)	richtet bei jedem Start Layout, Zugangsschlüssel `opbweb` und Bucket `packages` ein und beendet sich dann

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.

Konfiguration

Mon, 01 Jan 0001 00:00:00 +0000

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.

LDAP-Anmeldung

Mon, 01 Jan 0001 00:00:00 +0000

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

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.
Sonst, bei LDAP_ENABLED=true, verbindet sich oPBWeb mit dem Dienstkonto (LDAP_BIND_DN) oder anonym, wenn kein Bind-DN gesetzt ist.
oPBWeb sucht mit LDAP_USER_FILTER unterhalb von LDAP_USER_SEARCH_BASE (leer: LDAP_BASE_DN). Die Suche muss genau einen Eintrag liefern.
Mit dem gefundenen DN und dem eingegebenen Passwort meldet sich oPBWeb als Benutzer an und prüft so das Passwort.
Aus dem Attribut memberOf bestimmt oPBWeb die Rolle (siehe unten). Ohne passende Gruppe gibt es keinen Zugang.
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.

Betrieb und Aktualisierung

Mon, 01 Jan 0001 00:00:00 +0000

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]

Option	Wirkung
(keine)	startet den Produktiv-Stack (`docker-compose.yml`) mit den vorhandenen Images
`--build`	baut die eigenen Images vor dem Start neu
`--logs`	folgt nach dem Start den Logs aller Container (`logs -f --tail=50`); Strg+C beendet nur die Anzeige
`--dev`	nimmt `docker-compose.dev.yml` hinzu (Entwicklungs-Stack, siehe unten); nur im Klon mit Quellen
`--test`	nimmt `docker-compose.test.yml` hinzu: zwei opsi-Mocks als Configserver Test und Produktion, siehe Testumgebung
`--lang de` bzw. `--lang en`	Sprache der Ausgaben für diesen Aufruf (sonst `OPBWEB_LANG` aus der `.env`)
`-h`, `--help`	zeigt die Hilfe

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 .

Sicherung und Wiederherstellung

Mon, 01 Jan 0001 00:00:00 +0000

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.

Hinweis

Die Befehle in diesem Kapitel sind Beispiele. Die Datenbank-Sicherung mit mariadb-dump und das Sichern der Garage-Volumes bei gestopptem Stack sind der vorgesehene Weg; die konkreten Befehle für Volumes und Wiederherstellung sind daraus abgeleitet. Passe Pfade und Namen an deine Umgebung an und teste die Wiederherstellung, bevor du dich darauf verlässt.

Fehlersuche

Mon, 01 Jan 0001 00:00:00 +0000

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

Quelle	Inhalt
Seite Systemstatus	Zustand von Datenbank, Redis, Objektspeicher, Worker und opsi-Server, siehe Systemstatus
Seite Jobs	vollständiges Protokoll jedes Jobs mit Fehlermeldung, siehe Jobs
`docker compose ps -a`	welche Container laufen, welche beendet sind (mit Exit-Code)
`docker logs opbweb-api`	Start, Migrationen, Anmeldung, LDAP
`docker logs opbweb-worker`	Jobs, opsi-Verbindung
`docker logs opbweb-garage-init`	Einrichtung des Objektspeichers
Statusleiste der Oberfläche	„Backend nicht verbunden“, wenn die API nicht antwortet; orangefarbener Hinweis bei Problemen mit dem opsi-Server

Stack startet nicht

Symptom	Ursache	Abhilfe
`start.sh` meldet „.env fehlt – bitte ./setup-opbweb.sh ausführen (im Entwickler-Checkout: ./setup-opbweb.sh –dev).“	keine `.env`	`./setup-opbweb.sh` (oder `cp .env.example .env`)
API startet nicht, Log: „Secret file not found: …“	Secret-Datei fehlt, etwa weil der Stack mit `docker compose` statt mit `./start.sh` gestartet wurde	`./start.sh` verwenden oder `./scripts/init-secrets.sh` ausführen
API beendet sich nach etwa 60 Sekunden, Log: „Database not reachable: …“	MariaDB nicht bereit oder Passwort passt nicht zum Volume	`docker logs opbweb-db` prüfen; bei geändertem `db_password.txt` siehe Konfiguration
api, worker und frontend starten nicht, garage-init mit Exit-Code ungleich 0	Einrichtung des Objektspeichers fehlgeschlagen	`docker logs opbweb-garage-init`; „ERROR: No admin token found“ bedeutet fehlendes `secrets/garage_admin_token.txt`
garage-init meldet dauerhaft „Not ready yet, retrying in 2s…“	Garage startet nicht oder das Admin-Token passt nicht	`docker logs opbweb-garage`; Token in `secrets/` nicht nachträglich ändern
Log der API: „No users and no ADMIN_PASSWORD configured - no initial admin created“	`secrets/admin_password.txt` leer oder fehlt bei leerer Benutzertabelle	Datei füllen bzw. von `init-secrets.sh` anlegen lassen, Stack neu starten

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 .

Build und Auslieferung

Mon, 01 Jan 0001 00:00:00 +0000

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.