UmbrelApps/Docs/Plannen/Actief/005-Webinterface/PLAN.md

# Webinterface - plan

> Gepromoveerd op 19-08-2026 vanuit `Plannen/Masterplannen/`, omdat het werk begonnen is: de pagina is
> herbouwd. Taken staan in [TAKEN.md](TAKEN.md), open punten in [OPEN.md](OPEN.md), de geschiedenis in
> [PROGRESS.md](PROGRESS.md).
>
> **De afhankelijkheid van Configuratie is vervallen.** Die stond er omdat de pagina de ingestelde
> waarden moet tonen. In het ontwerp dat er nu ligt haalt de pagina álles uit `status.json` en uit de
> umbrel-variabelen, en staat er geen enkele installatiespecifieke waarde meer in het bestand. Daarmee
> hoefde Configuratie er niet vóór, en is dit deel van Configuratie fase 2 meteen af.

## 1. Doel

De statuspagina toont verzonnen gegevens. De statuswaarden staan als de tekst `Online` in de HTML, het
domein staat er hardgecodeerd in en er wordt niets uitgelezen. De pagina meldt dus ook "Online" als
stunnel omgevallen is, en dat is erger dan geen pagina: hij wordt geraadpleegd juist wanneer er iets mis
lijkt, en geeft dan het verkeerde antwoord.

Als dit af is, toont de pagina alleen dingen die waar zijn, of hij zegt dat hij het niet weet.

## 2. Afbakening

Vastgesteld op 18-08-2026, na het zien van de pagina in bedrijf.

- De verzonnen status en het verzonnen logvenster eruit.
- **Blokhoogte en backend-status.** De hoogte via het Electrum-protocol, plus welke implementatie actief
  is en of hij antwoordt. Dit is meteen de echte gezondheidscontrole.
- **Certificaat:** geldig tot, resterende dagen, een zichtbare waarschuwing onder de dertig dagen, en het
  tijdstip van de laatste herlading.
- **Reactietijd van de backend**, en de geschiedenis daarvan als sparkline.
- Aansluiten op het design-systeem in `HomeGit/Docs/website-design-system.html`: donker-eerst met een
  lichte variant, tokens voor kleur en radius, en de bestaande componenten `card`, `card-stat`, `badge`,
  `alert` en `list-item`.
- **Verbindingsregels per client**, met kopieerknop. Toegevoegd 19-08-2026 op verzoek van de gebruiker.
  De ene wallet wil `domein:poort:s` op één regel, de andere wil host en poort in aparte velden met SSL
  aangevinkt, en juist die kleine verschillen kosten mensen tijd. De rijen komen uit
  [Referenties/Clients.md](../../Referenties/Clients.md) §4; wie er een bijzet, zet hem daar ook bij.
- **Een activiteitenlog**, zie §4e. Herziening van een eerder niet-doel.

## 3. Niet-doelen

- **Een backend of API.** Zodra de pagina iets moet opvragen, is er een proces nodig dat luistert, en dan
  is dit geen configuratie-app meer. De weg eromheen staat in §4.
- **Live logs, in de zin van een logvenster.** Ruwe logregels in de browser vragen precies de backend uit
  het vorige punt, en bij een TLS-proxy staan er verbindingsgegevens in. `docker logs` blijft de plek
  voor de echte logs. Wat er **wel** komt is een uitgedunde samenvatting per sessie; zie §4e. Dat is
  op 19-08-2026 herzien op verzoek van de gebruiker, en het is een andere zaak dan een logvenster.
- **Instellingen bewerken in de pagina.** Uitdrukkelijk zo besloten in het plan **Configuratie**.
- **Koersgegevens en koersgrafieken.** Besloten op 18-08-2026, na afweging. Het vraagt een externe API,
  en dan haalt de browser van iedereen die dit dashboard opent data op bij een derde partij. Bij een
  zelfgehoste Bitcoin-opstelling is dat precies het soort lek dat deze app juist dichtzet, en umbrelOS
  heeft er bovendien al widgets voor. **Alles op het dashboard komt uit lokale bronnen.**
- **Verbindingen per uur als grafiek.** Kan wel, maar bij één of twee wallets is die grafiek vrijwel
  leeg. Het activiteitenlog uit §4e dekt dezelfde vraag beter.
- **De blokhoogte zelf als grafiek.** Die loopt met ongeveer één per tien minuten omhoog, dus het is
  altijd dezelfde schuine lijn.
