v0.5.5

Neu

Neue Option startup_delay_seconds (Standard 60s, 0 deaktiviert die Verzögerung): verzögert die schwere
Init-Kette (Embedder laden, Qdrant-Collection, initialer Abgleich, Watcher-Start), damit dieser
Speicher-Peak (Torch + sentence-transformers, ~2 GB RAM beobachtet) nicht ausgerechnet in dem Moment
passiert, in dem nach einem Host-Reboot/Update alle anderen Add-ons gleichzeitig starten.

Hintergrund: ein OOM-Kill genau in diesem Fenster hat auf dem Produktivsystem des Maintainers zu einem
mehrstündigen Ausfall beigetragen — bestätigt über dmesg. Neue /api/status-Phase
waiting_before_startup, damit die Web-UI in dieser Zeit nicht wie hängengeblieben aussieht.

Sonstiges

• README/DOCS: deutscher Dev-Changelog-Blockquote vor der eigentlichen Erklärung durch eine
  Intro + Requirements + Getting-Started-Sektion ersetzt (#47).
• Eigenes icon.png/logo.png statt generischem Supervisor-Standardicon (#47).

Issue #50, PR #52. Follow-up-Idee (adaptive speicherbasierte Wartezeit statt fixer Verzögerung) als #51
für später vorgemerkt. Tests: 99 passed, ruff clean, Smoke-Build (amd64) erfolgreich.

v0.5.4 — Fix: builder --image war immer noch doppelt (Owner)

Fix

v0.5.3 hat nur den ghcr.io/-Teil aus --image entfernt, den Owner aber drin gelassen (dibi73/{arch}-bookstack-rag-addon). Die home-assistant/builder-Action hängt aber IMMER ghcr.io/{owner}/ vor den --image-Wert, egal was drinsteht — das Image landete dadurch weiterhin doppelt, diesmal nur beim Owner: ghcr.io/dibi73/dibi73/{arch}-bookstack-rag-addon.

Bestätigt direkt aus dem Build-Log von v0.5.3 (Init cache for ghcr.io/dibi73/dibi73/amd64-bookstack-rag-addon:0.5.3).

Fix: --image enthält jetzt nur noch {arch}-bookstack-rag-addon — weder Owner noch Registry, beides ergänzt die Action selbst.

Kein Funktionsumfang geändert — reiner CI/Publish-Fix (Fortsetzung von v0.5.3).

v0.5.3 — Fix: doppelter ghcr.io-Präfix beim Image-Push

Fix

Die Add-on-Installation schlug seit v0.5.2 mit „An unknown error occurred" fehl. Ursache: builder.yml hat --image mit vollem ghcr.io/dibi73/...-Pfad an die home-assistant/builder-Action übergeben — die Action hängt aber selbst noch einmal ghcr.io/ davor, wenn sie das Image tatsächlich baut/pusht. Das veröffentlichte Image landete dadurch am falschen, doppelten Pfad (ghcr.io/dibi73/ghcr.io/dibi73/{arch}-bookstack-rag-addon), den Supervisor nie abfragt.

Fix: --image ohne ghcr.io/-Präfix übergeben (die Action ergänzt ihn selbst).

Bestätigt über die GHCR Docker-Registry-v2-API (Manifest existierte nur unter dem doppelten Pfad) und das Build-Log von v0.5.2 selbst.

Kein Funktionsumfang geändert — reiner CI/Publish-Fix.

v0.5.2 — Hotfix: builder action image mismatch

Fixed

• home-assistant/builder pinned to 2026.03.2 instead of 2026.06.0. v0.5.1's Dependabot bump to 2026.06.0 broke the release-triggered build: the GitHub release exists, but no matching Docker image was ever published to ghcr.io/home-assistant/{arch}-builder under that tag ("manifest unknown"). 2026.03.2 is the newest version that actually has a published image.

This class of break only surfaces on a real release: published trigger, not on PR CI (which builds via plain docker build, not this action) — found immediately after cutting v0.5.1.

Full Changelog: v0.5.1...v0.5.2

v0.5.1 — Dependabot cluster consolidated

Dependabot cluster consolidated into one release instead of ten sequential single-PR merges (avoids rebase-cascade on the other open branches, one release commit instead of ten atomic "Bump X from A to B"s).

Changed

• docker/login-action 3 → 4.5.2 (also fixes a Node.js 20 deprecation warning surfaced during the v0.5.0 builder run — GitHub forces Node 24 from 2026-06-02 and removes Node 20 entirely 2026-09-16)
• actions/setup-python 6.2.0 → 7.0.0
• actions/checkout 6.0.2 → 7.0.1
• qdrant/qdrant v1.17.1 → v1.18.3 (Dockerfile base for the sidecar binary)
• home-assistant/builder 2025.03.0 → 2026.06.0
• uvicorn 0.46.0 → 0.47.0
• ruff 0.15.12 → 0.15.13
• sentence-transformers 5.4.1 → 5.5.0
• qdrant-client 1.17.1 → 1.18.0
• einops 0.8.1 → 0.8.2

Notes

95 tests pass, ruff clean, no Python source changes apart from dependency version pins. CI's smoke build + docker run + /api/status poll all green.

v0.5.0 — pre-built ghcr.io images + real docker-run smoke test

The "no more local build" release. Closes the structural gap that produced five hotfix cycles in a row (v0.4.1 → v0.4.5): every release shipped a runtime issue that docker build could not catch but docker run would have. Publishes pre-built multi-arch images to ghcr.io so the Supervisor pulls instead of building, and adds a real docker run smoke phase to the build CI so the same class of bug surfaces in pull requests.

Added

• .github/workflows/builder.yml — home-assistant/builder builds per-arch images (amd64, aarch64) on every published GitHub Release, pushes to ghcr.io/dibi73/{arch}-bookstack-rag-addon.
• bookstack-rag/config.yaml — image: ghcr.io/dibi73/{arch}-bookstack-rag-addon. Supervisor pulls the matching manifest instead of building locally.
• bookstack-rag/config.yaml — watchdog: http://[HOST]:[PORT:8000]/api/status for a real "ready" indicator on the add-on detail page.
• .github/workflows/build.yml — after the smoke build, docker runs the image with a synthetic /data/options.json, polls /api/status for up to 120s, fails the job if the response isn't ok/initializing.

Changed

• bookstack-rag/Dockerfile — FROM ${BUILD_FROM} again (python:3.12-slim-bookworm default for local builds); ARG BUILD_FROM moved to the very top of the file, before any FROM — a multi-stage Dockerfile ARG declared between two FROM lines is only visible in the previous stage's RUN steps, not the next FROM (Buildx: "base name should not be blank").
• READMEs/DOCS drop the "first install 5–15 min" warning, replaced with the ~2 min ghcr.io-pull expectation.

Notes

• 95 tests pass (no Python changes in this release apart from the version bump).
• First-time installers still need ~3 GB free disk (PyTorch + nomic-embed-text-v1.5) and ~2 GB free RAM at runtime — only the wall-clock time to a ready state on first install drops.
• ghcr.io packages must be public for Supervisor to pull anonymously.

v0.4.5 — Cold-Start-Fix

Cold-Start-Fix: Add-on wirkt nicht mehr "tot" beim Container-Start

Auf einer frisch gestarteten HA-Instanz wirkte das Add-on nach Container-Restart bis zu ~30 s wie eingefroren — der Ingress-Tab lieferte 502, obwohl der Container "running" war. Ursache: das sentence-transformers-Modell (~10–30 s auf aarch64) und das Anlegen der Qdrant-Collection liefen synchron im FastAPI-Lifespan, blockierten damit uvicorn vom Port-Bind, und HA-Ingress proxied auf einen nicht-gebundenen Port.

Behoben

• app/main.py trennt Initialisierung in zwei Phasen: leichte Services (LLM-Client, SQLite-Conversation-Store) bleiben im Lifespan-Critical-Path; Embedder, Qdrant-Collection, Watcher und der Initial-Reconcile wandern in einen einzelnen Background-Task. Ein neues StartupState(phase, error)-Objekt auf app.state.startup trackt den Fortschritt: loading_embedder → creating_collection → indexing → ready. Lifespan yieldet jetzt in <1 s, uvicorn bindet Port 8000 sofort, die SPA lädt direkt.
• app/api.py — /api/status returnt während des Background-Tasks {status: "initializing", phase: ...}, bei einem Crash {status: "error", error: ...}, und in fully-ready-State weiterhin das gewohnte {status: "ok"}-Schema (Test-Apps ohne StartupState sind unverändert). 503er auf /api/query und /api/reindex liefern jetzt einen Retry-After: 5-Header.
• app/ui/app.js pollt /api/status alle 1.5 s solange die Phase initialisierend ist, surface den jeweiligen Phasentext im Index-Pill ("Lädt Modell …" / "Bereitet Index vor …" / "Indiziert (N) …"), und sperrt den Composer mit erklärendem Placeholder bis zur Phase indexing. Ab indexing ist die Eingabe wieder offen — Queries laufen gegen den teilweise befüllten Index, gleiche Semantik wie der Background-Reconcile in v0.4.4.

Hinweise

• 95 Tests grün (vorher 91). Vier neue Tests decken die initializing / failed / ready-Branches und den Retry-After-Header ab.
• Nicht via echtem docker run validiert: das CI baut weiterhin nur das Image, startet keinen Container — gleiche Lücke wie bei den v0.4.1–v0.4.3-Hotfix-Cycles. Falls der Cold-Start auf realer HA-Supervisor-Instanz regrediert, kommt ein v0.4.6-Hotfix hinterher.

v0.4.4 — Hotfix: Initial-Reconcile als Background-Task, kein 502 mehr beim Start

Hotfix — kein 502 mehr beim Container-Start

v0.4.3 bringt Container, Qdrant und Embedder sauber hoch — aber bei einer Erstinstallation mit vielen Markdown-Files hängt der FastAPI-Lifespan synchron im Initial-Reconcile: jede Datei braucht ~1-2 Sek auf aarch64-CPU für das Embedding, und solange der Sweep läuft, bindet uvicorn keinen Port. HA-Ingress gibt während dieser ganzen Zeit 502 zurück — bei großen Exports problemlos 30+ Minuten.

Fix

pipeline.reconcile_all() läuft jetzt als Background-Task statt im Lifespan-kritischen Pfad:

reconcile_task = asyncio.create_task(_run_initial_reconcile(pipeline))

Konkret: asyncio.to_thread() schiebt den synchronen Reconcile in einen Thread-Pool, der asyncio-Loop bleibt frei, Lifespan yieldet innerhalb von Sekunden. Uvicorn bindet sofort den Port, Web-UI lädt, Queries werden gegen den partiell befüllten Index beantwortet, der sich im Hintergrund weiter füllt.

Watcher wird VOR der Reconcile-Task gestartet, also werden Filesystem-Events während des Sweeps trotzdem verarbeitet. Die Hash-basierte Idempotenz der Pipeline garantiert: ein Watcher-Event während Reconcile hasht halt eine Datei die der Bulk-Sweep eh angefasst hätte — keine Duplikate, keine Race-Conditions.

Was du im Add-on-Log nach Update siehst

INFO:app.main:Starting BookStack RAG v0.4.4
INFO:app.embedder:Loading embedding model nomic-ai/nomic-embed-text-v1.5
INFO:app.embedder:Embedding model loaded — vector size 768
INFO:app.main:Initial reconcile dispatched as background task — API is now ready
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000
                                                  ← API ist hier sofort responsive
... (Reconcile läuft im Hintergrund weiter, du siehst „Indexed ..."-Zeilen tropfenweise)
INFO:app.main:Initial reconcile (background) complete: indexed=N unchanged=0 ...

Update auf v0.4.4

In HA: Update-Button auf der BookStack-RAG-Karte. Build dauert wegen Layer-Cache 1-2 Min. Container startet, innerhalb von 30 Sek (statt vorher endlos) ist die UI erreichbar. Kein 502 mehr.

/api/status zeigt während des Background-Reconciles:

• markdown_files: N — wie viele Files auf der Disk liegen (fix)
• indexed: K — wie viele schon im Qdrant-Index sind (wächst)

Also kannst du in der UI live verfolgen wie der Index wächst.

Was bleibt offen (für v0.5.0)

• home-assistant/builder GitHub-Action für vorgebaute Multi-Arch-Images auf ghcr.io
• image: in config.yaml → Erstinstall geht von 5-15 Min auf ~2 Min runter
• Plus: echter docker run-Smoke-Test im CI — würde diese Klasse von Bug („Container hochfahren und prüfen dass /api/status antwortet") in CI fangen statt erst beim User
• Damit hätten wir die ganze Hotfix-Serie v0.4.1 → v0.4.4 in einer einzigen CI-Phase abgefangen

Vollständiger Change-Log

CHANGELOG.md

v0.4.3 — Hotfix: libunwind8 für Qdrant

Hotfix — Qdrant startet jetzt wirklich

Mit v0.4.2 startet uvicorn, aber der Qdrant-Sidecar bricht sofort ab mit:

/usr/local/bin/qdrant: error while loading shared libraries:
libunwind-ptrace.so.0: cannot open shared object file

Damit failed dann der FastAPI-Lifespan in index.ensure_collection() mit Connection refused, der Container shuttet sich runter via [api] service exited — bringing the add-on down.

Ursache

Wir kopieren mit COPY --from=qdrant/qdrant:v1.17.1 /qdrant/qdrant /usr/local/bin/qdrant nur das Binary, nicht seine Runtime-Library-Dependencies. Upstream qdrant/qdrant installiert in seinem Image libunwind8 (enthält libunwind-ptrace.so.0); unsere debian-slim-Base hatte das nicht.

Fix

libunwind8 zur apt-get install-Schicht im Dockerfile hinzugefügt.

Drive-by-Fix

app/embedder.py benutzt jetzt bevorzugt SentenceTransformer.get_embedding_dimension() (neue Methode) statt get_sentence_embedding_dimension() (deprecated). Damit verschwindet die FutureWarning die im selben Log-Block auftauchte.

Update auf v0.4.3

In HA: Settings → Add-ons → BookStack RAG → Update. Build sollte mit Layer-Cache schnell durchgehen (~30 Sek-2 Min, weil nur die apt-Schicht neu gebaut wird; PyTorch + Modell bleiben aus dem Cache). Nach dem Update Start klicken.

Im Add-on-Log solltest du jetzt sehen:

[qdrant] starting on localhost:6333 (storage at /data/qdrant)...
[api] waiting for qdrant readiness on localhost:6333...
[api] qdrant ready after Xs — starting API
INFO:app.embedder:Loading embedding model nomic-ai/nomic-embed-text-v1.5
INFO:app.embedder:Embedding model loaded — vector size 768
INFO:app.main:Initial reconcile: indexed=N unchanged=0 skipped=0 failed=0
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Wenn alle Zeilen kommen → ready, Web-UI in der HA-Sidebar klicken.

Process-Note

Das war der zweite Runtime-Failure (nach v0.4.2's leerer-String-im-Schema), den unsere CI nicht abgefangen hat — der Smoke-Build ruft nur docker build, nie docker run. v0.5.0 wird das beheben: vorgebaute Images via home-assistant/builder werden bei der Publish-Action tatsächlich gestartet, das fängt diese Klasse von Bug. Bis dahin ist Real-Host-Install der einzige Gate.

Vollständiger Change-Log

CHANGELOG.md

v0.4.2 — Hotfix: Add-on startet mit leeren Source-Link-Feldern

Hotfix — Add-on startet jetzt auch mit leeren Source-Link-Feldern

Mit v0.4.1 baut das Image durch (debian + apt-get + PyTorch + Modell — alles gut). Aber der Add-on-Start brach mit Schema-Fehler ab:

App ... has invalid options: expected a URL. Got {...
    'bookstack_base_url': '', 'homeassistant_base_url': ''}

Ursache

In HA-Add-on-Schemas heißt das ?-Suffix „darf im Dict fehlen", NICHT „darf leer sein". Ein leerer String "" ist ein präsenter Wert und besteht den url-Validator nicht.

Konkret hatte ich in v0.4.0:

bookstack_base_url: url?
homeassistant_base_url: url?

llm_base_url (schon in v0.3.0) war richtigerweise als str? deklariert — daher gab es bei dem keinen Bug. Bei den zwei neuen Feldern habe ich's verbockt.

Fix

bookstack_base_url: str?
homeassistant_base_url: str?

Runtime-Validation in app/llm.py:build_source_links prüft sowieso auf Nicht-Leer bevor URLs gebaut werden — das Schema-Relaxing ist sicher.

Update auf v0.4.2

Im HA-Add-on-Store auf Update klicken. Build dauert dieses Mal ~5-6 Min (Layer-Cache von v0.4.1 hilft, aber Schema-Update reicht potentiell ein Re-Tag — Supervisor entscheidet). Danach Start klicken — diesmal sollte der Container hochkommen.

Wenn bookstack_base_url und homeassistant_base_url leer bleiben, fällt der ganze Source-Link-Mechanismus (Sources-Zeile pro <doc>-Block) weg — alles andere läuft normal. Sobald du beide Werte setzt, kommen klickbare Quellen-Links automatisch zurück.

Vollständiger Change-Log

CHANGELOG.md