From 7c8a4b8c9ab063cf48ac4594f17dac53c8f84da7 Mon Sep 17 00:00:00 2001
From: marc <marc@shortcake.local>
Date: Sat, 29 Aug 2026 15:34:29 +0200
Subject: [PATCH] docs: die zwei Wege zur Leiste sauber getrennt
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Weg 1 fuer selbst geschriebene Apps, Weg 2 fuer fertig bezogene — mit dem
Vorher/Nachher an der Compose-Datei der App und dem, was der Einsetzer kostet.

Dabei richtiggestellt, dass Aether und InkNote die Leiste zur Laufzeit laden
statt sie ins HTML zu schreiben; die README beschrieb noch den alten Stand.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 README.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 93 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index bc2cf61..bab0672 100644
--- a/README.md
+++ b/README.md
@@ -156,18 +156,41 @@ offline, verschwindet das Symbol — lieber keins als eine Zahl von gestern.
 in der Leiste führt dorthin. Die Leiste liest über den Schlüssel und darf nichts
 schreiben.
 
-## Die Leiste in Aether / InkNote
+## Die Leiste in deine Apps bringen
 
-Eine Zeile ins `frontend/index.html` der App:
+Es gibt zwei Wege, und welcher gilt, hängt an einer einzigen Frage: **Kannst du
+den Quelltext der App ändern?**
+
+| | Weg 1 — selbst geschrieben | Weg 2 — fertig bezogen |
+|---|---|---|
+| Beispiele | Aether, InkNote | BentoPDF, Uptime Kuma, alles aus einem Image |
+| Einbau | die App lädt die Leiste selbst | ein nginx davor setzt sie ein |
+| Umstellen | eine Zeile in der `.env` | zwei Zeilen in der Proxy-Tabelle |
+| Layout | passt sich an (`--honeybar-h`) | bleibt, wie die App es macht |
+
+Beide Wege ergeben dieselbe Leiste; die App-Liste, die Farben und das Wetter
+kommen ohnehin aus HoneyOS.
+
+### Weg 1 — Apps, die du selbst schreibst
+
+Eine Zeile im HTML der App:
 
 ```html
-<script defer src="https://os.honeyy.duckdns.org/honeybar/honeybar.js"
+<script defer src="https://honeyos.duckdns.org/honeybar/honeybar.js"
         data-app="aether"></script>
 ```
 
 `defer` ist nicht optional: ohne wartet der Seitenaufbau der App auf das Skript.
 Ist HoneyOS langsam oder aus, soll die Leiste den Start von Aether nicht bremsen.
 
+**Aether und InkNote machen es einen Schritt anders — und das ist die bessere
+Art:** Sie laden die Leiste zur *Laufzeit*, die Adresse kommt aus ihrer eigenen
+`.env` (`HONEYBAR_ORIGIN`) über einen kleinen Endpunkt der App. Der Grund ist
+Erfahrung: Ein fertiges Abbild wird gezogen, nicht gebaut — was beim Bauen ins
+HTML geschrieben wird, lässt sich hinterher nicht mehr ändern. Und der Service
+Worker einer PWA hebt ganze Antworten auf, samt Kopfzeilen; eine ins HTML
+eingefrorene Adresse überlebt dort jede Konfigurationsänderung.
+
 `data-app` ist die Kennung aus der App-Liste. Die Liste holt sich die Leiste selbst von
 `/api/apps` — mit deiner HoneyOS-Sitzung, weil alle Adressen unter derselben Domain liegen.
 **Freigegeben sind nur die Ursprünge, die selbst als App eingetragen sind**: die App-Liste
@@ -183,11 +206,18 @@ hinein, ihre Stile nicht hinaus. Sie schiebt den Seiteninhalt um 32 px nach unte
 
 Vorschau ohne Einbau: `/honeybar/demo.html`.
 