- **Blokken per uur, in welke vorm dan ook.** Geschrapt op 19-08-2026 door de gebruiker, nadat het als
  grafiek én als tegel op de pagina had gestaan. Het antwoordt op een vraag die de gebruiker niet heeft:
  of de node meekomt met het netwerk is de zorg van de Electrum-server en niet van deze proxy, en de
  blokhoogte zelf zegt dat al. Gevolg voor het ontwerp: `history` in `status.json` hoeft alleen nog de
  reactietijd te bewaren, want de sparkline is de enige afnemer.
- **De afweging Tor tegenover TLS op het dashboard.** Ook 19-08-2026, door de gebruiker. Die uitleg is
  positionering en hoort in de winkelbeschrijving in `umbrel-app.yml`, waar iemand staat te kiezen. Wie
  het dashboard opent, heeft al gekozen en komt iets nakijken. De onderbouwing blijft in
  [Referenties/Clients.md](../../../Referenties/Clients.md) §1 staan; die voedt nu alleen de marketing.

## 4. Ontwerp

### 4a0. Wél een backend, en waarom die er alsnog is

Herzien op 19-08-2026, nadat de gebruiker vroeg of de WebDAV-truc uit §4f van
**Configuratie** eigenlijk de gebruikelijke manier is om een backend in een Umbrel-app te bouwen. Het
antwoord was nee, en het onderzoek eromheen veranderde deze paragraaf.

**Wat umbrelOS zelf aanbiedt is één instelling per app: de afhankelijkheidskeuze.** In
`AppSettingsSchema` staat `dependencies: z.record(z.string())` en verder niets. Daarom kostte het wisselen
tussen Electrs, Fulcrum en ElectrumX twee regels: dát mechanisme bestaat. Er is géén generiek
instellingenformulier dat een community-app kan declareren, en de andere umbrel-haken (`hooks/`,
`exports.sh`, `*.template`) zijn er voor het opstarten en voor andere apps, niet voor de gebruiker.

**Apps die wél instelbare configuratie hebben, zijn zelf een backend.** Nginx Proxy Manager, Home
Assistant en Jellyfin brengen hun eigen server en hun eigen instellingenscherm mee, in hun eigen image.
umbrelOS levert dat scherm niet; de app doet het. De juiste conclusie is dus niet "umbrelOS heeft er iets
voor" maar "die apps hebben een backend".

**Besluit van de gebruiker: een tweede container met een klein programma.** Een officiële
`python:3-alpine`, met het script uit `agent.py.template` zodat het bij een update meekomt. Geen eigen
image, dus geen bouwstap, geen registry en geen multi-arch-gedoe. Dat laatste is de reden dat een eigen
image afvalt, niet de complexiteit van het programma.

Wat die keuze onderweg oploste, en dat was de eigenlijke aanleiding:

- **de shell-lus was aan zijn plafond.** Een certificaatdatum lezen, een JSON-RPC-verzoek doen, een
  geschiedenis bijhouden en een keuze valideren zijn geen dingen die je met `openssl` en `nc` aan elkaar
  knoopt zonder dat het stil verkeerde antwoorden gaat geven;
- **de controles op `openssl`, `nc` en de WebDAV-module vervallen alle drie.** De agent doet dat werk zelf
  met de standaardbibliotheek, dus de app hangt niet meer af van wat er toevallig in de nginx-image zit;
- **het hardgecodeerde domein is weg uit `docker-compose.yml` en `nginx.conf.template`.** De agent
  schrijft `cert.conf` met de paden die hij gevonden heeft, en nginx doet daar een `include` op. Daarmee
  is dat deel van **Configuratie** fase 2 af.

**Wat het kost.** Een tweede container, en een echt API-oppervlak in plaats van geen. Klein, maar niet
nul, en daarom staat de verantwoording bij de `location /api/` in `nginx.conf.template` en niet alleen
hier.

**nginx herladen kan de agent niet zelf**, want dat vraagt de Docker-socket en die is er bewust uit. De
agent zet een vlagbestand neer en de nginx-container herlaadt zichzelf zodra hij dat ziet. Die lus
verplaatst wat eerst de certificaatbewaking was, en doet nu alleen nog dit ene ding.

### 4a. Statusgegevens uit status.json

De pagina vraagt nooit iets aan een dienst die kan omvallen: de agent schrijft elke ronde een
`status.json`, en de pagina haalt dat op met `fetch` en vult zichzelf. Dat blijft de kern, ook nu er een
agent is; het alternatief, een pagina die live naar de backend vraagt, zou de pagina zelf laten hangen
als de backend hangt.

