Maintaining Docker Hub

Maintaining Trilium's Docker Hub repositories

Everything below is done through one script, hub.mjs. Don't write throwaway Python or curl loops against the Hub API — the pagination caps, token expiry, rate limits and the storage model below each broke a hand-rolled attempt once.

H=.claude/skills/maintaining-docker-hub/hub.mjs
node $H stats triliumnext/trilium triliumnext/notes zadam/trilium   # pulls, stars, storage, weekly series
node $H tags triliumnext/trilium --prefix sha-                       # list; add --delete to delete
node $H inventory triliumnext/trilium                                # every manifest, untagged included
node $H purge triliumnext/trilium --older-than 7                     # dry run; add --delete to delete

Credentials come from docker login (~/.docker/config.json or its credsStore helper), or from DOCKERHUB_USERNAME + DOCKERHUB_TOKEN. stats and listing work for anyone signed in; deleting needs an owner of the namespace. Every delete is the user's call — run the dry run, report its numbers, and wait for an explicit go-ahead before --delete. A delete is not reversible.

The repositories

stats prints the weekly series Docker Hub embeds in the repository page (repoPullsData); it is published for organization repositories only, so zadam/trilium has none and its rate has to be derived from pull_count snapshots (the Wayback Machine has archived copies of hub.docker.com/v2/repositories/<repo>). Pulls count manifest requests, so auto-updaters (Watchtower, Diun) polling an unchanged tag inflate them — read them as "installations still tracking this", not downloads.

What is published where

.github/workflows/main-docker.yml builds on GHCR and copies to Docker Hub in its merge job:

• sha-<commit> — GHCR only. Until 2026-10 they were copied to Docker Hub too, which left 1,672 sha-* tags and ~10K untagged images there (974 GB in triliumnext/trilium, 658 GB in triliumnext/notes). The copy loop skips them now; do not undo that.
• main, v<version>, stable, latest — both registries. stable/latest only for a version tag without a hyphen.
• <branch-name> — both, from a manual run of the workflow on a branch (/ becomes -, e.g. feature-deployment_fixes). Delete it on Docker Hub once the branch is merged.

.github/workflows/mirror-legacy-docker.yml copies ghcr.io/triliumnext/trilium:stable to triliumnext/notes:stable+latest and zadam/trilium:latest after each stable release (the mirror_legacy job). The old version tags and zadam/trilium:0.63-latest are left alone, so pinned installs keep their version. A manual run with an empty tags input writes the release tags. The container contract (port 8080, /home/node/trilium-data, USER_UID/USER_GID) has not changed since 0.63, and a migration writes a before-migration backup; desktop clients of the old version stop syncing until replaced (SYNC_VERSION 32/36 → 39). The zadam account's token is a personal access token, which Docker Hub cannot restrict to one repository — it must carry an expiry date.

How Docker Hub stores images

These four facts decide every cleanup — verified against the live repositories in 2026-10:

1. Deleting a tag frees nothing. The image stays, pullable by digest, and keeps counting toward storage_size. Tag cleanup is cosmetic; storage only drops when the untagged image is deleted.
2. Deleting an image index deletes its per-platform images. Trilium's index holds 8 manifests (4 platforms + 4 attestations); after DELETE of the index all of them answer 404. So a purge deletes indexes only — never walk the children (that would be 13K wasted requests).
3. A digest a tag still uses cannot be deleted — the registry answers 403. That holds through an index: a sha-* build of a release commit has the same digest as v<version>, and its children are the release's children. purge also subtracts a keep list (every live tag's index and children), so the 403 is a second line, not the only one.
4. Untagged images are listed by GET /v2/namespaces/<ns>/repositories/<name>/manifests (last_evaluated_key pagination), which is what inventory and purge read. It is not in Docker's public API reference; the older /images endpoints return 404. It reports the per-platform images of a tagged index as untagged single manifests — they are not orphans.

storage_size tracks deletions within minutes. Its "before" values were real: the triliumnext/trilium purge took it from 974 GB to 18 GB, triliumnext/notes from 658 GB to 19 GB.