Doku-Archiv für Silverscale: here.now vs. selbst hosten

Tiefenrecherche · 07.06.2026 · für Dennis (Silverscale Family Hub)

Frage: Wo soll das permanente Doku-Archiv des Projekts leben — als here.now-Site unter silverscale-docs.dennisfisch.de (Kandidat A) oder selbst gehostet auf dem VPS (Kandidat B)? Inklusive User-Hilfe + „?"-Buttons in der iOS-App.

1. Executive Summary — Empfehlung

Empfehlung: Selbst hosten auf dem VPS, als eigene Subdomain mit eigenem Traefik-Router ohne Auth — Variante B2 (docs.silverscale.dennisfisch.de).

Der entscheidende Faktor ist nicht Komfort, sondern die iOS-App. Das Frontend hat einen globalen Interceptor (app/frontend/src/lib/native.js, initExternalLinks), der jeden Cross-Origin-Link zwingend in ein SFSafariViewController-Sheet schickt. Eine here.now-Domain ist immer Cross-Origin, also würde jeder „?"-Button die App verlassen und ein Safari-Sheet öffnen (eigene Chrome, eigener Scroll, „Fertig"-Button zum Schließen). Eine VPS-Subdomain kann dagegen so behandelt werden, dass die Hilfeseite im selben WebView-Kontext (oder als gebrandetes In-App-Overlay) erscheint — kein Bruch.

Hinzu kommt: Die Docs liegen dann im Repo (versioniert, im 03:30-Backup, per Mac-Klon-Push deploybar) und gehorchen demselben Designsystem ohne Render-Umweg. here.now bleibt das richtige Werkzeug für Wegwerf-Reviews (MD-Doc publishen, URL teilen — so wie bisher), ist aber für ein permanentes, in die App eingebettetes Archiv das schwächere Zuhause.

Wenn maximale Bequemlichkeit + Null-VPS-Wartung wichtiger wären als die In-App-UX, wäre here.now sauber machbar (Custom Domain via CNAME, eigenes CSS, stabile Pfade, permanent bei aktivem Account). Aber der „?"-Button-Bruch und die Account-/Zahlungs-Abhängigkeit kippen die Waage Richtung Selbsthosten.

2. In einfachen Worten

Stell dir den „?"-Knopf in der App vor. Wenn die Hilfeseite auf here.now liegt, ist das für die App „eine fremde Website" — iOS klappt dann ein extra Browser-Fenster hoch, das man wieder wegklicken muss. Wenn die Hilfeseite dagegen auf deiner eigenen Adresse liegt, kann die App sie einfach selbst anzeigen, als gehörte sie dazu. Das fühlt sich an wie „in der App bleiben" statt „raus aus der App".

Dazu zwei praktische Punkte: (1) Die Docs liegen dann bei deinem Code — gleiche Sicherung, gleiche Versionsgeschichte, deploybar wie alles andere. (2) Du hängst nicht von einem fremden Account ab. Solange der VPS läuft, laufen die Docs. here.now ist super, um schnell mal ein Dokument zum Drüberschauen ins Netz zu legen — aber das dauerhafte Hilfe-Archiv sollte bei dir wohnen.

3. Top 10 Entscheidungsfaktoren (mit Konfidenz)

4. Body

4.1 Kandidat A — here.now im Detail

Quelle: https://here.now/docs (gründlich gelesen, read-only; Account existiert, publish.sh authenticated funktioniert bereits).

Custom Domains (unterstützt, nicht nur {slug}.here.now): - Subdomain wie silverscale-docs.dennisfisch.de: CNAME mit Wert fallback.here.now. - Apex (nicht relevant hier): zwei A-Records + CNAME www → fallback.here.now. - „SSL is provisioned automatically once DNS is verified." - Status: „pending until verified, then active"; Status-Endpoint-Abruf „also triggers on-demand verification" — kein fester Zeitrahmen genannt. - Anlage: POST /api/v1/domains (liefert DNS-Instruktionen), danach Link anlegen: POST /api/v1/links mit {"location": "", "slug": "<dein-slug>", "domain": "dennisfisch.de"} (location:"" = Root der Domain). Eine API-Call pro Verknüpfung nach DNS-Verifikation.

