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) die Vorgaben für neue Pakete und die Vorlagen des Installer-Assistenten. 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.

Installer-Analyse (opsi-setup-detector)

Der Assistent Paket aus Installer erzeugen analysiert Installer im Worker. Die Werkzeuge dafür sind im Backend-Image enthalten, eine Konfiguration in der .env ist nicht nötig:

Fehlt ein Werkzeug, bricht die Analyse nicht ab; sie vermerkt einen Hinweis und arbeitet mit dem, was sie lesen kann. Welche Werkzeuge der Container findet, liefert GET /api/detector/tools (angemeldet) als Pfad je Werkzeug, null für fehlende. Externe Aufrufe brechen nach 300 Sekunden ab.

Detect-It-Easy nachrüsten

Detect-It-Easy braucht rund 550 MB Qt-Bibliotheken und ist deshalb nicht im Image. oPBWeb verwendet es, wenn diec im PATH des Worker-Containers liegt oder die Umgebungsvariable DIEC_PATH auf die ausführbare Datei zeigt. Die .env reicht DIEC_PATH nicht an die Container durch. Zum Nachrüsten baust du ein eigenes Backend-Image auf Basis von opbweb-backend mit Detect-It-Easy und trägst es als BACKEND_IMAGE ein (siehe Image-Overrides ), oder du ergänzt am Dienst worker in einer eigenen Compose-Datei ein Volume mit Detect-It-Easy und DIEC_PATH.

Vorlagen und Installertabelle

Beides stammt aus den Quellen des opsi-setup-detectors (Repository opsi-org/lazarus, Ordner opsi-misc/opsisetupdetector, AGPL-3.0) und liegt im Image unter src/detector/resources/ (im Repository backend/src/detector/resources/):

• installers.toml: die Installertabelle mit Erkennungsmustern, Silent- und Unattended-Parametern, Deinstallationsprogramm, Exit-Code-Funktion und Hinweisen je Installertyp. Sie wird mit backend/tools/osd_installers_to_toml.py aus osdbasedata.pas erzeugt und nicht von Hand bearbeitet.
• templates/: die Script-Vorlagen (template-files) als <Kanal>/<Gruppe>/<Datei>. Beim Start kopiert die API sie in die Tabelle detector_templates; ab dann arbeiten Generator und die Ansicht Vorlagen mit der Datenbank, siehe Vorlagen für den Installer-Assistenten .

Eine neuere Fassung der Vorlagen kann ein Administrator ohne neues Image als ZIP importieren. Die Installertabelle ändert sich nur mit einem neuen Image. Wie beides im Quellcode aktualisiert wird, beschreibt backend/src/detector/resources/README.md; kurz:

git clone --depth 1 --filter=blob:none --sparse https://github.com/opsi-org/lazarus.git /tmp/lazarus
git -C /tmp/lazarus sparse-checkout set opsi-misc/opsisetupdetector
python3 backend/tools/osd_installers_to_toml.py /tmp/lazarus/opsi-misc/opsisetupdetector/osdbasedata.pas
rsync -a --delete /tmp/lazarus/opsi-misc/opsisetupdetector/template-files/ backend/src/detector/resources/templates/

rsync --delete entfernt dabei die winget-Vorlagen, die oPBWeb selbst mitbringt (im Original fehlen sie); stell sie danach aus Git wieder her. Bringt die neue Installertabelle einen neuen Installertyp mit, braucht er eine ID im Skript und gegebenenfalls Code in src/detector/analyze.py.

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