Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
docs(docker): add a Docker Hub maintenance skill and developer page
Elian Doran3cf1557bc9e6
diff --git a/.claude/skills/maintaining-docker-hub/SKILL.md b/.claude/skills/maintaining-docker-hub/SKILL.mdnew file mode 100644index 0000000000..f3a88fd031--- /dev/null+++ b/.claude/skills/maintaining-docker-hub/SKILL.md@@ -0,0 +1,135 @@+---+name: maintaining-docker-hub+description: Use when working on Trilium's published Docker images on Docker Hub or GHCR rather than on the Dockerfiles — "how many pulls does the image get?", "why is the Docker Hub repository so big?", "clean up old tags", "delete untagged images", "which tags do we publish?", the legacy repositories (triliumnext/notes, zadam/trilium) and their mirroring, the main-docker.yml copy-to-Docker-Hub step, mirror-legacy-docker.yml, Docker Hub categories, stars or the overview. Includes hub.mjs (stats, tag listing/deletion, the manifest inventory and a safe untagged-image purge, all dry-run by default) and the storage model that decides how a cleanup works. Do NOT use for building or running the image locally (see the Developer Guide's Docker page).+---++# Maintaining Trilium's Docker Hub repositories++Everything below is done through one script, [hub.mjs](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.++```bash+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++| Repository | Role | Pulls / week (Sep 2026) | Credentials in CI |+| --- | --- | --- | --- |+| `triliumnext/trilium` | the image | ~140K | `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN` |+| `ghcr.io/triliumnext/trilium` | build target; every tag, `sha-*` included | — | `GITHUB_TOKEN` |+| `triliumnext/notes` | pre-rename image, last own build v0.95.0 | ~29.6K | same as the image |+| `zadam/trilium` | the original Trilium image, last own build 0.63.7 | ~24K (from totals) | `zadam` + `ZADAM_DOCKERHUB_TOKEN` |++`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.++## Recipes++**Clean a repository** (after a burst of unwanted tags, or periodically):++1. `node $H tags <repo> --prefix <p>` → report the count → with consent, `--delete`. The listing+ returns at most 1,000 tags and its `count` lags several minutes; re-run until it reports 0.+2. `node $H purge <repo> [--older-than N]` → report the dry run → with consent, `--delete`.+ `purge` refuses to run while the repository has 1,000+ tags, because the keep list would be+ incomplete — finish step 1 first.+3. Verify: `docker manifest inspect <repo>:<tag>` for `latest`, `stable`, `main` and a couple of+ versions, and `node $H stats <repo>` for the storage figure.++About 60–250 deletes a minute at the default `--concurrency 4`; the rate varies by time of day.++**Open issue — `main` keeps leaving untagged images.** Each push to `main` moves the `main` tag and+leaves the previous index untagged on Docker Hub: ~12 a day in early 2026-10, ~640 MB each. Either+keep `main` on GHCR only (as with `sha-*`; then document `ghcr.io/triliumnext/trilium:main` for+anyone tracking it) or run `purge --older-than 7` periodically. Until one lands, expect the+inventory to show recent untagged indexes.++## Traps++- **Docker Hub's _Image Management_ page shows the per-platform images of tagged indexes as+ untagged** and has no "untagged" filter. Never tell the user to bulk-delete untagged _Image_ rows+ there — it breaks `docker pull` of releases. Indexes only, or use `purge`.+- **Two tokens, two lifetimes.** The Hub API (`hub.docker.com`) wants a JWT from+ `POST /v2/auth/token`; the registry (`registry-1.docker.io`) wants one from `auth.docker.io` with+ scope `repository:<repo>:pull,push,delete`. Both expire after minutes; `hub.mjs` renews on 401.+ A long run that does not renew dies at ~650 requests with a wall of 401s.+- **Rate limits.** The Hub API answers 429 after a few thousand requests; the script backs off.+ Don't probe tags one by one anonymously — it hits the limit within a minute.+- **Stopping a background run:** `pkill -f "hub.mjs purge"` also matches the shell that issued it if+ the pattern appears in that command line. Use the PID, or `ps -eo pid,args | grep "[n]ode .*hub.mjs"`.+- **GHCR and Docker Hub digests match only for images CI copied** with `crane copy` (all of+ `triliumnext/trilium`, and `triliumnext/notes` from v0.95.0). Older `triliumnext/notes` images+ were built per registry. The inventory makes GHCR unnecessary as a digest source anyway.++## Visibility++- Categories (`stats` prints them): the knowledge-base peers use _Content management system_+ (Wiki.js, BookStack, MediaWiki, XWiki, Outline, Docmost); `triliumnext/trilium` adds _Machine+ learning & AI_. Most note apps set none.+- Stars need a signed-in visit to the repository page, and `docker pull` never shows the page —+ links from the README badge, the User Guide's Docker page and the legacy repositories' overviews+ are what bring visitors. Never ask for stars in the app or in issue replies.+- The legacy repositories' overview and short description must say they mirror+ `triliumnext/trilium` and that users should switch image names.++## Related++- `docs/Developer Guide/Developer Guide/Building/Docker Hub maintenance.md` — the human-facing+ version of this page; keep the two in step.+- **cutting-a-release** — a release is what moves `stable`/`latest` and triggers the legacy mirror.diff --git a/.claude/skills/maintaining-docker-hub/hub.mjs b/.claude/skills/maintaining-docker-hub/hub.mjsnew file mode 100644index 0000000000..372db87b60--- /dev/null+++ b/.claude/skills/maintaining-docker-hub/hub.mjs@@ -0,0 +1,348 @@+#!/usr/bin/env node+// Docker Hub maintenance for Trilium's image repositories.+//+// stats <repo...> pulls, stars, storage, tags, weekly pull series+// tags <repo> [--prefix p] [--delete] list (or delete) tags matching a prefix+// inventory <repo> [--json file] every manifest in the repository, untagged included+// purge <repo> [--older-than days] [--delete] [--concurrency n]+// delete untagged image indexes (and with them,+// their per-platform images)+//+// Every destructive command is a dry run unless --delete is passed.+//+// Credentials come from `docker login` (~/.docker/config.json, or its credsStore helper), or from+// DOCKERHUB_USERNAME + DOCKERHUB_TOKEN. Deleting needs an account that owns the namespace.+//+// Examples:+// node hub.mjs stats triliumnext/trilium triliumnext/notes zadam/trilium+// node hub.mjs tags triliumnext/trilium --prefix sha-+// node hub.mjs inventory triliumnext/trilium+// node hub.mjs purge triliumnext/trilium --older-than 7+// node hub.mjs purge triliumnext/trilium --older-than 7 --delete++import { execFileSync } from "node:child_process";+import { readFileSync, writeFileSync } from "node:fs";+import { homedir } from "node:os";+import { join } from "node:path";++const HUB = "https://hub.docker.com";+const REGISTRY = "https://registry-1.docker.io";++let hubToken;+const registryTokens = {};++const [command, ...rest] = process.argv.slice(2);+const flags = {};+const positional = [];+for (let i = 0; i < rest.length; i++) {+ const arg = rest[i];+ if (!arg.startsWith("--")) {+ positional.push(arg);+ } else if (["--delete"].includes(arg)) {+ flags[arg.slice(2)] = true;+ } else {+ flags[arg.slice(2)] = rest[++i];+ }+}++const commands = { stats, tags, inventory, purge };+if (!commands[command]) {+ console.log(readFileSync(new URL(import.meta.url), "utf8").split("\n").slice(1, 24)+ .map((l) => l.replace(/^\/\/ ?/, "")).join("\n"));+ process.exit(command ? 1 : 0);+}+await commands[command]();++// --- Commands ---------------------------------------------------------------------------------++async function stats() {+ for (const repo of positional) {+ const info = await hubJson(`/v2/repositories/${repo}/`);+ const tagCount = (await hubJson(`/v2/repositories/${repo}/tags?page_size=1`)).count;+ console.log(`${repo} [${info.status_description}]`);+ console.log(` pulls ${info.pull_count.toLocaleString("en-US")} stars ${info.star_count}`+ + ` storage ${gb(info.storage_size)} tags ${tagCount}`+ + ` last push ${info.last_updated?.slice(0, 10)}`);+ console.log(` categories: ${info.categories.map((c) => c.name).join(", ") || "-"}`);+ const weeks = await weeklyPulls(repo);+ if (weeks.length) {+ console.log(" weekly pulls: " + weeks.map(([w, n]) => `${w} ${n}`).join(", "));+ } else {+ console.log(" weekly pulls: not published for this repository");+ }+ }+}++async function tags() {+ const repo = requireRepo();+ const prefix = flags.prefix ?? "";+ if (flags.delete && !prefix) fail("--delete needs --prefix, so it cannot delete every tag.");+ const names = (await listTags(repo, prefix)).filter((n) => n.startsWith(prefix));+ console.log(`${names.length} tag(s) on ${repo} starting with "${prefix}"`+ + (names.length === 1000 ? " (listing capped at 1000; run again after deleting)" : ""));+ if (!flags.delete) {+ console.log(names.slice(0, 30).join(" ") + (names.length > 30 ? " …" : ""));+ return;+ }+ const counts = await pool(names, async (name) => {+ const status = await hubDelete(`/v2/repositories/${repo}/tags/${encodeURIComponent(name)}/`);+ return status === 204 ? "deleted" : status === 404 ? "absent" : `error ${status}`;+ }, "tags");+ console.log("done:", counts);+}++async function inventory() {+ const repo = requireRepo();+ const manifests = await listManifests(repo);+ const isIndex = (m) => /index|manifest\.list/.test(m.media_type);+ const groups = {+ "tagged indexes": manifests.filter((m) => isIndex(m) && m.tags.length),+ "untagged indexes": manifests.filter((m) => isIndex(m) && !m.tags.length),+ "untagged single manifests": manifests.filter((m) => !isIndex(m) && !m.tags.length),+ "tagged single manifests": manifests.filter((m) => !isIndex(m) && m.tags.length),+ };+ console.log(`${repo}: ${manifests.length} manifests`);+ for (const [label, list] of Object.entries(groups)) {+ if (!list.length) continue;+ const pushed = list.map((m) => m.last_pushed?.slice(0, 10)).sort();+ console.log(` ${label.padEnd(26)} ${String(list.length).padStart(6)}`+ + ` ${gb(sum(list, "total_size")).padStart(9)} nominal`+ + ` pushed ${pushed[0]} → ${pushed.at(-1)}`);+ }+ console.log(" (nominal sizes count shared layers once per manifest; the per-platform images"+ + " of a tagged index are listed as untagged single manifests)");+ if (flags.json) {+ writeFileSync(flags.json, JSON.stringify(manifests));+ console.log(`wrote ${flags.json}`);+ }+}++async function purge() {+ const repo = requireRepo();+ const olderThan = Number(flags["older-than"] ?? 0);+ const cutoff = Date.now() - olderThan * 86_400_000;++ const keep = await keepList(repo);+ const manifests = await listManifests(repo);+ const candidates = manifests.filter((m) => /index|manifest\.list/.test(m.media_type)+ && !m.tags.length+ && !keep.has(m.manifest_digest)+ && Date.parse(m.last_pushed) < cutoff);+ console.log(`keep: ${keep.size} digests from the live tags`);+ console.log(`to delete: ${candidates.length} untagged image indexes`+ + (olderThan ? ` pushed more than ${olderThan} day(s) ago` : "")+ + `, ${gb(sum(candidates, "total_size"))} nominal`);+ if (!flags.delete || !candidates.length) return;++ const counts = await pool(candidates.map((m) => m.manifest_digest), async (digest) => {+ const status = await registryDelete(repo, digest);+ return { 202: "deleted", 404: "absent", 403: "referenced" }[status] ?? `error ${status}`;+ }, "indexes");+ console.log("done:", counts);+}++// --- Docker Hub API ---------------------------------------------------------------------------++function credentials() {+ if (process.env.DOCKERHUB_USERNAME && process.env.DOCKERHUB_TOKEN) {+ return { username: process.env.DOCKERHUB_USERNAME, secret: process.env.DOCKERHUB_TOKEN };+ }+ const config = JSON.parse(readFileSync(join(homedir(), ".docker", "config.json"), "utf8"));+ const auth = config.auths?.["https://index.docker.io/v1/"]?.auth;+ if (auth) {+ const [username, ...secret] = Buffer.from(auth, "base64").toString().split(":");+ return { username, secret: secret.join(":") };+ }+ if (config.credsStore) {+ const out = execFileSync(`docker-credential-${config.credsStore}`, ["get"],+ { input: "https://index.docker.io/v1/" }).toString();+ const { Username, Secret } = JSON.parse(out);+ return { username: Username, secret: Secret };+ }+ fail("No Docker Hub credentials: run `docker login` or set DOCKERHUB_USERNAME/DOCKERHUB_TOKEN.");+}++async function hubLogin() {+ const { username, secret } = credentials();+ const res = await request(`${HUB}/v2/auth/token`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({ identifier: username, secret }),+ });+ if (res.status !== 200) fail(`Docker Hub login failed: ${res.status}`);+ hubToken = (await res.json()).access_token;+}++async function registryToken(repo, refresh = false) {+ if (!registryTokens[repo] || refresh) {+ const { username, secret } = credentials();+ const basic = Buffer.from(`${username}:${secret}`).toString("base64");+ const res = await request("https://auth.docker.io/token?service=registry.docker.io"+ + `&scope=repository:${repo}:pull,push,delete`, { headers: { Authorization: `Basic ${basic}` } });+ registryTokens[repo] = (await res.json()).token;+ }+ return registryTokens[repo];+}++/** Calls the Docker Hub API with a bearer token, renewing it on 401. */+async function hub(path, options = {}) {+ if (!hubToken) await hubLogin();+ for (let attempt = 0; attempt < 3; attempt++) {+ const res = await request(HUB + path, {+ ...options,+ headers: { ...options.headers, Authorization: `Bearer ${hubToken}` },+ });+ if (res.status !== 401) return res;+ await hubLogin();+ }+ fail(`Docker Hub keeps answering 401 for ${path}`);+}++async function hubJson(path) {+ const res = await hub(path);+ if (!res.ok) fail(`GET ${path}: ${res.status}`);+ return res.json();+}++async function hubDelete(path) {+ return (await hub(path, { method: "DELETE" })).status;+}++async function registryDelete(repo, digest) {+ for (let attempt = 0; attempt < 3; attempt++) {+ const res = await request(`${REGISTRY}/v2/${repo}/manifests/${digest}`, {+ method: "DELETE",+ headers: { Authorization: `Bearer ${await registryToken(repo, attempt > 0)}` },+ });+ if (res.status !== 401) return res.status;+ }+ return 401;+}++async function registryManifest(repo, reference) {+ const res = await request(`${REGISTRY}/v2/${repo}/manifests/${reference}`, {+ headers: {+ Authorization: `Bearer ${await registryToken(repo)}`,+ Accept: [+ "application/vnd.oci.image.index.v1+json",+ "application/vnd.docker.distribution.manifest.list.v2+json",+ "application/vnd.oci.image.manifest.v1+json",+ "application/vnd.docker.distribution.manifest.v2+json",+ ].join(", "),+ },+ });+ if (!res.ok) return null;+ const body = await res.json();+ return {+ digest: res.headers.get("docker-content-digest"),+ children: (body.manifests ?? []).map((m) => m.digest),+ };+}++/** Tags, newest first. The Hub API stops after 10 pages, so at most 1000 come back. */+async function listTags(repo, prefix = "") {+ const names = [];+ let path = `/v2/repositories/${repo}/tags?page_size=100` + (prefix ? `&name=${encodeURIComponent(prefix)}` : "");+ while (path) {+ const page = await hubJson(path);+ if (!page.results?.length) break;+ names.push(...page.results.map((t) => t.name));+ path = page.next ? page.next.replace(HUB, "") : null;+ }+ return names;+}++/** Every manifest in the repository, untagged ones included, from the Hub manifest inventory. */+async function listManifests(repo) {+ const [namespace, name] = repo.split("/");+ const manifests = [];+ let key;+ do {+ const page = await hubJson(`/v2/namespaces/${namespace}/repositories/${name}/manifests?page_size=100`+ + (key ? `&last_evaluated_key=${encodeURIComponent(key)}` : ""));+ manifests.push(...page.manifests);+ key = page.manifests.length && page.last_evaluated_key !== key ? page.last_evaluated_key : null;+ } while (key);+ return manifests;+}++/** Digests a live tag still needs: each tag's index and every manifest inside it. */+async function keepList(repo) {+ const keep = new Set();+ const live = await listTags(repo);+ if (live.length >= 1000) fail("More than 1000 tags: delete unwanted tags first, so the keep list is complete.");+ for (const tag of live) {+ const manifest = await registryManifest(repo, tag);+ if (!manifest) fail(`Cannot resolve ${repo}:${tag}; refusing to build an incomplete keep list.`);+ keep.add(manifest.digest);+ for (const child of manifest.children) keep.add(child);+ }+ return keep;+}++async function weeklyPulls(repo) {+ const res = await request(`${HUB}/r/${repo}`);+ const html = await res.text();+ const series = html.slice(html.indexOf("repoPullsData"));+ return [...series.matchAll(/(\d{4}-\d{2}-\d{2})T00:00:00Z\\",\\"(?:end\\",\\")?\d{4}-\d{2}-\d{2}T00:00:00Z\\",(?:\\"pullCount\\",)?(\d+)/g)]+ .map((m) => [m[1], Number(m[2])]);+}++// --- Helpers ----------------------------------------------------------------------------------++/** fetch() with backoff on 429, 5xx and network errors. */+async function request(url, options = {}) {+ for (let attempt = 1; ; attempt++) {+ try {+ const res = await fetch(url, { ...options, headers: { "User-Agent": "trilium-hub-maintenance", ...options.headers } });+ if ((res.status !== 429 && res.status < 500) || attempt >= 8) return res;+ } catch (e) {+ if (attempt >= 8) throw e;+ }+ await new Promise((resolve) => setTimeout(resolve, 5000 * attempt));+ }+}++/** Runs `task` over `items` with a few requests in flight; stops after 10 errors. */+async function pool(items, task, label) {+ const concurrency = Number(flags.concurrency ?? 4);+ const counts = {};+ let next = 0;+ let done = 0;+ let errors = 0;+ const worker = async () => {+ while (next < items.length && errors <= 10) {+ const item = items[next++];+ const outcome = await task(item);+ counts[outcome] = (counts[outcome] ?? 0) + 1;+ if (outcome.startsWith("error")) {+ errors++;+ console.log(`ERROR ${item}: ${outcome}`);+ }+ if (++done % 200 === 0) {+ console.log(`${new Date().toTimeString().slice(0, 8)} ${label}: ${done}/${items.length}`, counts);+ }+ }+ };+ await Promise.all(Array.from({ length: concurrency }, worker));+ if (errors > 10) fail(`Stopped after ${errors} errors: ${JSON.stringify(counts)}`);+ return counts;+}++function requireRepo() {+ if (!positional[0]?.includes("/")) fail("Pass the repository as <namespace>/<name>.");+ return positional[0];+}++function sum(list, field) {+ return list.reduce((total, item) => total + (item[field] ?? 0), 0);+}++function gb(bytes) {+ return `${(bytes / 1e9).toFixed(1)} GB`;+}++function fail(message) {+ console.error(message);+ process.exit(1);+}diff --git a/docs/Developer Guide/!!!meta.json b/docs/Developer Guide/!!!meta.jsonindex 1b3a7e715f..b607bd0972 100644--- a/docs/Developer Guide/!!!meta.json+++ b/docs/Developer Guide/!!!meta.json@@ -967,6 +967,40 @@"dataFileName": "Docker.md","attachments": []},+ {+ "isClone": false,+ "noteId": "713MoR6LVq8o",+ "notePath": [+ "jdjRLhLV3TtI",+ "a0mkxxB4Uvbf",+ "713MoR6LVq8o"+ ],+ "title": "Docker Hub maintenance",+ "notePosition": 30,+ "prefix": null,+ "isExpanded": false,+ "type": "text",+ "mime": "text/html",+ "attributes": [+ {+ "type": "label",+ "name": "shareAlias",+ "value": "docker-hub",+ "isInheritable": false,+ "position": 10+ },+ {+ "type": "label",+ "name": "iconClass",+ "value": "bx bx-brush",+ "isInheritable": false,+ "position": 20+ }+ ],+ "format": "markdown",+ "dataFileName": "Docker Hub maintenance.md",+ "attachments": []+ },{"isClone": false,"noteId": "aGlhNBEA9wwo",@@ -976,7 +1010,7 @@"aGlhNBEA9wwo"],"title": "Build information",- "notePosition": 30,+ "notePosition": 40,"prefix": null,"isExpanded": false,"type": "text",@@ -1010,7 +1044,7 @@"fI16A7NrT713"],"title": "Live reload (HMR)",- "notePosition": 40,+ "notePosition": 50,"prefix": null,"isExpanded": false,"type": "text",@@ -1037,7 +1071,7 @@"PXzm2t3sCdsP"],"title": "Build deliveries locally",- "notePosition": 50,+ "notePosition": 60,"prefix": null,"isExpanded": false,"type": "text",@@ -1071,7 +1105,7 @@"4nwtTJyjNDKd"],"title": "Releasing a new version",- "notePosition": 70,+ "notePosition": 80,"prefix": null,"isExpanded": false,"type": "text",diff --git a/docs/Developer Guide/Developer Guide/Building/Docker Hub maintenance.md b/docs/Developer Guide/Developer Guide/Building/Docker Hub maintenance.mdnew file mode 100644index 0000000000..3a58222313--- /dev/null+++ b/docs/Developer Guide/Developer Guide/Building/Docker Hub maintenance.md@@ -0,0 +1,76 @@+# Docker Hub maintenance+Trilium's server image is built by `.github/workflows/main-docker.yml` and published to two registries: GHCR (`ghcr.io/triliumnext/trilium`) and Docker Hub (`triliumnext/trilium`). This page describes which tags go where, how the legacy repositories are kept up to date, and how to clean up a repository that has accumulated images nobody uses.++## Where tags are published++| Tag | GHCR | Docker Hub | Created by |+| --- | --- | --- | --- |+| `main` | yes | yes | every push to `main` that touches the app |+| `sha-<commit>` | yes | **no** | every build |+| `v<version>` | yes | yes | a version tag |+| `stable`, `latest` | yes | yes | a version tag without a hyphen (not a prerelease) |+| `<branch-name>` | yes | yes | a manual run of the workflow on a branch |++The `sha-*` tags stay on GHCR only. Before October 2026 they were copied to Docker Hub as well, where nothing ever removed them: by October 2026, 1,672 of the 1,698 tags in `triliumnext/trilium` were `sha-*`, and the repository reported 974 GB of storage.++A manual run of the workflow on a branch also publishes a tag named after the branch, with `/` replaced by `-` (for example `feature-deployment_fixes`). Delete it on Docker Hub once the branch is merged.++Each push to `main` moves the `main` tag and leaves the previous image on Docker Hub without a tag, about a dozen a day. Until `main` is kept on GHCR only, clean them up from time to time as described below.++## Legacy repositories++Two older Docker Hub repositories still receive many pulls from installations that update automatically:++| Repository | History | Pulls per week (Sep 2026) |+| --- | --- | --- |+| `triliumnext/notes` | TriliumNext's image before the rename, last own build v0.95.0 | ~29,600 |+| `zadam/trilium` | the original Trilium image, last own build 0.63.7 | ~24,000 |++`.github/workflows/mirror-legacy-docker.yml` copies `ghcr.io/triliumnext/trilium:stable` to `triliumnext/notes:stable`, `triliumnext/notes:latest` and `zadam/trilium:latest` after every stable release; `main-docker.yml` calls it from its `mirror_legacy` job. The version tags and `0.63-latest` on `zadam/trilium` are left unchanged, so installations that pin a version keep it. To run the mirror by hand, start the workflow from the _Actions_ tab; an empty _tags_ field writes each repository's release tags.++Each repository has its own credentials:++* `triliumnext/notes` uses the `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` secrets, like the main image.+* `zadam/trilium` logs in as `zadam` with the `ZADAM_DOCKERHUB_TOKEN` secret, a Read & Write access token of that account. A personal access token cannot be limited to one repository, so give it an expiry date.++Pull statistics are on each repository's page on Docker Hub; `hub.mjs stats` (below) prints them, including the weekly series Docker Hub publishes for repositories owned by an organization.++## How Docker Hub stores images++Four facts decide how a cleanup works:++* **Deleting a tag does not delete the image.** The image stays in the repository, can still be pulled by digest and still counts towards the repository's storage. Only deleting the untagged image frees space.+* **Deleting an image index also deletes the images inside it.** A multi-platform image is an index that points to one manifest per platform plus its attestations (eight for Trilium). Once the index is gone, those manifests return `404` as well, so a cleanup deletes indexes only.+* **Docker Hub refuses to delete a manifest that a tag still uses.** A `DELETE` of such a digest returns `403`, so a cleanup cannot break a tag that is kept, even when a deleted image shares its digest with a release (a `sha-*` build of a release commit is the same image as `v<version>`).+* **`GET /v2/namespaces/<namespace>/repositories/<name>/manifests` lists every manifest in a repository, untagged ones included.** It is not in Docker's public API reference. It reports the per-platform images of a tagged index as untagged, so an untagged single manifest is not necessarily an orphan.++> [!WARNING]+> Never bulk-delete the untagged _Image_ entries in Docker Hub's _Image Management_ page. The per-platform images of every kept tag appear there as untagged, and deleting them breaks `docker pull` of those tags. Delete image indexes only.++## Cleaning up a repository++The `maintaining-docker-hub` skill in `.claude/skills` provides `hub.mjs`, which does the whole cleanup. Every command that deletes is a dry run unless `--delete` is passed.++```sh+H=.claude/skills/maintaining-docker-hub/hub.mjs+node $H stats triliumnext/trilium # pulls, stars, storage, tag count+node $H tags triliumnext/trilium --prefix sha- # list tags; --delete deletes them+node $H inventory triliumnext/trilium # tagged and untagged manifests+node $H purge triliumnext/trilium --older-than 7 # untagged indexes; --delete deletes them+```++It reads the credentials of `docker login` (or `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`). Deleting needs an account that owns the namespace.++To clean up a repository:++1. Delete the unwanted tags with `tags <repo> --prefix <prefix> --delete`. Docker Hub lists at most 1,000 tags at a time and its tag count lags behind deletions by several minutes, so run it again until it finds none.+2. Delete the untagged indexes with `purge <repo> --delete`. `purge` keeps the index and the per-platform images of every remaining tag, and refuses to run while the repository has more than 1,000 tags, since its list of tags to keep would be incomplete.+3. Check the kept tags with `docker manifest inspect <repo>:<tag>` for `latest`, `stable`, `main` and a few versions, and the storage figure with `stats`.++The storage figure follows within minutes. In October 2026 this took `triliumnext/trilium` from 974 GB to 18 GB and `triliumnext/notes` from 658 GB to 19 GB, about 17,000 untagged indexes in all, at 60 to 250 deletions per minute.++## See also++* <a class="reference-link" href="Docker.md">Docker</a>, for building the image locally.+* [docker/hub-feedback#2448](https://github.com/docker/hub-feedback/issues/2448), where Docker announced support for deleting manifests through the registry API.+* [Registry API reference](https://docs.docker.com/reference/api/registry/latest/) on docs.docker.com.\ No newline at end of filediff --git a/docs/Developer Guide/Developer Guide/Building/Docker.md b/docs/Developer Guide/Developer Guide/Building/Docker.mdindex d671f605cd..31d3968ac0 100644--- a/docs/Developer Guide/Developer Guide/Building/Docker.md+++ b/docs/Developer Guide/Developer Guide/Building/Docker.md@@ -7,4 +7,6 @@ To build the server for Docker:* To not only build but also run the Docker container, simply replace `docker-build` with `docker-start` (e.g. `pnpm docker-start-debian`).* To check that an image also runs as a non-root user, as CI does, run `sh scripts/check-docker-non-root.sh triliumnext-debian` (or `triliumnext-alpine`).-Build the images on Linux or in WSL. The build keeps only the host's prebuilt `better-sqlite3` binary, so an image built from a `dist` made on Windows fails at startup with `Cannot find module …/better_sqlite3.node`.\ No newline at end of file+Build the images on Linux or in WSL. The build keeps only the host's prebuilt `better-sqlite3` binary, so an image built from a `dist` made on Windows fails at startup with `Cannot find module …/better_sqlite3.node`.++For the registries the image is published to, the legacy repositories and cleaning up old images, see <a class="reference-link" href="Docker%20Hub%20maintenance.md">Docker Hub maintenance</a>.\ No newline at end of file