Cloudflare-Proxy — der wunde Punkt: Die Doku nennt nur Standard-DNS (A/CNAME) und sagt nichts zu Orange- vs. Grey-Cloud. Da here.now ein eigenes Zertifikat ausstellt, sobald der CNAME auf fallback.here.now zeigt, ist der proxied (orange) Modus problematisch: Cloudflare würde TLS selbst terminieren und müsste das Cert für silverscale-docs.* selbst haben (Cloudflare-for-SaaS / Orange-to-Orange). Der dokumentierte, einfache Weg ist DNS-only (grey cloud) — dann verifiziert und besichert here.now direkt. (Belege: Cloudflare Proxy-Status, Cloudflare for SaaS / Getting started.) Heißt konkret: Diese eine Subdomain liefe ohne Cloudflare-Schutz — anders als der Rest, der hinter Traefik/Cloudflare hängt.

Limits / Kosten (aus der Limits-Tabelle):

→ Free reicht für genau eine Custom Domain. Falls du here.now schon für andere Custom Domains nutzt, bräuchte es Hobby. Subdomain-Handles (yourname.here.now) brauchen laut Doku einen bezahlten Plan — die eigene Custom Domain dagegen ist auch im Free-Tier dabei (1 Stück). Konkrete Preise nennt die Doku nicht; einzuplanen, falls mehr als 1 Domain.

Sites & Updates: Publish via POST /api/v1/publish (Manifest → presigned Uploads → finalize). Update: PUT /api/v1/publish/:slug bzw. publish.sh --slug <slug>. Inkrementell: SHA-256 pro Datei, unveränderte Dateien werden übersprungen. Metadaten (Titel, Beschreibung, Passwort, TTL, SPA): PATCH /api/v1/publish/:slug/metadata.

Multi-Page / Unterordner / stabile URLs: Verschachtelte Ordner und mehrere HTML-Dateien funktionieren — „Each site gets its own subdomain: https://<slug>.here.now/", Pfade relativ zur Site-Root (index.html, guide/scan.html, report.pdf). → vorhersagbare Hilfe-URLs wie silverscale-docs.dennisfisch.de/hilfe/scan sind machbar.

Suche: Keine Volltext-Suche im Viewer dokumentiert. Es gibt nur eine Owner-API zum Auffinden von Sites (GET /api/v1/publishes/search?q=...). End-User-Suche im Archiv müsste man selbst (statisch/JS) bauen.

Versionierung: Keine Versionshistorie der Inhalte. Updates überschreiben den Slug; alte Stände sind weg (inkrementeller Deploy ist kein Versionssystem). Versionierung käme nur aus deinem lokalen Git der Quell-MDs.

Passwortschutz: Serverseitig erzwungen, übersteht Redeploys; aber passwortgeschützte Sites tauchen nicht auf öffentlichen Profilen auf. Für öffentliche Docs irrelevant.

Permanenz / Account-/Zahlungsrisiko: Authentifizierte (eigene) Sites sind „permanent by default" (optional TTL). Aber: kein dokumentierter Export für Sites oder Site-Data. Permanenz hängt am bestehenden Account + Zahlung. Mitigation: Quell-MDs liegen ohnehin im Repo → Re-Publish jederzeit möglich, aber die Live-URL ist nicht in deiner Hand.

Erzwungene Viewer / Branding: Keine gefunden — statische Uploads rendern dein HTML/CSS pur. Designsystem also frei. (Es gibt optionale Viewer-Metadaten für Titel/Beschreibung, kein Pflicht-Branding.)

Site Data / Proxy-Routes: here.now bietet sogar serverseitigen Storage (10 Collections/Site, 16 KB/Record, Rate-Limits) und Proxy-Routes für API-Keys — für ein statisches Doku-Archiv nicht nötig, aber nett zu wissen.

Fazit A: Technisch rund, schnell, wartungsarm, designfrei, stabile Pfade, permanent solange Account aktiv. Schwächen: kein Export/keine Versionierung/keine Suche, Cloudflare-Proxy muss aus, und — entscheidend — Cross-Origin für die iOS-App.

4.2 Kandidat B — Selbst hosten (Repo-Kontext gelesen)