Wat er in staat: het domein en de poort waar de wallet heen moet, het adres en de naam van de backend, de
blokhoogte en de reactietijd, de einddatum van het actieve certificaat, de lijst met gevonden
certificaten, een geschiedenis van reactietijden over 24 uur, en de logregels. Plus het tijdstip van
schrijven, en dat is het belangrijkste veld van allemaal.

Wat de vorm oplevert:

- **de pagina kan niet meer liegen over "draait het".** Elk veld heeft een zichtbare onbekend-toestand en
  nooit een lege waarde, want een leeg veld leest als "in orde". Dit is de pagina die juist geraadpleegd
  wordt wanneer er iets mis lijkt;
- **oude gegevens zijn herkenbaar, en wel bij de waarde zelf.** Onder de blokhoogte staat "as of ... ago",
  de badge bij de backend gaat van groen naar grijs met "last answered", en de voettekst noemt het
  tijdstip. Dat is de enige manier waarop de pagina een gestopte agent kan opmerken.

  **Bewust geen melding bovenaan daarvoor.** Die heeft er even gestaan en is er op 19-08-2026 op verzoek
  van de gebruiker uit. De afweging is het opschrijven waard, want hij geldt voor elke volgende melding
  die iemand wil toevoegen: een banner die hetzelfde zegt als wat er drie regels lager bij het getal
  staat, voegt geen informatie toe maar wel gewicht, en dat gewicht gaat ten koste van de meldingen die
  wél iets nieuws zeggen. Een melding bovenaan is er voor iets wat je nergens anders ziet, zoals een
  ontbrekend certificaat;
- **de lus valt nooit stil.** Een mislukte ronde wordt gelogd en overgeslagen; stoppen zou de pagina op
  oude gegevens bevriezen zonder dat iemand het ziet.

### 4a1. De indeling van de pagina

Vastgesteld door de gebruiker op 19-08-2026, na het bekijken van de eerste versie.

**De volgorde, van boven naar beneden:** Electrum-server, de drie statustegels, de certificaatkeuze, het
activiteitenlog, en onderaan het instellen van je wallet. De regel erachter: **eerst waar je naar kijkt
als je iets nakomt, onderaan waar je naar kijkt als je iets instelt.** Dat laatste doe je één keer.

De laatste twee zijn op verzoek van de gebruiker omgedraaid ten opzichte van de eerste opzet. Dat pakte
beter uit dan alleen als voorkeur: het certificaatkader is nu het smalle kader links en het log het brede
rechts, waardoor de kolomgrens samenvalt met die van de rij erboven in plaats van ertegenin te lopen. En
logregels zijn monospace, dus die hebben de breedte beter nodig dan een lijst met keuzerondjes.

**Twee kaders zijn er één geworden.** "Point your wallet here" en "Setting up your wallet" stelden dezelfde
vraag, dus het verbindingsadres met de kopieerknop staat nu bovenaan het instelkader in plaats van in een
eigen kader erboven.

**Breed, met kaders naast elkaar.** Twaalf kolommen, en de rijen wisselen 5/7 en 7/5 af: de
Electrum-server naast de statustegels, het log naast de certificaatkeuze, en het instelkader vol breed.
Afgekapt op 1760px, want op een ultrawide monitor levert een kader van 2500px regels op die niemand leest.

**Elk kader is hetzelfde opgebouwd.** Een `card-head` met een titel in `t-h3`, dan de inhoud. Bijgesteld op
19-08-2026 door de gebruiker: de drie statustegels hadden een eigen kleine grijze kop in kapitalen, en dat
maakte ze een apart soort ding zonder dat daar een reden voor was. De titel gebruikt de token
`--text-primary` en niet letterlijk wit, want in de lichte variant is wit onzichtbaar.

Wat daarbij vastligt en niet per ongeluk mag verschuiven:

- **de leesvolgorde in de HTML ís de bedoelde volgorde.** Er staat nergens een `order` of een `row-start`
  die de opmaak laat afwijken van de bron, dus bij een smal scherm stapelt alles precies zoals het gelezen
  hoort te worden. Wie hier een kader bijzet, zet het op de goede plek in de HTML en niet op de goede plek
  in het raster;
