UmbrelApps/Docs/Plannen/Masterplannen/Archief/Appstore.PLAN.md

# Appstore - masterplan

> **Status: nog niet actief.** Dit is één bestand en dat is bewust: er is nog geen `TAKEN.md`,
> `PROGRESS.md` of `OPEN.md`, want er wordt nog niet aan gewerkt. Bij promotie naar
> `Plannen/Actief/NNN-Appstore/` worden de paragrafen hieronder over die vier bestanden verdeeld; zie
> `HomeGit/Docs/Werkproces.md` §1b.
>
> Afhankelijk van: –

## 1. Doel

De app draait nu als een met de hand neergezette docker-compose die umbrelOS niet kent. Gevolg: na een
herstart van de Umbrel, of als een app waar deze van afhangt omvalt, moet er met de hand
`docker compose down` en `up` gedaan worden. Dit plan maakt er een echte Umbrel-app van in een eigen
community app store: een tegel met icoon, die umbrelOS zelf installeert, start en na een herstart weer
opbrengt.

Als dit af is, is de repo tegelijk de app store: de URL erin plakken in umbrelOS is genoeg om de app te
installeren, en een `git push` is genoeg om een update uit te leveren. De repo staat op de eigen
Git-server, `https://sc.kamenier-hamer.nl/sysop/ElectrumTLS.git`, en dat kan: umbreld doet geen enkele
controle op de hostnaam. Zie §4e voor wat dat wél afdwingt.

## 2. Afbakening

- De repo omzetten naar de vorm die umbrelOS voor een community app store verwacht.
- `docker-compose.yml` omzetten naar de moderne vorm: `app_proxy`, geen zelfgebouwd netwerk, geen
  handmatige host-poorten waar dat niet hoeft.
- De Electrum-backend via de afhankelijkheid aanspreken in plaats van via een hardgecodeerde
  containernaam, zodat Electrs, Fulcrum en ElectrumX alle drie werken.
- Een image die gepind kan worden, in plaats van `alpine:latest` met `apk add` bij elke start.
- Het manifest compleet en eerlijk maken: eigen icoon, eigen gallery, kloppende velden.
- De oude `install.sh` en `uninstall.sh` weghalen.

De volledige spec waar dit tegenaan moet, met bronvermelding per feit, staat in
[Referenties/Umbrel-appstore-spec.md](../../Referenties/Umbrel-appstore-spec.md). Die is bij het schrijven
van dit plan uitgezocht en hoeft niet opnieuw opgezocht te worden.

## 3. Niet-doelen

- **De hardgecodeerde waarden eruit halen.** Het domein `sync.kamenier-hamer.nl` en het Zoraxy-pad blijven
  in dit plan staan zoals ze zijn. Dat is het plan **Configuratie**, en het apart houden is bewust: een
  commit die tegelijk de structuur omgooit en de configuratie herontwerpt is niet meer na te lezen.
  Wel een harde koppeling: **de repo gaat pas naar GitHub als Configuratie af is**, want anders staat een
  persoonlijk domein en de indeling van een privé-server in een publieke repo. Zie open punt 3.
- **De web-UI eerlijk maken.** De pagina toont verzonnen status. Dat is het plan **Webinterface**. Hier
  wordt de pagina alleen verhuisd en aan `app_proxy` gehangen, niet herschreven.
- **Meerdere apps in de store.** De store krijgt de vorm die meer apps toelaat, maar er komt er één in.
- **Indienen bij de officiële Umbrel App Store.** Een community store is er juist om dat niet te hoeven.
  Als het later toch aantrekkelijk wordt, is de spec-eis grotendeels dezelfde, dus dit sluit niets af.

## 4. Ontwerp

### 4a. De repo-vorm

```
ElectrumTLS/
├── umbrel-app-store.yml              id: electrumtls
├── electrumtls-electrum-tls/
│   ├── umbrel-app.yml                id: electrumtls-electrum-tls
│   ├── docker-compose.yml
│   ├── entrypoint.sh
│   └── web/index.html
├── Docs/
├── README.md
└── CHANGELOG.md
```

De store-id is `electrumtls`, gekozen op 18-08-2026. De prefix-eis is hard: mapnaam en manifest-`id`
moeten gelijk zijn en allebei met de store-id beginnen.

### 4b. Backend-onafhankelijk, en waarom dat bijna niets kost

umbrelOS 1.3 heeft swappable dependencies. Fulcrum en ElectrumX declareren allebei `implements: [electrs]`
en hun `exports.sh` aliast `APP_ELECTRS_IP`, `APP_ELECTRS_NODE_IP` en `APP_ELECTRS_NODE_PORT` naar hun
eigen waarden. De gebruiker kiest de implementatie in de umbrelOS-instellingen; umbrelOS laadt de
`exports.sh` van de gekozen app.

