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/. 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.