docs(docker): publish a Docker Hub Overview, and a step to keep it current

[LeeroyHannigan]

What this does

Publishes a Docker Hub Overview for extenddb/extenddb-postgres, and adds a step that keeps it in sync with the repository.

The Hub page currently has 446 pulls and a blank Overview, plus a blank short description. A bare page reads as an abandoned image.

Why it is blank, and why a push will never fix it

Neither docker push nor the skopeo copy that promote-image uses touches repository metadata. The Overview is full_description on the Docker Hub repository object, not on any image or manifest, and nothing in CI calls the Hub API.

The asymmetry worth knowing: GHCR looks documented for the same image because it derives its package description from the OCI labels the Dockerfile already sets at lines 47-48 (org.opencontainers.image.title and .description). Docker Hub ignores those labels for the Overview entirely. Same artifact, maintained on one registry and blank on the other.

Why a new file rather than pointing at docker/README.md

docker/README.md is contributor-facing: generate notices, docker build with build args, the four-role Compose stack, run the smoke test. Someone pulling the image needs a different set of facts:

• the tag policy (X.Y.Z immutable, latest only moves forward, sha-<commit> are unpromoted candidates)
• that PostgreSQL is not bundled and 14+ must be supplied
• the runtime contract: port, state volume, non-root UID, tini, and that the healthcheck is liveness only
• how to verify the signature

So this adds docker/dockerhub-overview.md and leaves the existing doc for contributors.

It also carries the trademark notice from the README verbatim. The Hub page is a public front door and previously carried no notice at all, which matters more there than in a directory README. And it links to extenddb.org.

Design of the sync step

Sourced from a file in the repo, so the published Overview is reviewed like any other content and cannot drift.

Dispatch-only, gated on the dockerhub environment. It uses the same credential that can push images, so it gets the same gate.

Deliberately not wired into promote-image. The Overview is version-neutral: a wording fix should not require a release, and a release should not silently rewrite the page. It also keeps this clear of #283, which is already changing that workflow.

It verifies rather than assumes. After the PATCH it re-reads the repository anonymously and diffs the published Overview against the file, so a silent no-op or a partial write fails the run instead of reporting green. That matters because the Hub API path cannot be exercised from a PR: the credential only exists inside the gated job. The first dispatch proves it end to end.

Testing done

• Workflow YAML parses; the jq payload construction was exercised locally with no credentials involved.
• Size limits are asserted in the job and were checked here: the Overview is 4,945 characters against Docker Hub's 25,000 cap, and the short description is 73 against its 100 cap.
• Every link was fetched and returns 200: extenddb.org, the repository, the releases page, and the four linked docs. A broken link on the front page would be worse than a blank one.
• Runtime facts were read out of the Dockerfile rather than restated from memory: EXPOSE 18443, state at /var/lib/extenddb, USER 10001:10001, tini entrypoint, and the healthcheck being liveness rather than backend readiness.
• Signature guidance points at the releases page rather than hardcoding a cosign invocation, because v0.1.6 needs --insecure-ignore-tlog=true and releases after ci(release): sign and propagate in the publish stage #284 will not. Each release's notes already carry the right command and attach extenddb-signing.pub.pem.

Follow-ups, not in scope

• extenddb/extenddb-dev now exists on Docker Hub (created with the 0.1.7 release), so both Overviews are publishable; the workflow is parameterised by HUB_REPO so it is a copy of the job rather than new machinery.
• Once ci(promote): fan out promotion to GHCR and ECR in one approved run #283 lands, folding this into the promote flow becomes an option, though the version-neutral argument above suggests leaving it separate.

Checklist

• I have read CONTRIBUTING.md
• All tests pass — no code changed
• Code is formatted — n/a
• Clippy is clean — n/a
• I have added or updated tests for new functionality — the job asserts size caps and diffs the published result against the file
• I have updated documentation if behavior changed
• Breaking changes are noted below (if any)

ADR / RFC: n/a — no change to the wire protocol, Storage trait, auth model, on-disk format, or public CLI surface.

Breaking changes

None. No image, tag, or digest is affected.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache License 2.0 and I agree to the Developer Certificate of Origin (DCO). See CONTRIBUTING.md for details.

[robinnsc]

Reviewed all three files and reproduced the one thing I think blocks. The design reasoning is exactly right — the GHCR-vs-Hub metadata asymmetry explanation is the kind of context that saves the next person an hour, sourcing the Overview from a reviewed file is the correct trust model, the anonymous read-back is the right verification philosophy, and the local case validation matches the convention the other workflows just converged on. Content checks out too: dev overview's port 18080 and :memory: env var match the merged #281 behavior, and the tag-policy section matches what promote-registry actually enforces as of today.

Blocking, reproduced locally: the verify step false-fails on every successful publish. GOT_FULL=$(jq -r ...) strips the trailing newline via command substitution, while cat "$FILE" keeps it (both .md files end with newlines), so diff reports a difference every time — the gate can never pass, and the first dispatch will report failure after publishing correctly, which reads as a broken publish rather than a broken check. One-line fix — compare stripped-to-stripped:

if [[ "$GOT_FULL"!="$(cat "$FILE")" ]];then

(both substitutions strip trailing newlines, so the comparison is apples-to-apples; same result could be had with printf '%s\n' on the left of the diff.)

Should-fix: all four pre-publish gates (file exists, size caps, link check, repo-exists) are credential-free but live inside the environment-gated job — so a dead link or a 404 burns a reviewer approval to discover, the same shape you flagged on the sign-image dev option. Splitting them into an ungated validate job (contents: read, no secrets) with publish: needs: validate means validation runs on dispatch, and the reviewer approves knowing the content already passed.

Nits:

• The link checker has no retry, so a transient network blip fails the run (and post-split, at zero cost; pre-split, it burns an approval): curl --retry 2 covers it.
• The PR body's "extenddb/extenddb-dev does not exist yet (404)" is stale — you created it last night; the repo-exists gate makes this self-resolving, just worth a body edit so the record reads right.

Happy to re-check after the comparison fix — with it, this closes the last blank-front-door problem the images have.

[LeeroyHannigan]

All four addressed in f6e9928:

• Blocker: reproduced your repro first (old comparison fails on the real overview file, stripped-to-stripped passes), then applied your fix. Good catch - the gate could never have passed.
• Should-fix: split into an ungated validate job (no secrets, no environment) with publish: needs: validate carrying the dockerhub gate. Reviewer now approves content that already passed.
• Nits:--retry 2 --retry-delay 3 on the link checker and the repo-exists probe; PR body's stale 404 claim corrected.

Thanks for actually running it - that comparison bug would have made the first real dispatch look like a broken publish.