HarmenandClaude Opus 5
67ed9b603b
umbrelOS leest per store één repo, dus twee apps in twee repo's kan niet. Deze repo is de store en bevat vanaf nu Electrum Gate en het werk aan Evolu Relay. Opgezet als verse repo op verzoek van de gebruiker: de historie van ElectrumTLS en van EvoluRelay komt niet mee. Dat heeft één gevolg dat verder gaat dan opruimen. In de historie van ElectrumTLS staat het domein van de gebruiker en het certificaatpad, van vóór de opschoning van 19-08. Die komt hier niet in. Zolang die repo op de Git-server blijft staan verandert dat niets, dus het weghalen ervan is het laatste stuk van open punt 3 van het plan Appstore, en geen bijzaak. De store zelf hoefde niet te veranderen: store-id whatsnext, en dus blijft het app-id whatsnext-electrum-gate. Dat hangt aan het store-id en niet aan de URL, dus voor umbrelOS is dit dezelfde app in een andere store. Dat de store op 19-08 naar de maker genoemd werd in plaats van naar deze ene app, betaalt zich hier uit. Wat de documentatie betreft is dit één wortel voor beide apps, en dat was de reden om samen te voegen en niet de prijs ervan: de appstore-spec, het pinnen van images en de werkwijze golden al voor allebei en stonden in twee repo's naast elkaar. De kruisverwijzing die daarvoor nodig was (Referenties/Umbrel-appstore.md in de oude EvoluRelay-repo) is verdwenen; wat daarin stond over de plekken waar de relay een ander geval is, staat nu als ontwerp in het masterplan Umbrelapp §4. Botsende namen kregen een achtervoegsel met de app, en alleen die: Publicatie werd Publicatie-Gate en Publicatie-Relay, CHANGELOG.md werd CHANGELOG-electrum-gate.md. Proefopstelling kreeg 007, tussen de twee bestaande nummers, zodat de bovenkant van de reeks op tier-orde blijft staan. CONTINUE_HERE.md heeft een kolom App, maar de tiers lopen over beide apps heen: er is één volgorde van werken. Electrum Gate gaat naar 0.0.15, want website, repo, support, submission en icon wijzen nu naar UmbrelApps en zonder versieverhoging rolt dat niet uit. De release notes leggen aan de gebruiker uit dat hij de store opnieuw moet toevoegen. Of een geïnstalleerde app een wisseling van store-URL overleeft is nog steeds niet uitgezocht; dat blijkt bij het omzetten. Twee dingen in de plannen van Electrum Gate waren door deze verhuizing niet meer waar en zijn bijgewerkt: de taak "de repo hernoemen" in fase 7 is afgevinkt, en de repo-vorm in PLAN.md §4a toonde nog de store-id electrumtls, die al sinds fase 7 achterhaald was. Tests: 39 goed 0 fout en 54 goed 0 fout, niets overgeslagen. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
130 lines
7.1 KiB
Markdown
130 lines
7.1 KiB
Markdown
# UmbrelApps - projectspecifieke afspraken
|
|
|
|
De algemene werkafspraken staan in `HomeGit/CLAUDE.md` en worden hier niet herhaald. Hieronder alleen wat
|
|
eigen is aan dit project.
|
|
|
|
**Deze repo is één community app store met twee apps erin.** umbrelOS leest per store één repo, en dat is
|
|
de reden dat ze samen in één repo zitten in plaats van elk in een eigen. Eerst de regels die voor allebei
|
|
gelden, dan per app wat alleen daar geldt.
|
|
|
|
| App | Map | Toestand |
|
|
|-|-|-|
|
|
| **Electrum Gate** | `whatsnext-electrum-gate/` | draait op de Umbrel, wordt gebruikt |
|
|
| **Evolu Relay** | nog niet | bestaat uit plannen; zie het plan **Proefopstelling** |
|
|
|
|
**Zet geen CLAUDE.md of andere werkbestanden in een app-map.** umbreld kopieert bij installatie de héle
|
|
app-map naar `~/umbrel/app-data/<app-id>/` met `rsync --archive`, dus alles wat daar staat belandt op het
|
|
apparaat en in de back-up. Documentatie hoort in `Docs/`, tests in `tests/`, allebei in de repo-root.
|
|
|
|
## Umbrel-regels die je niet mag omzeilen
|
|
|
|
Deze gelden voor élke app hier, want het zijn eigenschappen van umbrelOS. Met bron in
|
|
[Docs/Referenties/Umbrel-appstore-spec.md](Docs/Referenties/Umbrel-appstore-spec.md).
|
|
|
|
**Geen accolade-variabelen in een `*.template` die er niet horen.** umbreld haalt bij elke start elk
|
|
`${...}` in zo'n bestand door `envsubst`, ook een variabele die niet bestaat, en die wordt dan leeg. Dat
|
|
sloopt Python-code, en in een nginx-config betekent het geen `$host`, geen `log_format` en geen
|
|
`access_log` met variabelen. Moet er tóch een dollarteken in een nginx-directive, dan hoort die directive
|
|
in een bestand dat het `command`-blok van de compose wegschrijft, want daar is `$$` te ontsnappen.
|
|
|
|
**Wat bij een update meekomt is een whitelist**: `docker-compose.yml`, `*.template`, `exports.sh`, `torrc`,
|
|
`hooks` en `umbrel-app.yml`. Al het andere bereikt een bestaande installatie nooit, zonder foutmelding.
|
|
Zet logica die later nog moet kunnen wijzigen dus in de compose of in een `*.template`, en nooit in een
|
|
los bestand of in een submap.
|
|
|
|
**Een wijziging zonder verhoging van `version` in `umbrel-app.yml` wordt niet uitgerold.** Geen melding,
|
|
geen fout; umbrelOS ziet hetzelfde nummer en doet niets. Dat heeft hier een keer een dag gekost. De
|
|
versies staan per app los van elkaar.
|
|
|
|
**Alle gebruikersstaat onder `${APP_DATA_DIR}/data/...`, en nooit erbuiten schrijven.** Elke map die bij
|
|
de eerste start moet bestaan, heeft een `.gitkeep` in de repo.
|
|
|
|
**Geen wachtwoord of ander geheim in de repo.** umbrelOS levert `${APP_PASSWORD}` en `${APP_SEED}` aan,
|
|
per installatie afgeleid. Deze repo is publiek, dus een literal is een gepubliceerd wachtwoord. Dat wordt
|
|
pas echt scherp bij Evolu Relay, want daar hoort een Postgres bij.
|
|
|
|
**Mapnaam gelijk aan het `id` in het manifest, en allebei met het store-id `whatsnext` ervoor.**
|
|
|
|
## Electrum Gate
|
|
|
|
### De tests draaien
|
|
|
|
```
|
|
python tests/test_agent_certificates.py
|
|
```
|
|
|
|
```
|
|
python tests/test_server_start_zonder_certificaat.py
|
|
```
|
|
|
|
Geen testrunner en geen afhankelijkheden: het zijn losse scripts die 0 teruggeven als alles goed is. Beide
|
|
horen bij "de suite", dus beide draaien voor een commit die deze app raakt. De uitvoer eindigt met een
|
|
regel "N goed, M fout". Er is geen watch-modus; de suite kost minder dan een seconde.
|
|
|
|
Twee dingen om te weten voordat je een groene uitslag vertrouwt:
|
|
|
|
- **sommige toetsen slaan zichzelf over en melden dat.** De vergelijking met `ssl` heeft de
|
|
certificaatwinkel van het besturingssysteem nodig, en de subjectAltName-toets heeft netwerk nodig. Staat
|
|
er `OVERGESLAGEN` in de uitvoer, dan is dat deel níet bewezen. Lees de uitvoer dus, tel niet alleen de
|
|
exitcode;
|
|
- **de suite dekt de agent, niet de pagina.** Alles in `index.html.template` is handwerk in een browser.
|
|
|
|
### Architectuurregels
|
|
|
|
**Geen Docker-socket.** De agent kan nginx daarom niet zelf herladen; hij zet een vlagbestand neer en de
|
|
nginx-container herlaadt zichzelf. Als je denkt de socket nodig te hebben, is er bijna zeker een
|
|
vlagbestand-oplossing.
|
|
|
|
**De pagina start altijd, ook zonder certificaat.** Het TLS-blok staat daarom niet in
|
|
`nginx.conf.template` maar in `stream.conf.template`, en het `command`-blok van de compose zet dat pas in
|
|
`/var/lib/gate/tls/` als de agent een `cert.conf` geschreven heeft; `nginx.conf` haalt die map met een
|
|
jokerteken op. Zet het blok niet terug in `nginx.conf`, hoe netjes dat ook staat: nginx weigert te starten
|
|
als een `listen ssl` geen certificaat heeft, en dan komt de pagina waarop je dat certificaat kiest ook niet
|
|
omhoog. Dat was de fout in 0.0.3. `tests/test_server_start_zonder_certificaat.py` houdt het dicht.
|
|
|
|
**Bij twijfel over een certificaat weigert de app.** Meerdere kandidaten zonder keuze van de gebruiker
|
|
levert géén automatische keuze op, ook niet "de nieuwste". Een verkeerd certificaat geeft een verbinding
|
|
die het lijkt te doen en pas bij de wallet stukloopt op naamverificatie, en dat is veel lastiger te vinden
|
|
dan een app die weigert en zegt waarom.
|
|
|
|
### Feiten
|
|
|
|
- App-id en mapnaam `whatsnext-electrum-gate`.
|
|
- De TLS-poort is **50022**, niet de conventionele 50002: die bezet Fulcrum op de host.
|
|
- De app leest de certificaatmap van Zoraxy alleen-lezen. Dat is het meest ongebruikelijke aan dit
|
|
pakket; zie het masterplan **Publicatie-Gate** §4.
|
|
|
|
## Evolu Relay
|
|
|
|
**Er is nog geen manifest, geen compose en geen code, en die horen er ook nog niet te komen.** Het eerste
|
|
dat er moet komen is een antwoord, niet een bestand: zie [Docs/CONTINUE_HERE.md](Docs/CONTINUE_HERE.md).
|
|
Speculatieve pakketbestanden zouden geschreven worden op aannames die het plan **Proefopstelling** juist
|
|
moet toetsen.
|
|
|
|
**De relay-code is niet van ons.** Dit pakketteert `trezor/trezor-suite-sync`; er worden geen wijzigingen
|
|
aan die software gedaan en er wordt niet bovenstrooms bijgedragen.
|
|
|
|
**Er zijn geen tests, want er is geen bron.** Werkte een sessie uitsluitend aan deze app en aan
|
|
documentatie, dan vervalt stap 4 van het sessie-protocol.
|
|
|
|
## Repo-feiten
|
|
|
|
- Remote: `https://sc.kamenier-hamer.nl/sysop/UmbrelApps.git`, **SHA-1** en **publiek**. Alle drie zijn
|
|
eisen en geen voorkeuren: umbreld kloont met isomorphic-git, en die spreekt alleen smart-HTTP, kan alleen
|
|
SHA-1, en krijgt geen inloggegevens mee.
|
|
- **Store-id `whatsnext`** in `umbrel-app-store.yml`. Elk app-id moet daarmee beginnen en gelijk zijn aan
|
|
de mapnaam.
|
|
- **Aangemaakt op 25-08-2026 zonder historie**, toen Evolu Relay erbij kwam. De voorganger was de repo
|
|
`ElectrumTLS`; die bevatte één app en zijn naam werd onhoudbaar bij een tweede. De historie is bewust
|
|
niet meegenomen. Zolang die oude repo op de Git-server staat, staat het domein van de gebruiker daar nog
|
|
in; zie het plan **Appstore**, `OPEN.md` punt 3.
|
|
- **De URL is de identiteit van de store.** Verandert hij, dan is het voor umbrelOS een andere store en
|
|
moet de gebruiker hem opnieuw toevoegen.
|
|
|
|
## Taal
|
|
|
|
Codecommentaar en documentatie zijn Nederlands. **Zichtbare tekst is Engels**: de pagina, `umbrel-app.yml`,
|
|
de meldingen die de agent naar de pagina stuurt, en de root-`README.md`, want dat is wat een bezoeker van
|
|
een publieke app store als eerste ziet. Die grens loopt precies langs "ziet de gebruiker dit": een reden
|
|
uit `choose()` belandt op het dashboard en is dus Engels, een commentaarregel erboven niet.
|