Deze app hoeft daarvoor dus **geen keuzemechanisme te bouwen**. Het is dit:

```yaml
dependencies:
  - electrs
```

en in de compose `${APP_ELECTRS_NODE_IP}:${APP_ELECTRS_NODE_PORT}` gebruiken.

Twee vallen om te vermijden. De eerste: de huidige compose zet `ELECTRS_HOST=${APP_ELECTRS_IP}`, en dat
is de **web-UI-container** van Electrs, niet de Electrum-server; dat moet `APP_ELECTRS_NODE_IP` worden.
De tweede: alleen `IP`, `NODE_IP` en `NODE_PORT` worden gealiast, dus alles wat Electrs-specifiek is
(zoals `APP_ELECTRS_RPC_HIDDEN_SERVICE`) mag hier niet gebruikt worden.

### 4c. De image: nginx `stream` in plaats van stunnel

Het huidige `alpine:latest` plus `apk add stunnel` bij elke start is op drie manieren fout: het is niet
te pinnen, het faalt zonder internet, en het maakt de starttijd afhankelijk van een Alpine-mirror. De
app-store-eis is een image gepind op de multi-arch index-digest.

Er zijn drie wegen, en de aanbeveling is de derde:

1. **Eigen image bouwen** met een `Dockerfile` en een GitHub Actions-workflow die multi-arch naar GHCR
   duwt. Correct, maar het voegt CI, een registry en een tweede uitleverstroom toe aan een app die verder
   uit twee shellscripts bestaat.
2. **Een bestaande stunnel-image pinnen.** Er is geen onderhouden multi-arch stunnel-image die het
   vertrouwen waard is. Afgevallen.
3. **De officiële `nginx`-image gebruiken en de `stream`-module de TLS-terminatie laten doen.** Die image
   is multi-arch, wordt onderhouden en is gewoon te pinnen. Dan valt er meer weg dan alleen het
   bouwprobleem:
   - dezelfde container serveert de web-UI én termineert TLS, dus van drie containers blijft er één over;
   - een certificaatwissel wordt `nginx -s reload` **binnen** de container, dus de `cert-monitor` heeft de
     Docker-socket niet meer nodig. Die socket is nu read-only gemonteerd, maar read-only op de
     Docker-socket beschermt niets: wie de socket kan lezen kan containers starten en is daarmee root op
     de host. Dat weghalen is de grootste beveiligingswinst in dit plan;
   - een reload verbreekt bestaande verbindingen niet, een containerherstart wel.

   **Te verifiëren voordat hierop gebouwd wordt:** dat de officiële `nginx:alpine` daadwerkelijk met
   `--with-stream` en `--with-stream_ssl_module` gebouwd is. Dat is de aanname waar deze hele keuze op
   rust en hij is in één commando te controleren (`nginx -V`). Klopt hij niet, dan valt dit terug op weg 1.

De `awk`-splitsing van de certificaat-chain uit `entrypoint.sh` blijft bruikbaar en wordt overgenomen.

### 4e. De eigen Git-server als app store

De repo komt op `https://sc.kamenier-hamer.nl/sysop/ElectrumTLS.git`. umbreld valideert de URL alleen met
de `URL`-constructor en kloont met isomorphic-git; er is geen GitHub-eis. Wat er wél uit die aanroep volgt
en wat dus getest moet worden:

- **HTTPS, niet SSH.** De URL hierboven heeft de goede vorm.
- **Anoniem kloonbaar.** umbreld geeft geen inloggegevens mee, dus de repo moet in Gitea op publiek
  staan. Een privérepo werkt niet, en er is geen omweg.
- **Geldig certificaat op `sc.kamenier-hamer.nl`.** Node valideert de keten. Loopt die host al via
  Zoraxy met Let's Encrypt, dan is dit in orde, maar het is het controleren waard voordat het klonen
  onverklaarbaar faalt.
- **Alles op de standaardbranch.** Er wordt met `depth: 1, singleBranch: true` gekloond, dus een tag of
  tweede branch levert niets op.
- **De URL is de identiteit van de store.** Wijzigt hij, dan ziet umbrelOS een andere store en moet hij
  opnieuw toegevoegd worden. Kies hem dus één keer goed.

### 4d. Poorten

`port:` in het manifest is de **web-UI-poort** van de tegel, niet de TLS-poort. Dat staat nu op 50002 en
is daarmee fout.

De TLS-poort blijft een gepubliceerde host-poort; daar helpt `app_proxy` niet, want dat is voor HTTP.
Welke poort dat wordt is een open punt in **Configuratie**: Fulcrum bezet host-poort 50002 en botst dus
met de huidige keuze.

## 5. Het werk in grote lijnen

