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

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

```bash
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

```bash
docker buildx imagetools inspect python:3.13-alpine
```

```bash
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

```bash
docker pull python:3.13-alpine
```

```bash
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`:

```yaml
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.