-## Die Leiste in fremde Apps einsetzen (Reverse Proxy)
+### Weg 2 — fertige Apps: ein Einsetzer davor
 
 Für Werkzeuge, die man **nicht selbst geschrieben hat**, gibt es keinen
-`<script>`-Tag zum Ändern — den setzt der Reverse Proxy ein, während er die
-Seite durchreicht. Getestet mit nginx gegen eine App mit gzip und eigener CSP:
+`<script>`-Tag zum Ändern — den setzt ein kleiner nginx ein, während er die
+Seite durchreicht:
+
+```
+außen ──► Pangolin ──► leiste (nginx) ──► app:8080
+          TLS, Auth      setzt eine Zeile ein, reicht sonst nur durch
+```
+
+Ein Reverse Proxy hinter dem Reverse Proxy also, mit klarer Arbeitsteilung. Getestet mit nginx gegen eine App mit gzip und eigener CSP:
 
 ```nginx
 location / {
@@ -249,6 +279,63 @@ Ursprung, und die drei Hürden fallen auf einmal weg. Durchgereicht werden dabei
 ein pauschales `/api/` hinge sonst die ganze HoneyOS-Schnittstelle unter die
 Adresse der App.
 
+#### Was du an der Compose der App änderst
+
+Vorher — BentoPDF, wie es aus der Anleitung des Herstellers kommt:
+
+```yaml
+services:
+  bentopdf:
+    image: ghcr.io/alam00000/bentopdf-simple:latest
+    container_name: bentopdf
+    restart: unless-stopped
+    ports:
+      - '8888:8080'
+```
+
+Nachher:
+
+```yaml
+services:
+  bentopdf:
+    image: ghcr.io/alam00000/bentopdf-simple:latest
+    container_name: bentopdf
+    restart: unless-stopped
+    networks: [honeybar]        # statt ports:
+
+networks:
+  honeybar:
+    external: true              # legt der Einsetzer-Stapel an
+```
+
+Zwei Änderungen, mehr nicht:
+
+1. **`ports:` fällt weg.** Die App braucht kein Loch nach außen mehr — der
+   Einsetzer spricht sie im Docker-Netz unter ihrem Namen an (`bentopdf:8080`;
+   die `8080` ist der Port *im* Behälter und bleibt, die `8888` war nur die
+   Klinke an der Außenseite). Ginge Pangolin weiter direkt auf die App, wäre der
+   Einsetzer umgangen und die Leiste fehlte. Zum Nachsehen darf ein `ports:`
+   ruhig stehen bleiben — dann hast du zwei Wege: direkt ohne Leiste, über
+   Pangolin mit.
+2. **Das Netz `honeybar` dazu.** Es entsteht im Einsetzer-Stapel; hier wird es
+   nur als `external` mitbenutzt. Deshalb jenen Stapel zuerst starten.
+
+Dazu noch zwei Zeilen im Einsetzer (`$ziel` und `$appid`) und in Pangolin die
+Ressource von der App auf `leiste:80` umstellen. Fertig.
+
+#### Was es kostet
+
+Nicht viel, aber nicht nichts:
+
+- **Ein Ausfallpunkt mehr.** Ist der Einsetzer weg, sind die Apps dahinter weg —
+  nicht nur ihre Leiste. `restart: unless-stopped` ist deshalb Pflicht; ein
+  nginx, der nur durchreicht, fällt praktisch nie aus.
+- **Eine Stelle mehr zum Pflegen.** Je App zwei Zeilen, und beim Umbenennen
+  einer Adresse muss man daran denken.
+- **Ein Sprung mehr im Netz.** Im selben Docker-Netz nicht messbar.
+- **Nicht jede App muss dahinter.** Was ohne Leiste laufen soll, zeigt in
+  Pangolin weiter direkt auf die App. Das entscheidest du je App.
+
 **Fertige Beispiele:**
 
 - [`beispiele/bentopdf/`](beispiele/bentopdf/) — ein Dienst, alles über die