Installation und reproduzierbare Konfiguration

Installation und reproduzierbare Konfiguration

0:00 Willkommen zu Modul vier. Drei Module lang haben wir geplant: Anwendungsfall, Governance, Architektur. Jetzt wird installiert. Und Sie werden merken, dass die eigentliche Installation von Open WebUI erstaunlich schnell geht. Die Kunst liegt woanders. Sie besteht darin, das Ganze so aufzusetzen, dass es sich jederzeit wiederholen lässt, mit demselben Ergebnis.

0:21 Wir legen deshalb alles in ein Repository namens lotsenhaus-betrieb, legen die Version fest, sichern den ersten Start ab, stellen einen Proxy davor und klären eine Frage, die viele überrascht: Wer hat eigentlich das letzte Wort, die Konfigurationsdatei oder die Datenbank? Am Ende bauen Sie das Labor einmal komplett ab und wieder auf.

Installation und reproduzierbare Konfiguration

0:42 Der zweite Tag beginnt mit der Praxis, und der Satz auf der Folie ist die Leitregel dafür. Was nicht im Repository steht, gibt es nach dem nächsten Neuaufbau nicht mehr. Jede Einstellung, die nur in einem Klick in der Oberfläche lebt, ist eine Erinnerung, die irgendwann verloren geht. Unser Ziel ist eine Installation, die man getrost löschen kann, weil man weiß, dass sie wiederkommt.

Bereitstellung mit Docker Compose

1:05 Wir beginnen mit dem Fundament: ein festes Image, ein festes Volume und eine Datei im Repository. Das klingt unspektakulär, entscheidet aber über alles, was danach kommt. Open WebUI wird in vielen Varianten veröffentlicht, und die Tabelle hilft, die passende zu wählen. Die Unterschiede liegen auf zwei Ebenen. Erstens der Inhalt: Das Standardimage bringt eigene Modelle für Sprache und Embedding mit, die schlanke Variante verzichtet darauf und ist dadurch rund zehnmal kleiner, braucht dann aber externe Dienste.

1:36 Zweitens die Stabilität: Manche Kennungen wandern mit jeder Änderung weiter, andere zeigen für immer auf genau ein Release. Für Lotsenhaus fällt die Wahl deshalb auf eine feste Versionsnummer. Und die Fußzeile entlarvt eine verbreitete Annahme. Latest heißt hier nicht neuestes Release, sondern folgt dem Hauptzweig. Die Compose-Datei ist bewusst kurz, und gerade das macht sie wertvoll.

1:59 Sie legt die Version fest, sorgt dafür, dass der Container nach einem Absturz neu startet, liest die Einstellungen aus einer separaten Datei und hängt ein benanntes Volume ein, in dem alle Daten liegen. Was auffällt, ist das, was fehlt: Es gibt keinen Port nach außen. Open WebUI ist nur über den Proxy erreichbar, den wir gleich davorstellen.

2:20 Und die Fußzeile zeigt die strengere Variante. Zusätzlich zur Versionsnummer lässt sich der Digest des Images festschreiben, eine Art Fingerabdruck. Dann ist bitgenau sicher, was läuft. Dieser Vergleich zeigt, warum die feste Version mehr ist als Pedanterie. Links die rollende Variante: Ihr Inhalt ändert sich mit jeder Änderung im Projekt, das Update passiert einfach beim nächsten Herunterladen, und hinterher weiß niemand genau, was lief.

2:46 Migrationen der Datenbank kommen dann unangekündigt. Rechts die festgelegte Version: Ein Update ist ein bewusster Commit im Repository, die Release Notes werden vorher gelesen, und der Rückweg ist der vorige Commit samt Backup. Das ist der Unterschied zwischen einer Wohnung, in der nachts jemand die Möbel umstellt, und einer, in der Sie den Umzug selbst planen.

3:06 Vier Fehler kosten hier regelmäßig Daten oder Nerven. Ohne Volume verschwinden Chats, Nutzer und Einstellungen mit dem Container, beim ersten Neuerstellen ist alles weg. Zweitens läuft das Image als root. Wer das nicht will, braucht ein eigenes Build mit passender Nutzer- und Gruppenkennung. Drittens gehört die SQLite-Datei auf eine lokale SSD, nicht auf eine Netzwerkfreigabe. Und viertens der Secret Key.

3:32 Ohne festen Wert erzeugt Open WebUI selbst einen, aber der liegt außerhalb des Volumes. Beim nächsten Neuaufbau ist er verloren, und alle Anmeldungen sind ungültig.

Sicherer Start

3:43 Jetzt zum ersten Start, und der hat eine Eigenheit. Das erste Konto, das sich registriert, wird Administrator. Das sollte besser nicht dem Zufall überlassen bleiben, sondern der Konfiguration. Diese Einstellungen legen den Administrator schon beim ersten Start fest, statt darauf zu warten, wer sich zuerst anmeldet. Bei Lotsenhaus ist das das Notfallkonto notfall-admin, das Passwort kommt aus dem Tresor.

4:09 Dazu kommen der Secret Key, die öffentliche Adresse und die Regel, dass neue Konten zunächst auf Freigabe warten. Zwei Hinweise aus den Beschriftungen sind wichtig. Diese Datei liegt nicht im Repository, denn sie enthält Geheimnisse. Und die Admin-Werte wirken nur bei leerer Datenbank. Danach ist die Registrierung geschlossen.

4:28 Die Doku rät ausdrücklich, eine frische Instanz nie ungeschützt erreichbar zu machen. Wer schneller ist, wird sonst Chef. Sechs Geheimnisse braucht Lotsenhaus, und für alle gilt dieselbe Grundregel: Sie gehören in den Tresor, nie ins Repository. Die Tabelle zeigt aber, dass sie unterschiedlich heikel sind. Der Secret Key signiert Anmeldetokens und muss auf allen Instanzen gleich sein.

4:53 Für OAuth-Tokens gibt es einen eigenen Schlüssel, der sonst einfach dem Secret Key entspricht. Hier lohnt ein eigener Wert. Datenbank- und Redis-Zugang, der Schlüssel des externen Endpunkts und das Passwort des Notfallkontos komplettieren die Liste. Und die Fußzeile ist eine Warnung aus der Praxis. Ein neuer Secret Key meldet alle Nutzer ab. Rotation gehört also in einen Plan, nicht in die Mittagspause.

5:18 Vor Open WebUI steht im Labor ein Nginx, und diese Konfiguration löst drei typische Probleme. Erstens WebSockets: Dafür braucht es HTTP eins Punkt eins und die passenden Header für den Verbindungswechsel. Zweitens das Streaming: Die Antwort eines Modells kommt Stück für Stück, und ein Proxy, der puffert, sammelt sie erst und liefert dann einen Klumpen.

5:40 Deshalb ist das Puffern abgeschaltet. Drittens Geduld: Lange Antworten dauern Minuten, also braucht es großzügige Timeouts. Warum Nginx? Die Fußzeile sagt es. Für diesen Proxy beschreibt die Doku Puffer, WebSockets und Timeouts am genauesten, und das spart im Labor Sucherei. Diese Tabelle ist eine Checkliste für alles, was zwischen Proxy und Open WebUI zusammenpassen muss.

6:05 Der rote Faden: Open WebUI muss wissen, dass es hinter einem Proxy unter HTTPS steht. Sonst zeigen Anmelde-Rückrufe auf falsche Adressen, Cookies wandern unverschlüsselt, und WebSockets scheitern still. Auffällig sind die Standardwerte. Bei erlaubten Ursprüngen und vertrauenswürdigen Proxys steht ab Werk ein Sternchen, also jeder. Das Secure-Cookie ist ab Werk aus.

6:28 Bequem für den ersten Test, aber nicht für den Betrieb. Und die Fußzeile beruhigt: Auch wenn der Proxy nach außen HTTP zwei spricht, bleibt die Verbindung nach innen bei eins Punkt eins.

Konfigurationshoheit

6:40 Jetzt kommt das Kapitel, das in der Praxis die meisten Rätsel auflöst. Umgebungsvariable oder Datenbank, wer gewinnt eigentlich, wenn beide etwas anderes sagen? Stellen Sie sich einen Neuzugang vor, der am ersten Arbeitstag ein Merkblatt mit allen Regeln bekommt. Manche davon schreibt er sich in sein eigenes Notizbuch und hält sich fortan daran, egal was später auf neuen Merkblättern steht. So verhält sich Open WebUI.

7:06 Beim ersten Start liest es alle Umgebungsvariablen. Werte, die als ConfigVar gekennzeichnet sind, speichert es in der Datenbank, und ab dann gilt der gespeicherte Wert, nicht mehr die Variable. Auch Änderungen in der Admin-Oberfläche landen dort. Alle übrigen Variablen wirken bei jedem Start neu. Wer das nicht weiß, ändert Konfigurationsdateien und wundert sich, dass nichts passiert.

7:30 Die Tabelle sortiert Einstellungen danach, wer nach einem Neustart das letzte Wort hat. Bei ConfigVar-Werten wie der Registrierung oder der öffentlichen Adresse gewinnt die Datenbank. Bei normalen Variablen wie dem Datenbankzugang gewinnt die Variable. Es gibt aber einen Hauptschalter, der die Persistenz abschaltet. Dann gelten immer die Variablen, und Änderungen in der Oberfläche überleben keinen Neustart.

7:53 Für OAuth gibt es einen eigenen Schalter, der ab Werk auf Variablen setzt, die Einstellungen sind im Admin-Bereich dann nur lesbar. Und der praktische Tipp aus der Fußzeile: In der Referenz steht bei jeder Variable, ob sie persistiert wird. Aus dieser Mechanik leitet Lotsenhaus eine klare Arbeitsteilung ab. Infrastruktur und Geheimnisse leben in Compose und env-Datei.

8:16 Sicherheitsgrenzen ohne Persistenz ebenfalls, denn sie wirken bei jedem Start neu. Sicherheitsgrenzen mit Persistenz werden beim Erststart gesetzt und danach in der Oberfläche gepflegt, mit Protokoll. Fachliches wie Banner, Modellfreigaben und Wissensbasen bleibt in der Oberfläche. Und die Assistenten Schreibhilfe und Richtlinienlotse landen als Export im Repository und lassen sich über eine Schnittstelle abgleichen.

8:41 Die Fußzeile nennt die Alternative für alle, die alles deklarativ wollen. Das geht, kostet aber die Pflege per Oberfläche. Alle vier Stolpersteine haben dieselbe Wurzel: Man vergisst, wer gewinnt. Der Klassiker ist eine geänderte Registrierungseinstellung in der env-Datei, die einfach nichts bewirkt, weil der Datenbankwert gilt. Der umgekehrte Fall ist genauso ärgerlich.

9:04 Wer die Persistenz abschaltet und trotzdem in der Oberfläche konfiguriert, verliert beim Neustart alles. Drittens der Holzhammer: Das Volume löschen, damit die Variablen frisch geladen werden. Das klappt, nur sind dann auch Nutzer und Chats weg. Und viertens dieselbe Einstellung an zwei Orten, ohne festzulegen, welcher zählt. Das ist ein Streit, der irgendwann im Betrieb ausgetragen wird.

Umgebungen und Varianten

9:28 Eine Installation reicht selten. Lotsenhaus braucht Labor, Test und Produktion, alle aus denselben Dateien mit anderen Werten, und vor allem ohne Testdaten in der Produktion. Drei Umgebungen, drei Aufgaben, und die Tabelle zeigt, wie sie sich unterscheiden. Das Labor läuft mit der festen Version und synthetischen Dokumenten.

9:49 Hier darf experimentiert werden. Der Test bekommt das nächste Release, damit Updates dort zuerst auffallen, und hat eigene Datenbank und eigene Geheimnisse. Die Produktion läuft nur mit freigegebenen Releases samt Digest, mit lh-db, Backups und Monitoring. Die Fußzeile verdient besondere Aufmerksamkeit. Wer die Vorabversion ausprobieren will, tut das nur als zweite Instanz mit eigenem Volume. Deren Migrationen verändern die Datenbank, und zurückdrehen lassen sie sich nicht.

10:19 Für den abgeschotteten Betrieb muss alles vorher bereitliegen, und die Schritte folgen genau dieser Logik. Erst kommt das Image, geholt auf einem verbundenen System und als Datei ins getrennte Netz gebracht. Dann die Modelle auf inferenz-01, geprüft mit einer Testfrage. Das Embedding-Modell gehört vorab in den Cache von Open WebUI, denn ohne Netz kann es nichts mehr nachladen. Extraktion und Zusatzdienste brauchen eigene Images.

