UmbrelApps/Docs/Plannen/Actief/004-Eigenimage/PLAN.md

# Eigenimage - plan

> **App: Electrum Gate**, met een korte paragraaf over wat het voor Evolu Relay betekent (§8). Voorgesteld
> door de gebruiker op 27-08-2026: van de uitvoerbare bestanden die nu in de app-map staan een image maken
> en die in het eigen Gitea-register zetten.
>
> **Gepromoveerd van masterplan naar `Actief/` op 27-08-2026**, toen **Webinterface** afgerond was; dat was
> de volgorde die de gebruiker die dag afsprak. Het origineel staat in `Plannen/Masterplannen/Archief/` en
> is historie: hier wordt gewerkt.
>
> Taken staan in [TAKEN.md](TAKEN.md), de open beslissingen in [OPEN.md](OPEN.md). §7 en §9 hieronder zijn
> daarheen verhuisd en staan er niet meer; wat hier blijft is het ontwerp en de afweging.

## 1. Waar dit over gaat, en wat het uitdrukkelijk níet oplost

Electrum Gate is de enige app in deze store zonder eigen image. Hij draait op `python:3-alpine` en
`nginx:alpine` en mount zijn eigen programmacode uit `app-data`. Dat is geen ongeluk maar een besluit uit
het plan **Appstore**: geen eigen image bouwen betekende toen geen bouwstap, geen register en geen
inloggegevens, en de app werkte.

Dit plan stelt dat besluit ter discussie, en het begint met wat het **niet** is:

**Dit is geen oplossing voor het updateprobleem, want dat is er niet meer.** De valkuil die dit project een
dag gekost heeft is dat een update alleen een whitelist ververst. Maar `*.template` staat in die whitelist,
en alle code van deze app staat inmiddels in een `.template`-bestand: `agent.py.template`,
`index.html.template`, `nginx.conf.template` en `stream.conf.template`. Een `git push` met een
versieverhoging bereikt een bestaande installatie dus gewoon. Wie dit plan verkoopt met "dan komen
wijzigingen eindelijk aan", verkoopt iets wat al werkt.

Er is één uitzondering en die is echt: **`icon.png` is geen template** en bereikt een bestaande installatie
nooit. Dat staat als zodanig in de compose. Voor een plaatje dat vrijwel nooit wijzigt is dat goed genoeg,
en het is te klein om dit plan op te bouwen.

Wat het wél is, staat in §3.

## 2. Wat er vandaag uit `app-data` gemount wordt

De inventaris, want dit is precies de lijst die in een image zou verdwijnen.

| Bestand | Container | Wat het is |
|-|-|-|
| `agent.py` | agent | het programma: certificaten lezen, de Electrum-server bevragen, `status.json` schrijven, de keuze aannemen |
| `nginx.conf` | server | de configuratie van de pagina en de proxy naar de agent |
| `stream.conf` | server | het TLS-blok voor poort 50022, bewust apart |
| `index.html` | server | het dashboard |
| `icon.png` | server | het plaatje in de kop en het tabblad |
| het `command`-blok | server | ruim honderd regels shell in `docker-compose.yml`: log-format, TLS aan- en uitzetten, de sessieteller en de herlaadlus |

Die laatste regel is de interessantste. Dat blok staat in de compose omdat de compose in de whitelist
staat, en het moet daar dollartekens ontsnappen als `$$` omdat umbreld elk `${...}` in een template
leegmaakt. Het is dus shell in een YAML-string met een eigen ontsnappingsregel eroverheen: het enige stuk
van deze app waar de vorm door de verpakking bepaald wordt en niet door wat het doet.

## 3. Wat een eigen image oplevert

Op volgorde van hoe zwaar het weegt.

1. **De programmacode gaat uit `app-data`.** Dat is de afwijking die de gebruiker zelf opmerkte op
   20-08-2026, uitgezocht in `Umbrel-appstore-spec.md`: bij andere apps staat in `app-data` alleen
   configuratie en data, want hun code zit in een image. Voor eigen gebruik is dat cosmetisch. Voor het
   masterplan **Publicatie-Gate** is het meer dan dat, want daar kijkt iemand anders naar het pakket.
2. **Het `command`-blok wordt een gewoon script.** Een `entrypoint.sh` in de image is te lezen, te
   controleren en desnoods te testen, en hoeft geen dollartekens te verdubbelen. Dat is de grootste
   inhoudelijke winst en de enige die de code zelf beter maakt.
3. **Eén digest in plaats van twee vreemde.** De pin-eis uit **Publicatie-Gate** gaat nu over
   `python:3-alpine` en `nginx:alpine`, images van iemand anders die bij elke beveiligingsupdate opnieuw
   gepind moeten worden. Met een eigen image pin je één ding dat je zelf uitgeeft. Let op de andere kant
   hiervan: de basisimage zit dan ín jouw image, dus het onderhoud verdwijnt niet, het verhuist naar het
   bouwrecept.
4. **`icon.png` wordt updatebaar**, zie §1.

## 4. Wat het kost, en dit is de reden dat het moment ertoe doet

**Elke wijziging wordt een bouwronde.** Vandaag is een wijziging aan het dashboard: bestand aanpassen,
`version` ophogen, committen, in umbrelOS updaten. Met een eigen image wordt dat: aanpassen, bouwen, naar
het register duwen, de digest opzoeken, de compose bijwerken, `version` ophogen, committen, updaten. Dat is
geen ramp, maar het is een veelvoud, en het moet op de machine met Docker gebeuren en niet op de machine
waar geschreven wordt.

Dat is precies het probleem met "nu": het plan **Webinterface** staat op tier A en itereert op
`index.html.template`. Een bouwronde per UI-wijziging remt het plan dat op dit moment het meeste oplevert.

**Multi-arch is een tweede kostenpost.** De eis is `linux/amd64` én `linux/arm64` in de manifest-lijst. De
Umbrel van de gebruiker is amd64 (vastgesteld 20-08-2026 uit de nginx-startlog), dus een `docker build`
daar levert de helft. Dat vraagt `buildx` met QEMU, en dat is trager en kan bij een Python-image met
gecompileerde afhankelijkheden stukgaan. Deze app heeft die afhankelijkheden niet, dus de kans is klein,
maar hij is niet nul en het is nog nooit geprobeerd.

## 5. Het register: Gitea werkt, en dat is bewezen

Dit is het deel waar het minste onzeker aan is, want de weg is al een keer gelopen.

Op 25-08-2026 faalde de eerste installatie van Evolu Relay met `pull access denied` op een image die alleen
lokaal gebouwd was. De verklaring staat in `Umbrel-appstore-spec.md`: umbreld haalt elke image zelf op via
de Docker Engine API, dus lokaal bouwen bestaat niet voor hem en `pull_policy: never` verandert daar niets
aan. De oplossing werd het Gitea-register op dezelfde server als de store,
`sc.kamenier-hamer.nl/sysop/evolu-relay`, gepind op tag plus digest.

Twee dingen zijn daarbij al vastgesteld en gelden hier onverkort:

- **anoniem halen moet werken**, want umbreld krijgt geen inloggegevens mee. Controleer dat met een
  uitgelogde pull in dezelfde context waarin je inlogde, anders meet je je eigen sessie. Het commando staat
  onderaan `tools/evolu-relay/build.sh`;
- **het bouwrecept hoort in `tools/`**, nooit in de app-map. Een `Dockerfile` staat niet in de
  update-whitelist, dus bouwen-in-de-app kost bij elke versie een deïnstallatie.

## 6. Hoe het eruit zou zien

Eén image, niet twee. De agent en nginx blijven wel twee containers, want ze doen verschillend werk en de
sessieteller moet in de netwerk-namespace van nginx zitten; maar één image met beide erin scheelt een
bouwrecept, en `nginx` plus `python3` in één alpine is klein.

```
tools/electrum-gate/
  Dockerfile      de basisimage, agent.py, de nginx-configuratie, de pagina, entrypoint.sh
  build.sh        pin op de basisimage, bouwt multi-arch, duwt naar het register, drukt de digest af
```

Wat er in de app-map overblijft: `docker-compose.yml`, `umbrel-app.yml`, `icon.png` en `data/` met zijn
twee `.gitkeep`-bestanden. De compose houdt zijn `environment`-blok, want dat is hoe
`${APP_ELECTRS_NODE_IP}` binnenkomt, en die weg is op 27-08-2026 juist bewezen bij de omschakeling naar
Fulcrum.

Eén ding om bij het ontwerp niet over te slaan: `index.html.template` bevat vandaag
`${APP_ELECTRS_NODE_IP}:${APP_ELECTRS_NODE_PORT}`, ingevuld door umbreld bij het starten. Zit de pagina in
de image, dan bestaat die invulling niet meer en moet het adres langs de omgeving naar binnen, bijvoorbeeld
doordat de agent het in `status.json` zet en de pagina het daaruit leest. Dat is werk dat nu nog gratis is
en straks niet meer.

## 7. Open punten

Verhuisd naar [OPEN.md](OPEN.md) bij de promotie op 27-08-2026. Het gaat om drie vragen: blijft het
Gitea-register ook bij publicatie de bron, wordt het één image of twee, en waar wordt er gebouwd. De eerste
moet vóór de eerste taak beantwoord zijn.

Dit kopje blijft staan met deze verwijzing en is niet weggehaald, want de nummering van de paragrafen
hierna wordt elders aangehaald.

## 8. Wat dit voor Evolu Relay betekent

**Herschreven op 30-08-2026, want de vorige versie van deze paragraaf gokte verkeerd.** Daar stond dat het
bouwrecept van die app misschien zou vervallen omdat de kale `docker.io/evoluhq/relay:latest` de weg zou
worden, en dat je daarom niets aan dat recept moest verbeteren. Die verwachting is ingehaald: de app draait
sinds 28-08-2026 op een **eigen** image, omdat wij twee terugroepfuncties aan `createRelay` meegeven en die
in de gepubliceerde image niet zitten. Het recept in `tools/evolu-relay/` is dus geen tijdelijke toestand
maar de vaste weg.

Wat daarmee de stand is, en het is minder ver dan hier stond:

- **de relay zelf: klaar.** Eigen image, eigen recept, register gekozen, anonieme pull gecontroleerd, en
  gepind op tag plus digest bij elke verhoging. Voor dat deel is dit plan uitgevoerd;
- **de agent en de pagina: niet.** Die zitten daar precies zoals bij Electrum Gate: `agent.py.template`,
  `index.html.template` en `nginx.conf.template` in de app-map, gemount in `python:3-alpine` en
  `nginx:alpine`. Alles in §1 tot §4 geldt dus onverkort ook voor die app;
- **multi-arch: open**, want ook dat recept bouwt vandaag één architectuur. Dat staat bij
  **Publicatie-Relay**.

**De volgorde die hieruit volgt en die verder reikt dan dit plan:** zolang de agent en de pagina op vreemde
images draaien, valt er voor die twee niets zinnig te pinnen, want ze verdwijnen hier. Dat is de regel in
[KNOWLEDGE.md](../../../KNOWLEDGE.md), en Evolu Relay is er het tweede geval van.

Wat wél blijft gelden: **trek het werk aan de relay-image niet in dit plan.** Niet meer omdat het recept
misschien weggaat, maar omdat het dat níet doet en het al af is. Wat hier hoort is de agent en de pagina,
voor beide apps.

## 9. Waarom dit nú actief is

**Beslist door de gebruiker op 27-08-2026: na Webinterface**, en dat moment is er. Dat was dezelfde
afweging als waarom de pin-eis in **Publicatie-Gate** op "niet nu doen" staat: zolang er nog gedraaid en
verbeterd wordt, betaalt elke wijziging de bouwronde uit §4 en levert het niets op wat er dan ontbreekt.
**Webinterface** iterereerde die dag juist op de pagina, en dat was het werk dat er het meeste onder zou
lijden. Dat plan is dezelfde dag afgerond en naar tier B gezakt.

Het valt daarmee ook samen met het werk dat toch aan de compose gedaan moet worden vóór de inlevering uit
**Publicatie-Gate**: het pinnen en het kaal maken van het app-id vragen allebei een herinstallatie, en die
kun je één keer doen in plaats van drie keer.

**Wat dit niet is: een harde afhankelijkheid.** Technisch kon dit plan altijd al. De volgorde was een
keuze, geen feit over het plan.