- **de statustegels rekken mee met hun buur**, met de titel boven en het getal onder, want van zichzelf
  zijn ze lager dan het kader ernaast en dan staat er een gat rechtsboven. De onderregel van een tegel
  heeft daarvoor dezelfde hoogte als de sparkline, anders staat het getal van "Backend response" hoger dan
  de andere twee;
- **het logblok scrollt zelf horizontaal in plaats van af te kappen.** Met puntjes zou een smal scherm de
  bytes stil verbergen, en dat is dezelfde soort onwaarheid als een verzonnen statuswaarde;
- **twee kaders naast elkaar zijn even hoog**, en het langste bepaalt de rij. Wat mag meegroeien zegt dat
  zelf: het logblok en de certificaatlijst. Daardoor is de certificaatlijst een scrollend vak in plaats van
  een lijst die de pagina oprekt, en dat was nodig: een gedeelde certificatenmap kan er tientallen bevatten.
  Het aantal staat in de kop, want zodra er een scrollbalk is, is niet meer te zien hoeveel er onder de rand
  staan.

  **Bewust een lijst en geen dropdown.** De gebruiker vroeg op 19-08-2026 of een dropdown niet netter was,
  en dat is het visueel ook, maar het botst met wat dit besturingselement moet doen: je kiest hier op de
  hostnaam waarop je wallet verbindt, en dan wil je bron, naam en resterende dagen naast elkaar kunnen
  vergelijken. In een dropdown zie je er één per keer, en een verlopen certificaat kan er niet rood in
  omdat `option`-opmaak per browser verschilt. De hoogtewinst die de dropdown zou opleveren komt er met een
  scrollend vak ook, dus er hoefde niets ingeleverd te worden;

- **er is geen voetregel.** Er heeft er een gestaan met "Last reading ... ago" en het versienummer; die is
  er op verzoek van de gebruiker uit. De leeftijd stond al bij de waarden zelf, dus dat was een derde keer
  hetzelfde.

  Het **versienummer** is wel gebleven, klein achter de tagline als `v0.0.3`. Dat is een aparte afweging en
  hij viel andersom uit dan de rest van de voetregel: dit project verloor een keer een dag aan een wijziging
  die niet uitrolde door een niet-verhoogde `version`, en dan is "welke versie zie ik nu eigenlijk" precies
  de vraag die je stelt. Het staat in `--text-sec` en niet in `--text-ter`, want die laatste is in de lichte
  variant `#bbbbbb` op wit en op deze grootte niet te lezen.

### 4b. Waarschuwen op een aflopend certificaat

Met de einddatum in `status.json` is dit een vergelijking in de pagina zelf: onder de dertig dagen een
opvallende melding, verlopen een duidelijke fout. Dat is de enige echte toevoeging ten opzichte van nu,
en hij is goedkoop omdat de datum er toch al is.

### 4c. Welke backend er gekozen is

Die volgt uit `${APP_ELECTRS_NODE_IP}` en `${APP_ELECTRS_NODE_PORT}`, maar dat is een IP-adres en geen
naam. De adressen liggen per app vast (Electrs op `10.21.21.10`, Fulcrum op `10.21.21.200`, ElectrumX op
`10.21.21.199`), dus een vertaaltabel kan er een naam van maken. Dat is aardig, maar het is een tabel die
stilzwijgend veroudert als Umbrel de adressen wijzigt. Voorstel: het adres tonen, en de naam alleen als
extra wanneer hij in de tabel staat. Dan is de pagina bij veroudering minder informatief in plaats van
onwaar.

### 4e. Het activiteitenlog

Toegevoegd 19-08-2026, nadat de gebruiker vroeg of er iets over live client-aanroepen te tonen is, en
diezelfde dag bijgesteld naar logregels onder elkaar in plaats van een lijst met sessiekaarten.

**Eerst de grens, want die bepaalt de rest. Een regel per protocolaanroep kan niet.** De wallet doet zijn
verzoeken *binnen* één TLS-verbinding die hier getermineerd wordt en daarna als bytestroom naar de backend
gaat. nginx `stream` kent geen verzoeken, alleen verbindingen. Ze wél tellen zou betekenen dat de app de
Electrum-berichten van de gebruiker uitleest, en dat is precies het verkeer waarvoor deze app bestaat. Dat
is geen implementatiedrempel maar een ontwerpgrens, en hij hoort ook op de pagina te staan zodat niemand
denkt dat het log iets verzwijgt.

Wat er wél per regel in kan:

