Skip to content

docs: document Docker image tags and run (#10) - #81

Merged
eSlider merged 1 commit into
mainfrom
docs/docker-tags-10
Nov 11, 2026
Merged

eSlider merged 1 commit into
mainfrom
docs/docker-tags-10

Conversation

@eSlider

@eSlider eSlider commented Nov 11, 2026

Copy link
Copy Markdown
Owner

Closes Gitea https://git.pro-dukt.de/eslider/2dph/issues/10 (epic #12, phase Ф2 — docs).

What

  • README — new compact ### Run with Docker block under Quick start: pull, a
    verified docker run, /health, MCP URL, one-line tag legend, link to the
    runbook anchor. No rewrite of the existing showcase text.
  • docs/runbook.md — new ## Docker images and tags section (after Toolchain):
    • tag table vX.Y.Z / latest / api / sha-<12> and which to use
      (prod pins vX.Y.Z; api for tests only), upgrade/rollback flow;
    • working docker run plus why KB_HOST=0.0.0.0 and --user "$(id -u):$(id -g)"
      are required;
    • version of an image: OCI label org.opencontainers.image.version /
      docker buildx imagetools inspect, revision/source/created;
    • how releases are cut: manual workflow_dispatch, push to main → api +
      sha-<12> only, backfill re-points an existing digest (feat: bin/brain/serve.go; search backend is Go not Python #9).

Verified against the real image

ghcr.io/eslider/2dph:api (linux/amd64, pulled 2026-11-11):

  • the documented docker run comes up healthy; /health → {"status":"ok"},
    /openapi.json → 200, POST /mcp tools/list → search/get/… tools;
  • without KB_HOST=0.0.0.0 the published port resets (serve binds 127.0.0.1);
  • without --user the container exits OpenDatabase: failed to open database
    (image uid 1001 vs host-owned var/);
  • docker run --rm <image> version → unknown command: version, so the docs use
    the OCI label only (no invented verb);
  • docker image inspect … org.opencontainers.image.version is null on today's
    api — labels arrive with feat: bin/brain/serve.go; search backend is Go not Python #9. GHCR currently has api + 46 sha-*, no
    latest/v* yet; the runbook says so explicitly.

Not touched

.github/, bin/, Go code (issue #9 owner). Only README.md and
docs/runbook.md changed. No internal hosts/PII added; all relative links resolve.

Review checklist

@eSlider
eSlider merged commit ace26cf into main Nov 11, 2026
6 checks passed
@eSlider
eSlider deleted the docs/docker-tags-10 branch November 11, 2026 16:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant