Files
infrastructure/docs/platform/llm-server/ai/GNAI-021-TECH_OpenWebUI-Theme.md
T
spektr 46dab5dca7
ci-static / secret-scan (push) Successful in 21s
ci-static / yamllint (push) Successful in 30s
ci-static / ansible-syntax (push) Successful in 28s
ci-static / markdown-links (push) Successful in 22s
ci-static / secret-scan (pull_request) Successful in 20s
ci-static / yamllint (pull_request) Successful in 30s
ci-static / ansible-syntax (pull_request) Successful in 27s
ci-static / markdown-links (pull_request) Successful in 20s
M6/GNAI-021: OpenWebUI-Theme gnai-catppuccin-mocha + Ghost-Favicon als read-only Mounts; ai_backup um /etc/gnmon und openwebui-data (SQLite-Snapshot) erweitert
- open_webui-Rolle: Theme (files/theme/gnai-catppuccin-mocha.css) und Favicon
  (files/favicon/*, byte-identisch zum Dashboard-Original) werden host-seitig
  deployt und im Quadlet read-only ueber die Image-Platzhalter in
  /app/backend/open_webui/static/ gemountet — update-persistent, weil der
  Mount host-seitig liegt und OpenWebUIs Start-Wipe von static/ eine ro-Datei
  nicht anfassen kann. Inode-Befund: copy->Rename tauscht den Inode, daher
  notify Restart + flush_handlers vor den Served-Checks.
- Served-Verifikation in der Rolle: /static/custom.css (Marker) und
  /static/favicon.png (byte-identisch via content_length).
- ai_backup: zusaetzliche Pfade etc/gnmon und
  var/lib/ghostnet-ai/production/openwebui-data; die live webui.db (+wal/shm)
  wird aus dem tar ausgeschlossen und stattdessen als konsistenter Snapshot
  via SQLite-Online-Backup-API (python3 stdlib) an derselben Archiv-Position
  angehaengt (tar uncompressed -> append -> gzip).
- Doku: GNAI-021 (neu) + ai-README-Index; Link auf GNMON-000 korrigiert.
- Live ausgerollt 14.11.2026 auf 10.0.0.90 (webui.yml + ai.yml konvergent
  changed=0): custom.css 200/5311 B mit Marker, favicon.png 200/2729 B,
  alle 6 ro-Mounts am laufenden Container gebunden.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-14 14:37:13 +01:00

10 KiB

Technischer Arbeitsentwurf

Dokumenten-ID: GNAI-021-TECH
Titel: Ghostnet-Branding „gnai-catppuccin-mocha" — OpenWebUI-Theme als Default + Favicon „ursprünglicher Geist" auf beiden Sites, update-persistent
Stand: 2026-11-14
Status: produktiv seit 2026-11-14 (Betreiber-Go „schalte es live"): Theme live; Favicons nach Betreiberentscheid 2026-11-14 zurück auf den ursprünglichen Geist (Badge-Varianten v2/v5 verworfen) — Monitoring via Image v0.3.6 (unverändert), OpenWebUI via ro-Mounts; Konvergenz changed=0
Referenzen: DOC-Index, GNMON-000 (Dashboard-Stil M3.1: Catppuccin Mocha, Monospace), Rolle llm-server/llm/ansible/roles/open_webui/, OpenWebUI v0.13.3 (digest-gepinnt, sha256:46b59158…), Upstream-Quelle tag v0.13.3

Dieses Dokument beschreibt den technischen Sollzustand des Custom-Themes für OpenWebUI (https://chat.ghostnet.selfhost.eu, intern 10.0.0.90:8081) und warum es OpenWebUI-Updates unabhängig übersteht.


Änderungsverlauf

Datum Version Autor Beschreibung
2026-11-14 0.1 spektr / Mistral Vibe Erstfassung: Befunde zum Theme-Mechanismus in v0.13.3, update-persistenter Mount, Umsetzung in Rolle open_webui, Verifikation
2026-11-14 0.2 spektr / Mistral Vibe Live-Rollout: erster Lauf changed=3 (Theme-Dir, custom.css, Quadlet), Play brach vor den Handlern an der Served-Prüfung ab (alter Container ohne Mount) — daemon-reload + Unit-Restart manuell nachgezogen, danach GET /static/custom.css = 200 mit 5311 Bytes und Marker; zweiter Playbook-Lauf konvergent changed=0, failed=0. Der Neustart nach Quadlet-Change ist zugleich der Persistenz-Beweis: OpenWebUIs Start-Wipe von static/ läuft dabei erneut und kann den ro-Mount nicht anfassen
2026-11-14 0.3 spektr / Mistral Vibe Favicons ergänzt (Abschnitt 5): v2 (Ghost + Pulse-Badge) für das Monitoring-Dashboard, v5 (Ghost + Terminal-Badge) für OpenWebUI — gleiche read-only-Mount-Mechanik
2026-11-14 0.4 spektr / Mistral Vibe Live-Rollout Favicons: OpenWebUI v5 via ro-Mounts OK (alle 5 Dateien byte-identisch serviert, md5-geprüft). Dashboard: Mount-Versuch über /app/wwwroot scheiterte (HTTP 500 — MapStaticAssets-Manifest-Mismatch, Befund in Abschnitt 5), deshalb Image-Rebuild dashboard:v0.3.7 auf der Workstation (Image-ID a2c15048e188, favicon md5 87f78a61… im Image verifiziert), podman save/scp/load als gn-dashboard, Tag im Inventory gebumpt, Unit neu gestartet — GET /favicon.png = 200, 2488 Bytes, md5 identisch zur Quelle; Playbook konvergent changed=0, failed=0
2026-11-14 0.5 spektr / Mistral Vibe Betreiberentscheid: Badge-Varianten verworfen, beide Sites nutzen wieder den ursprünglichen Geist. Monitoring komplett reverted (Quell-PNGs, Rolle, Inventory-Tag v0.3.6; GET /favicon.png = 2729 B, md5 78966788…). OpenWebUI: Favicon-Dateien gegen byte-identische Kopien des Dashboard-Originals ersetzt (Mounts bleiben); Inode-Befund dokumentiert (copy→Rename→neuer Inode, laufender Container serviert alt — deshalb notify Restart + flush_handlers vor den Checks). Beide Playbooks konvergent changed=0, failed=0; alle Favicon-URLs md5-verifiziert

1. Entscheidung

Betreiberwunsch 2026-11-14: OpenWebUI soll im Farbschema der Monitor-Website (mon.ghostnet.selfhost.eu, GNMON — Catppuccin Mocha, DejaVu Sans Mono, Hacker-TUI-Stil) erscheinen; das Theme soll Default für alle Nutzer sein und unabhängig von OpenWebUI-Updates bestehen bleiben (kein Image-Patch, kein Fork).

2. Befunde zum Theme-Mechanismus in OpenWebUI v0.13.3

a) Es gibt kein server-seitiges Theme. Die Theme-Wahl (system/light/ dark/oled-dark/her) liegt pro Browser in localStorage.theme (src/app.html, src/lib/utils/theme.ts setTheme()); in der DB (webui.db) existiert keine Theme-Tabelle (Backend-Modelle/Routers enthalten kein Theme — geprüft gegen tag v0.13.3). Ein „Default-Theme für alle Nutzer" lässt sich daher nicht serverseitig erzwingen, sondern nur über CSS, das beide Modi abdeckt (Abschnitt 3). b) Offizieller Extension-Point: /static/custom.css. src/app.html lädt auf jeder Seite <link rel="stylesheet" href="/static/custom.css">. Das Image enthält an dieser Stelle eine leere Placeholder-Datei (static/static/custom.css = leerer Blob). Live verifiziert 2026-11-14: GET / enthält den custom.css-Link; GET /static/custom.css → 200, 0 Bytes. c) /static wird aus STATIC_DIR serviert (main.py: app.mount('/static', StaticFiles(directory=STATIC_DIR)), Default /app/backend/open_webui/static). Beim Start wiped config.py alle Top-Level-Dateien in STATIC_DIR und kopiert sie aus dem Image neu (STATIC_SOURCE_DIR = /app/build/static). Eine read-only bind-mountete Einzeldatei kann dort weder unlink()t noch per copyfile überschrieben werden (EBUSY/EROFS, beides per except: pass ge-swallowt) — sie überlebt jeden Start und jedes Image-Update. d) Theme-Switch setzt Inline-Styles. setTheme() schreibt --color-gray-800/850/900/950 als Inline-Style auf <html> (dark/oled-dark). Das Theme-CSS braucht daher !important auf den Custom-Properties. Ungelayertes CSS (custom.css) schlägt außerdem die @layer theme-Variablen von Tailwind v4 (src/tailwind.css definiert nur die Graustufen selbst; Akzentfarben kommen aus dem Tailwind-Default-Theme). e) Farbpalette des Dashboards stammt aus llm-server/monitoring/src/Ghostnet.Dashboard/wwwroot/app.css (:root, Catppuccin Mocha: crust #11111b … text #cdd6f4 … mauve #cba6f7).

3. Umsetzung

  • Theme-Datei im Repo: llm-server/llm/ansible/roles/open_webui/files/theme/gnai-catppuccin-mocha.css. Mapping: Graustufen-Rampe → Mocha-Oberflächen (dark: 950=crust, 900=base, 850=mantle, 800=surface0 … 50=text; light: Rampe invertiert auf dieselbe dunkle Palette, damit auch light/system-Nutzer das Mocha-Theme sehen), Akzent-Rampen (blue→sapphire/blue, green→green/teal, red→red, yellow→yellow, orange→peach, violet→mauve), color-scheme: dark, Monospace-Stack ("DejaVu Sans Mono", ui-monospace, …), Splash-Screen auf base/peach/grün.
  • Deployment (Rolle open_webui):
    • open_webui_theme_dir = /var/lib/ghostnet-ai/production/openwebui-theme, Datei custom.css (Owner gnai-production, 0644).
    • Quadlet open-webui.container.j2: Volume={{ open_webui_theme_dir }}/custom.css:/app/backend/open_webui/static/custom.css:ro.
    • Kein Restart bei reinen Inhaltsänderungen nötig (/static wird pro Request von Disk gelesen); der Quadlet-Change triggert einmalig daemon-reload + Restart über die bestehenden Handler.
  • Verifikation im Playbook: nach dem Health-Check prüft GET http://10.0.0.90:8081/static/custom.css auf HTTP 200 und den Marker gnai-catppuccin-mocha im Body — so fällt ein künftiges Image, das custom.css nicht mehr referenziert/serviert, sofort auf statt still zu verstummen.

4. Warum das Theme Updates überlebt

  • Der Mount liegt host-seitig im Quadlet (Ansible, Git), nicht im Image.
  • Die Theme-Datei liegt im Repo und wird idempotent erneut ausgerollt (changed=0 bei unverändertem Stand).
  • Beim Container-Start (auch nach Image-Update auf neuen Digest) kopiert OpenWebUI static/ zwar neu, kann die read-only gemountete Datei aber nicht anfassen (Befund c) — das Theme bleibt aktiv.
  • Einzige Sollbruchstelle: Ein künftiges OpenWebUI-Release, das den custom.css-Link aus app.html entfernt. Der Served-Check im Playbook (Abschnitt 3) erkennt das beim nächsten Rollout; bis dahin bleibt das Theme auch über Updates aktiv.

5. Favicons — Betreiberentscheid 2026-11-14: ursprünglicher Geist auf BEIDEN Sites

Badge-Varianten (v2 Pulse, v5 Terminal aus ~/Downloads/Gemini_Generated_Image_p4vvywp4vvywp4vv.jpg) wurden gebaut, live genommen und dann vom Betreiber verworfen: Beide Websites verwenden wieder das ursprüngliche Geist-Favicon der Monitoring-Website (favicon.png 32x32 md5 78966788…, apple-touch-icon.png 180x180 md5 9bc48a15…).

  • Monitoring-Dashboard: alles zurückgesetzt — Quell-PNGs, Rolle gnmon_dashboard und Inventory-Tag auf HEAD/v0.3.6 reverted; Unit neu gestartet, GET /favicon.png = 2729 Bytes, md5 identisch zum Original. Der Image-Bau v0.3.7 (mit v2-Favicon) bleibt als unbenutztes Image im Store liegen.

  • OpenWebUI: Mount-Mechanik bleibt (funktioniert), nur der Inhalt wurde ersetzt: roles/open_webui/files/favicon/ enthält jetzt byte-identische Kopien des Dashboard-Originals (favicon.png, apple-touch-icon.png) plus Ableitungen (favicon-96x96.png, favicon.ico 16/32, favicon.svg als Data-URI-Wrapper). Live verifiziert: alle fünf /static/*-URLs liefern die erwarteten md5s.

  • Befund Inode (14.11.2026): Single-File-Bind-Mounts binden den Inode bei Container-Erzeugung; Ansible copy ersetzt Dateien per Rename (neuer Inode) — der laufende Container serviert dann weiter den alten Inhalt. Deshalb notifyen die Copy-Tasks in der Rolle jetzt Restart OpenWebUI unit, und flush_handlers läuft vor den Served-Checks.

  • Befund .NET (14.11.2026): Beim Dashboard ist der Mount-Weg prinzipiell unbrauchbar — .NET 10 MapStaticAssets liest Content-Length/ETag aus dem Publish-Manifest (Ghostnet.Dashboard.staticwebassets.endpoints.json); eine gemountete abweichende Datei lieferte HTTP 500 (kürzer) bzw. Truncation (länger). Favicon-Änderungen am Dashboard erfordern also immer einen Image-Bau + Tag-Bump.

  • Out of scope: OpenWebUI-Splash (splash.png/splash-dark.png) und site.webmanifest/web-app-manifest-*.png zeigen weiterhin das OpenWebUI-Logo.

6. Grenzen / Offen

  • Die Theme-Auswahl im UI (Settings → General → Theme) bleibt sichtbar, ist aber visuell neutralisiert (light und dark rendern beide Mocha). Wer explizit „OLED Dark" wählt, bekommt ebenfalls Mocha (Crust statt Schwarz) — bewusst, damit das GNMON-Theme überall greift.
  • Die DejaVu-Sans-Mono-Datei des Dashboards wird nicht eingebettet (kein Font-Mount ohne neuen Mount-Pfad); auf Linux-Clients mit installierter DejaVu Sans Mono ist der Look identisch, sonst greift der Monospace-Fallback.
  • Code-Highlighting (hljs) und eingebettete Markdown-Tabellen behalten ihre eigenen Akzente — bewusst nur dezente Anpassungen (Links sapphire, Inline-Code peach, Selection mauve).