Gelesen: CLAUDE.md, traefik/traefik.yml, docker-compose.yml. Setup: Traefik v3, exposedByDefault: false, Let's Encrypt DNS-01 über Cloudflare (Resolver cf), je Container Router-Labels. Die App (silverscale.dennisfisch.de) hängt komplett hinter Pocket-ID-Auth (Middleware, ADR-16).

Variante B1 — silverscale.dennisfisch.de/docs (öffentlicher Pfad auf der Auth-Domain)

• Sicherheit: Erfordert eine Middleware-Ausnahme für /docs auf derselben Domain, die sonst alles hinter Auth hält. Das ist genau die Art Ausnahme, die leicht zu breit gerät (Pfad-Präfix-Matching, Trailing-Slash, Encoding-Tricks). Blast-Radius: hoch — ein Fehler legt potenziell einen Auth-Bypass auf die Haupt-App. Widerspricht dem ADR-16-Geist.
• „?"-Button-UX: Same-Origin → öffnet in-place in der WebView, kein Safari-Sheet. Bestes UX-Verhalten überhaupt.
• Verdikt: Beste UX, aber sicherheitstechnisch der riskanteste Weg. Nur vertretbar mit sehr präziser, getesteter Pfad-Regel.

Variante B2 — docs.silverscale.dennisfisch.de (eigene Subdomain, eigener Router, KEINE Auth) — empfohlen

• Sicherheit: Eigener Traefik-Router, ohne Auth-Middleware, isoliert von der App-Domain. Kein Loch in der App-Auth — die Doku ist bewusst und sauber öffentlich. Blast-Radius: minimal. Passt perfekt zum bestehenden „ein Router pro Host"-Muster (wie pocket-id/silverscale).
• Build-Pipeline: Zwei Optionen —
• (a) Eigener winziger nginx-Container (nginx:alpine) mit Volume-Mount ./docs/site:/usr/share/nginx/html:ro + Router-Labels. Sauber getrennt, ~15 Zeilen Compose.
• (b) Static-Mount im bestehenden silverscale-Container + zweiter Router auf docs.* ohne Auth-Middleware, FastAPI served StaticFiles. Kein neuer Container, aber vermischt Belange. → (a) nginx-Container ist die klarste Trennung und empfohlen.
• DNS/Cert: Cloudflare-DNS-Record für docs.* (Proxy nach Geschmack — Cert kommt eh per DNS-01, also Orange-Cloud bleibt möglich, anders als bei here.now!). Traefik holt das LE-Zert automatisch (Wildcard oder per-Host).
• Wartung: MDs → HTML-Build (gleicher Renderer wie /tmp/render-design.py, als Repo-Skript) → docs/site/. Deploy = git commit + docker compose up -d bzw. Mac-Klon-Push. Im 03:30-Backup + voll versioniert.
• „?"-Button-UX: Cross-Origin zu silverscale.dennisfisch.de, also ohne Eingriff ebenfalls Safari-Sheet — aber das ist trivial steuerbar: Im initExternalLinks-Interceptor (native.js) eine Ausnahme für docs.silverscale.dennisfisch.de ergänzen (in-app/Overlay statt extern), oder die Docs als gleicher Origin-Pfad spiegeln. Volle Kontrolle, weil unser Code. (Bei here.now ginge das auch per Allowlist — aber here.now bleibt trotzdem fremde Domain ohne Branding-Garantie über die Zeit.)
• Verdikt: Beste Sicherheit, volle Kontrolle, gute UX (steuerbar), git-nativer Workflow. Empfohlen.

4.3 Bewertungsmatrix

Bewertung: ++ stark · + ok · ~ Einschränkung · - schwach

Lesart: A gewinnt nur bei Wartung, Aufwand-initial und Ausfall-Entkopplung. B2 gewinnt bei Kontrolle, Versionierung, Sicherheit, Kosten und ist bei der In-App-UX überlegen, weil wir den Interceptor besitzen. B1 hat die beste rohe UX, aber das Sicherheitsrisiko diskreditiert es.

4.4 Empfohlene Ziel-Architektur (B2)