| Gebeurtenis | Waar het vandaan komt |
|-|-|
| `connect` | de verbindingsteller is opgelopen sinds de vorige ronde |
| ~~`traffic`~~ | vervallen op 20-08-2026, zie punt 2 onderaan deze paragraaf |
| `disconnect` | de `access_log`-regel van nginx, met duur en bytes |
| `probe` | een sessie die eindigde zonder één byte in beide richtingen. Toegevoegd 20-08-2026: een doorgestuurde poort wordt gescand, en zonder dit onderscheid gaf elke scan een rode `refused`-regel terwijl er niets geweigerd is. Bewust op de bytes en niet op de duur of de status: een scan die tien seconden open blijft is nog steeds een scan, en een echte sessie die na een halve seconde omvalt is nog steeds een storing |
| `refused` | de verbinding gaf wél verkeer door en liep daarna stuk. Dit is het geval dat rood mag zijn |
| `reload` | het certificaat is gewijzigd en nginx is herladen |
| `start` | de container is gestart en luistert |

Die regels komen als `log` in `status.json`, afgekapt op 24 uur. De pagina toont ze nieuwste bovenaan, in
een monospace-blok dat scrollt.

**Bewust niet gelogd: het IP-adres van de client en de bronpoort.** Dat is precies het soort gegeven dat
deze app van het netwerk af houdt, en om te zien dát het werkt is het niet nodig.

Twee dingen die eerst uitgezocht moeten worden, en die het bouwen kunnen blokkeren:

1. **Een `log_format` bevat nginx-variabelen met een dollarteken, en dit bestand is een template.** De
   invulling bij het starten vervangt die en zou ze leegmaken; dat is dezelfde valkuil die nu bovenaan
   `nginx.conf.template` beschreven staat. De uitweg is de `log_format` niet in het template te zetten
   maar door het `command`-blok in `docker-compose.yml` te laten wegschrijven als een `include`-bestand,
   want daar wordt een dollarteken al als `$$` ontsnapt. Te verifiëren.
2. **nginx `stream` schrijft zijn regel pas bij het sluiten van de sessie.** Een verbinding die twaalf uur
   openstaat, verschijnt dus pas na afloop, en dat is de normale toestand van een wallet. Daarom komen
   `connect` en `traffic` niet uit de log maar uit de lopende verbinding; anders lijkt een actieve wallet
   afwezig. **Uitgezocht en gebouwd op 20-08-2026, nadat de gebruiker meldde dat hij van zijn verbonden
   wallet niets terugzag:**

   - **`connect` komt uit `/proc/net/tcp`.** Kolom 2 is het lokale adres met de poort in hex, kolom 4 de
     toestand; tellen wat op `:C366` staat met toestand `01` geeft het aantal open wallet-verbindingen.
     Dat bestand geldt **per netwerk-namespace**, en daar zit de bevinding: de agent kan het niet lezen,
     want hij zit in een andere container. De teller staat daarom in de achtergrondlus van de
     nginx-container, die het aantal naar een bestand schrijft dat de agent oppikt. Zelfde patroon als de
     herlaadvlag, en om dezelfde reden: geen Docker-socket. Geteld wordt alleen het aantal;
   - **`traffic` vervalt.** Bytes van een lopende sessie zijn er niet af te lezen: `/proc/net/tcp` heeft
     geen tellers, en de interfacetellers van de container bevatten ook het dashboard- en backendverkeer.
     Wat er dan overblijft is een schatting die als meting leest, en dat is precies wat §4c verbiedt. De
     sessieregel bij het sluiten geeft de echte aantallen;
   - **de pagina toont de teller in de badge van het activiteitenlog** en niet als logregel alleen. De
     vraag is "is mijn wallet nu verbonden", en die hoort niet uit een lijst afgeleid te worden.

## 5. Het werk

Staat in [TAKEN.md](TAKEN.md), met de fase-indeling en wat er af is.

## 6. Open punten

Staan in [OPEN.md](OPEN.md).

## 7. Verificatie

Handmatig, want het gaat om wat er in een browser staat:

- de pagina toont het werkelijk ingestelde domein en de werkelijke poorten, niet die uit de HTML;
- na een certificaatvernieuwing verandert de einddatum op de pagina;
- **stunnel of de proxy stoppen laat de pagina niet "Online" tonen.** Dit is de controle die de aanleiding
  van dit plan afdekt en de enige die per se gedaan moet worden;
- een certificaat dat binnen dertig dagen verloopt, geeft een zichtbare waarschuwing.