UmbrelApps/Docs/Referenties/Images-pinnen.md

Images pinnen: de commando's

Naslag, geen plan. Wanneer dit gedaan wordt en waarom staat in het masterplan Publicatie; hier staan alleen de commando's en wat je uit de uitvoer moet halen.

Sinds 08-09-2026 staan er alleen nog eigen images in de composes, één per app, en die worden bij elke verhoging gepind door de digest uit de push-uitvoer over te nemen; tools/<app>/build.sh drukt de stappen af. Stap 1 en 2 hieronder gaan over het pinnen van een vréémde image en zijn daarmee naslag voor wie er ooit weer een bij zet. Lees dan eerst de volgorde-regel in KNOWLEDGE.md. Wat hieronder wél nog actueel is: de index-digest versus een platform-digest, zodra er multi-arch gebouwd wordt.

Alles hieronder draait op de Umbrel, want daar staat Docker. Lukt een commando niet, zet er dan sudo voor.

Waarom het niet één commando is

De eis is repo:versie@sha256:<digest>, en daar zitten drie dingen in die elk apart mis kunnen gaan:

• de tag moet specifiek zijn. python:3-alpine beweegt mee met elke nieuwe 3.x en is ook mét digest niet toegestaan. Stap 1 zoekt uit welke versie er nu achter zit;
• de digest moet die van de index zijn, niet die van één architectuur. Een platform-digest werkt op de machine waar je hem ophaalt en breekt op de andere; een Umbrel Home is arm64 en een zelfbouw meestal amd64;
• beide architecturen moeten erin zitten. Dat lees je in dezelfde uitvoer af.

Stap 1: welke versie zit er achter de bewegende tag

docker run --rm python:3-alpine python -V

docker run --rm nginx:alpine nginx -v

De uitvoer noemt bijvoorbeeld Python 3.13.7 en nginx version: nginx/1.27.4. Gebruik daarvan alleen het eerste deel in de tag, dus python:3.13-alpine en nginx:1.27-alpine, en niet de derde cijfergroep: een patchversie-tag bestaat niet altijd, en de tweede cijfergroep is specifiek genoeg om niet mee te bewegen met een nieuwe hoofdversie.

Stap 2: de index-digest van die tag

docker buildx imagetools inspect python:3.13-alpine

docker buildx imagetools inspect nginx:1.27-alpine

Twee dingen uit die uitvoer, en let op welke digest je pakt:

Name:      docker.io/library/python:3.13-alpine
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:AAAA...          <- deze, de bovenste
Manifests:
  Name:      docker.io/library/python:3.13-alpine@sha256:BBBB...
  Platform:  linux/amd64           <- deze moet erin staan
  Name:      docker.io/library/python:3.13-alpine@sha256:CCCC...
  Platform:  linux/arm64           <- en deze ook

De bovenste Digest: is de manifest-lijst en die hoort in de compose. De digests bij Manifests: zijn per platform; dat is precies de verwisseling die pas op de andere architectuur opvalt.

Stap 2b: als buildx er niet is

docker pull python:3.13-alpine

docker image inspect --format '{{index .RepoDigests 0}}' python:3.13-alpine

Een docker pull van een tag met meerdere architecturen zet de index-digest in RepoDigests, dus dit levert dezelfde waarde op als stap 2.

Maar het bewijst niets over de architecturen, en dat is hier geen theoretisch punt. De Umbrel van de gebruiker is amd64 (OS: Linux 6.12.85+deb13-amd64, uit de nginx-startlog van 20-08-2026). Een docker pull daar haalt de amd64-variant en zegt niets over arm64, terwijl arm64 wel een eis is en de helft van de Umbrels erop draait. Gebruik dus stap 2 als het kan, en zie deze terugval als "de digest opzoeken", niet als "de eis controleren".

Terzijde, uit diezelfde log: achter nginx:alpine zat op 20-08-2026 nginx 1.31.4. Stap 1 hoeft daarvoor dus niet eens gedraaid te worden zolang de app draait; docker logs van de server-container noemt de versie bij elke start.

Stap 3: de pin in de repo

Plak de uitvoer van stap 2 in de sessie. De pin gaat dan in docker-compose.yml:

image: python:3.13-alpine@sha256:AAAA...

Dat is een gewone commit met een versieverhoging in umbrel-app.yml, want de compose staat in de update-whitelist en wordt dus daadwerkelijk uitgerold.

Stap 4: het is onderhoud, geen eenmalige handeling

Een gepinde image krijgt geen beveiligingsupdates meer tot iemand de pin verhoogt. Deze vier stappen horen daarom bij elke release opnieuw gedaan te worden, niet één keer bij de inlevering.