10:45 Erst ganz am Ende wird der Offline-Modus gesetzt, das Netz getrennt und mit einem echten Dokument geprüft. Die Fußzeile wiederholt eine Lektion aus Modul drei: Abschotten tun Firewall und Netz, nicht der Schalter. Zum Schluss ein Blick nach vorn, denn der Pilot ist nicht das Ende. Für den Ausbau zeigt die Doku zwei Wege.

11:04 Kubernetes mit dem offiziellen Helm-Chart bietet automatische Skalierung, rollierende Updates und GitOps, verlangt aber echte Erfahrung im Team. Ein Container-Dienst eines Cloud-Anbieters nimmt Ihnen Skalierung und Rollout ab, setzt aber ein Cloud-Konto voraus. Die eigentliche Botschaft steht nicht auf der Folie: Beide Wege brauchen dieselben Zustandsdienste: PostgreSQL, Redis, Vektordatenbank und Speicher.

11:28 Wer die im Pilot schon sauber aufsetzt, hat beim Ausbau die halbe Arbeit hinter sich. Bei mehreren Umgebungen lauern Fehler, die man im Labor nicht sieht. Teilen sich Test und Produktion Datenbank oder Secret Key, ist der Test kein Test mehr, sondern ein Eingriff in die Produktion. Läuft der Test mit einer anderen Variante, etwa schlank statt Standard, testen Sie schlicht etwas anderes, als später läuft.

11:52 Beim Offline-Betrieb wird gern nur das Image mitgenommen, und dann fehlen Embedding-Modell und Extraktion genau in dem Moment, in dem jemand das erste Dokument hochlädt. Und im Cluster gilt dieselbe Regel wie zuvor: Bei Schemaänderungen wechseln alle Instanzen gleichzeitig, rollierend geht dann nicht.

Übung

12:09 Jetzt bauen Sie selbst. Und zwar nicht einmal, sondern zweimal. Denn erst der zweite Aufbau zeigt, ob das Repository wirklich alles enthält. Ihre Aufgabe ist das Labor von Lotsenhaus, aufgebaut aus dem Repository lotsenhaus-betrieb. Die Fähigkeit dahinter geht über diese eine Installation hinaus. Es geht darum, eine Installation so zu beschreiben, dass ein Neuaufbau dasselbe Ergebnis liefert, ohne Handarbeit und ohne Erinnerungslücken.

12:37 Gelungen ist das, wenn nach einem Neuaufbau der Gesundheitscheck positiv antwortet, sich notfall-admin anmelden kann und eine Antwort von inferenz-01 sauber streamt. Sie müssen dafür keinen Modellserver aufsetzen, inferenz-01 ist vorbereitet. Und der Proxy nutzt ein Zertifikat der Labor-CA. Konzentrieren Sie sich also ganz auf Open WebUI und seine Konfiguration.

13:00 Diese Tests prüfen nicht nur, ob etwas läuft, sondern ob es richtig läuft. Gesundheitscheck und Anmeldung sind die Grundlage. Der Chat mit dem Modell prüft nebenbei den Proxy, denn sauber gestreamtes Markdown heißt, dass Puffer und WebSockets stimmen. Spannend wird es bei den letzten drei. Nach dem Neuerstellen des Containers müssen Sitzung und Chats noch da sein, das prüft Volume und Secret Key. Das Log muss die festgelegte Version nennen.

13:26 Und eine geänderte ConfigVar in der env-Datei darf keine Wirkung zeigen, damit beweisen Sie, dass Sie die Konfigurationshoheit verstanden haben. Halten Sie jedes Ergebnis mit Datum im Runbook fest. Der Weg führt vom leeren Host zum geprüften Labor. Sie legen das Repository mit Compose-Datei, Nginx-Konfiguration und einer Vorlage für die Einstellungen an, ohne Geheimnisse.

13:49 Dann legen Sie Version und Digest fest und holen die Geheimnisse aus dem Tresor auf den Host. Danach starten Sie den Proxy, machen den Erststart und führen die Funktionstests aus. Und dann kommt der entscheidende Schritt: Sie löschen alles außer Repository und Geheimnissen, bauen neu auf und testen erneut. Die Fußzeile ist die Pointe der ganzen Übung.

14:09 Was beim zweiten Aufbau anders läuft, fehlt im Repository.