UmbrelApps/Docs/KNOWLEDGE.md

# Duurzame kennis over UmbrelApps

Cross-plan kennis: dingen die blijven gelden en die geen enkel plan bezit. Wat bij één plan hoort staat
daar; wat naslag is staat in [Referenties/](Referenties/). Geldt een stuk maar voor één van de twee apps,
dan staat dat in de kop.

## Pinnen komt ná een eigen image, niet ervoor (beide apps)

Vastgelegd 30-08-2026 op aanwijzing van de gebruiker, nadat de suite voor de zoveelste keer meldde dat
`python:3-alpine` en `nginx:alpine` niet gepind zijn. De verleiding is dan om dat "even te doen". **Doe het
niet in die volgorde.**

De keten die eronder ligt, van achter naar voren:

1. **de officiële appstore eist gepinde images.** Dat is de reden dat het op de lijst staat, en het staat in
   de masterplannen **Publicatie-Gate** en **Publicatie-Relay**;
2. **maar vóór inleveren gaat de app-inhoud eerst een eigen image in**, want dat is wat het plan
   **Eigenimage** doet. De agent en de pagina zitten nu als `*.template` in de app-map en worden door
   `python:3-alpine` en `nginx:alpine` uitgevoerd;
3. **en dan bestaan die twee images er niet meer**, of in elk geval niet meer als de plek waar onze code
   uitgevoerd wordt. Wat je gepind had, is dan weg.

**De regel: pin alleen een image die er na Eigenimage nog staat.** In de praktijk is dat de image die je
zelf uitgeeft, en die is er precies één per app.

Stand op 08-09-2026: Electrum Gate draait op zijn eigen image sinds 0.1.0, gepind, en zijn twee vreemde
images zijn weg. Evolu Relay heeft sinds 0.6.0 alles in zijn eigen image; de pin daarvan komt erbij bij de
eerste push. Daarmee is de keten hieronder afgelopen en is er per app precies één image om te pinnen. De
regel blijft staan voor wie er een vreemde image bij zet.

Twee dingen die dit níet zegt, want anders slaat het de andere kant op door:

- **de eigen image pinnen doe je wél meteen**, bij elke verhoging. Dat is geen toekomstig werk maar de
  gewone gang van zaken; Evolu Relay doet dat sinds 25-08-2026. Zie de valstrik in de compose daar: een
  óude digest onder een níeuwe tag levert stilzwijgend de oude image, dus laat de digest er even ván af
  zolang de nieuwe niet geduwd is;
- **de melding in de suite blijft staan en dat is goed.** `test_appstore_vorm.py` drukt de pinstatus af en
  toetst hem met opzet níet, juist zodat dit zichtbaar blijft zonder de suite rood te maken. Zet die toets
  er dus niet "even" bij: dan staat de suite rood tot Eigenimage klaar is, en een suite die altijd rood
  staat wordt niet gelezen.

Waarom dit hier staat en niet in één plan: de eis komt uit **Publicatie**, de oorzaak zit in **Eigenimage**,
en de taak staat in **Umbrelapp** en **Appstore**. Vier plannen, en geen van de vier bezit het. De
onderbouwing van punt 3 staat wel al uitgeschreven in **Eigenimage**, `PLAN.md` §3: met een eigen image pin
je één ding dat je zelf uitgeeft, in plaats van twee images van iemand anders die bij elke
beveiligingsupdate opnieuw gepind moeten worden.

## De app is voor eigen gebruik, niet voor distributie (Electrum Gate)

Vastgelegd 18-08-2026 op aangeven van de gebruiker. De repo is publiek, maar dat is een **technische
voorwaarde en geen publicatiedoel**: umbreld kloont een community app store anoniem en kan geen
inloggegevens aanbieden, dus privé kan niet. De app is bedoeld voor één Umbrel, die van de gebruiker.

Waarom dit opgeschreven staat: het is het soort context dat een latere sessie niet kan afleiden uit de
code, en dat zonder vermelding tot werk leidt dat niemand gevraagd heeft. Concreet stuurt het deze
afwegingen:

- **Generiek maken is geen doel op zich.** Configuratie uit de code halen blijft nuttig, maar de reden is
  dat een domeinwijziging of een poortbotsing anders een zoektocht door drie bestanden wordt, niet dat
  iemand anders de app moet kunnen draaien. Weeg extra instelbaarheid dus tegen die maatstaf.
- **Presentatie mag mager blijven.** Een eigen icoon is nuttig, want dat is de tegel die de gebruiker
  dagelijks ziet. Gallery-afbeeldingen, uitgebreide release notes en een nette `submitter` zijn dat
  nauwelijks: die zijn er voor een winkelpagina die niemand bezoekt. Doe wat het manifest verplicht en
  niet meer.
- **Het domein in de publieke historie is een geaccepteerd feit.** De repo is gepusht vóór de opschoning,
  bewust, met als afweging dat een niet-aangekondigde repo op een eigen server niet gevonden wordt. Haal
  dat niet opnieuw op als bezwaar en stel er geen werk voor uit; zie het plan **Appstore**, `OPEN.md`
  punt 3.
- **Achterwaartse compatibiliteit is geen eis.** Er zijn geen andere installaties. Een wijziging die de
  configuratie of de app-id verandert mag gewoon, mits de gebruiker weet dat hij één keer opnieuw moet
  installeren.

Wat het **niet** verandert: de eisen van umbrelOS zelf. Prefix in het app-id, `app_proxy`, gepinde images
en een geldig manifest zijn geen etiquette maar voorwaarden om te starten. Zie
[Referenties/Umbrel-appstore-spec.md](Referenties/Umbrel-appstore-spec.md).