**Fase 1 - De repo-vorm.** `umbrel-app-store.yml` erbij, de app-bestanden naar
`electrumtls-electrum-tls/`, het app-id met prefix, `install.sh` en `uninstall.sh` eruit. Uitkomst: de
repo heeft de vorm die umbrelOS herkent.

**Fase 2 - De compose.** `app_proxy` erin, het externe `umbrel_main_network` en de handmatige
`APP_..._PORT`-plaatshouders eruit, de mounts op `${APP_DATA_DIR}` en `${UMBREL_ROOT}`. Uitkomst: een
compose die umbrelOS zelf kan draaien.

**Fase 3 - Backend-onafhankelijk.** `dependencies: [electrs]` en `${APP_ELECTRS_NODE_IP}` /
`${APP_ELECTRS_NODE_PORT}`. Uitkomst: de app werkt met Electrs, Fulcrum en ElectrumX zonder aanpassing.

**Fase 4 - De image.** `nginx:alpine` gepind op digest, `stream`-configuratie in plaats van stunnel,
`cert-monitor` samengevoegd en de Docker-socket eruit. Uitkomst: één gepinde container, geen `apk add`
bij start, geen socket.

**Fase 5 - Het manifest.** Eigen icoon en gallery in de repo, `port` op de web-UI-poort, `developer`,
`repo`, `support`, `submitter` en `submission` kloppend, `website` naar de eigen repo. Uitkomst: een
tegel die er klopt uitziet en niet naar andermans plaatjes wijst.

**Fase 6 - Installeren en verifiëren.** Store toevoegen in umbrelOS, installeren, en de dingen nalopen
die alleen op het apparaat te zien zijn: start hij mee na een herstart, komt hij terug als Electrs
omvalt, en werkt de TLS-verbinding vanaf een echte wallet.

## 6. Open punten

1. **Draait `nginx:alpine` met de `stream`- en `stream_ssl`-module?** De hele keuze uit §4c hangt hierop.
   **Moment:** als eerste taak van fase 4, vóór er iets herschreven wordt. **Eigenaar:** uitvoerder.

2. **Wat gebeurt er met een bestaande installatie?** Er draait nu een handmatig neergezette
   `electrum-tls` op de Umbrel. Die moet met de hand weg voordat de echte app geïnstalleerd wordt, anders
   vecht hij om de poort. Hoort daar een korte migratie-aanwijzing bij in de README, of doet de gebruiker
   dat eenmalig zelf? **Moment:** bij fase 6. **Eigenaar:** gebruiker.

3. **Wanneer wordt er voor het eerst gepusht?** **Beslist op 18-08-2026: meteen.** De repo staat sinds
   die dag publiek op `https://sc.kamenier-hamer.nl/sysop/ElectrumTLS.git`, met de
   installatiespecifieke waarden er nog in. Dat de repo publiek moest, stond niet ter discussie: umbreld
   kloont anoniem. Alleen de volgorde was een keuze, en die is bewust vóór **Configuratie** gevallen.

   Het gevolg dat vastligt: **`sync.kamenier-hamer.nl` en het certificaatpad staan nu in de publieke
   historie.** Ze eruit halen in Configuratie haalt ze uit de bestanden, niet uit de historie; daarvoor
   zou de historie herschreven moeten worden, en dat is bij een repo die anderen al gekloond kunnen
   hebben geen schoonmaak maar een breuk. Behandel het domein dus als bekend, en laat het geen argument
   worden om Configuratie uit te stellen: de winst daarvan zit nu in herbruikbaarheid, niet meer in
   geheimhouding.

4. **Eigen icoon.** Het manifest wijst nu naar het Electrs-icoon in andermans repo. Er moet een eigen
   SVG komen en een gallery-plaatje. Wie maakt die, en waar staan ze (in de repo of extern gehost)?
   **Moment:** fase 5. **Eigenaar:** gebruiker.

## 7. Verificatie

Er zijn geen tests in dit project en die zijn hier ook niet zinvol: de app is configuratie, geen code.
Wat er wél moet, en wat per se handmatig op het apparaat gebeurt:

- de store laat zich in umbrelOS toevoegen en de app verschijnt met icoon en tegel;
- installeren via de umbrelOS-interface werkt zonder SSH;
- **na `sudo reboot` komt de app vanzelf terug.** Dit is de aanleiding voor het hele plan en dus de
  belangrijkste controle;
- de app komt ook terug nadat Electrs handmatig gestopt en gestart is;
- een Electrum-wallet verbindt over TLS en verifieert het certificaat;
- omschakelen naar Fulcrum in de umbrelOS-instellingen laat de app werken zonder aanpassing.

Wat automatisch gecontroleerd kan worden, en de moeite waard is omdat het de fouten vangt die je niet
ziet: dat de YAML geldig is, dat het `id` in het manifest gelijk is aan de mapnaam, en dat elke `image:`
een `@sha256:`-digest heeft.