docs.silverscale.dennisfisch.de
        |  (Cloudflare DNS-Record, Proxy nach Wunsch; Cert via Traefik DNS-01)
        v
   Traefik v3  -- Router "docs" (Host=docs.silverscale.dennisfisch.de)
        |           KEINE Auth-Middleware
        v
   nginx:alpine  (Volume: ./docs/site:/usr/share/nginx/html:ro)
        ^
   ./docs/site/  <- Build aus ./docs/src/*.md (Renderer im Repo, maritimes CSS)
        ^
   git commit + docker compose up -d  (oder Mac-Klon-Push)

Migrationsschritte: 1. Repo-Struktur: docs/src/*.md (Quellen) + docs/build.py (Renderer aus /tmp/render-design.py ableiten, maritime Tokens, Navigation/Index erzeugen) → Output docs/site/ (committed oder im Deploy gebaut). 2. Compose: nginx-Service mit traefik.enable=true, Host-Regel docs.silverscale.dennisfisch.de, entrypoints=websecure, tls.certresolver=cf, Port 80, read-only Volume. Keine Auth-Labels. 3. DNS: Cloudflare docs.silverscale.dennisfisch.de (A/CNAME auf VPS-IP). Cert kommt per DNS-01 → Proxy-Status egal. 4. „?"-Button-Konzept (siehe 4.5). 5. Optional Suche: statisches lunr.js/Pagefind beim Build erzeugen. 6. Wegwerf-Reviews bleiben bei here.now (publish.sh, MEMORY-Workflow) — das permanente Archiv zieht auf B2.

4.5 „?"-Button-Konzept

• Kern-Features (Scan, Wochenplan, Einkaufsliste, Tagebuch-Edit, Aktivitäten, PVG, Stammdaten) bekommen je einen ?-Button mit stabilem Hilfe-Slug, z. B. HELP_BASE + '/hilfe/scan'.
• HELP_BASE = 'https://docs.silverscale.dennisfisch.de'.
• Im Frontend eine kleine openHelp(slug)-Funktion. In der App (isApp) zwei saubere Optionen: 1. In-App-Overlay/Sheet mit eigenem <iframe>/WebView auf den Hilfe-Slug (bleibt im App-Look, eigener Zurück-Weg über den bestehenden Sheet-Stack) — empfohlen, weil es den Safari-Sheet-Bruch ganz vermeidet. 2. Oder docs.* in initExternalLinks whitelisten, sodass es NICHT als externer Link gilt (dann braucht es aber eine eigene Anzeige-Route).
• Im Web normaler Tab/Link.
• Vorhersagbare URLs = direkt verlinkbar, auch außerhalb der App teilbar.
• Latenz: same-VPS, statisches nginx → minimal; bei here.now CDN-schnell, aber Cross-Origin + Sheet-Aufbau kosten gefühlt mehr.

4.6 Offene Fragen

• here.now-Preise konkret: Free deckt 1 Custom Domain; nutzt du bereits eine andere? Dann Hobby nötig (Preis nicht in der Doku). Nicht abschließend geklärt.
• here.now Verifikations-Dauer für Custom-Domain-SSL: nicht beziffert.
• iframe-Einbettbarkeit der Hilfeseiten (für In-App-Overlay): bei B2 setzen wir die Header selbst (kein X-Frame-Options: DENY); bei here.now unbekannt, ob Framing erlaubt ist → für Option-1-Overlay riskant bei A.
• Cloudflare-O2O für here.now: ob Orange-Cloud doch ginge (Cloudflare for SaaS), nicht praktisch getestet — der dokumentierte Weg ist DNS-only.

5. Quellenverzeichnis

• here.now Dokumentation — https://here.now/docs (Abschnitte #domains, #urls, #links, #handle, #metadata, #spa-routing, #sitedata, #analytics, #limits, #proxy-routes), gelesen 07.06.2026, read-only.
• Repo: /home/dennis/silverscale/CLAUDE.md, traefik/traefik.yml, docker-compose.yml, app/frontend/src/lib/native.js, app/ios-shell/README.md, app/ios-shell/capacitor.config.json.
• Cloudflare DNS Proxy-Status
• Cloudflare for SaaS — Getting started
• Cloudflare for SaaS — Custom origin
• Capacitor Browser Plugin, Capacitor InAppBrowser, ionic-team/capacitor #5786 (external link opens in webview)

Hinweis: Recherche read-only. Keine Domains konfiguriert, keine Sites angelegt/geändert, keine mutierenden API-Calls.