[codex] Publish registry-backed server images

[den-sq]

Summary

• add a Publish Server Image workflow that builds the Python wheel and publishes python/Dockerfile-prod to GHCR
• tag server images by release tag and commit SHA
• document how release compose files should consume immutable registry image tags while keeping the wheel/Dockerfile path as fallback

Closes #85

Validation

• poetry install in python/
• poetry build in python/
• docker build -f python/Dockerfile-prod -t ouroboros-server:pr86-build python
• docker run --rm ouroboros-server:pr86-build python -c "import ouroboros; print('ouroboros import ok')"
• GitHub Actions PR checks passed:
  • coverage
  • docs
  • server-image
  • test-coverage

Manual GHCR Publish

• Manually dispatched Publish Server Image on codex/registry-server-images
• Run: https://github.com/ChengLabResearch/ouroboros/actions/runs/28260409147
• Result: success
• Source commit: ab3eb073974e8431be68b48b53933298f8f2807c
• Published image: ghcr.io/chenglabresearch/ouroboros-server:sha-ab3eb07
• Published digest: sha256:f90b106eb798508386c249b24164f982e37a1f1328986e801294faa6bfc46031
• GitHub Packages API confirms the package exists with tag sha-ab3eb07
• Current GHCR package visibility: public
• Anonymous registry manifest inspection succeeds for ghcr.io/chenglabresearch/ouroboros-server:sha-ab3eb07

[den-sq]

Updated this branch from current main, resolved the docs nav conflict, and added PR build-only validation for the server image workflow.

Validation:

• Local: poetry install in python/
• Local: poetry build in python/
• Local: docker build -f python/Dockerfile-prod -t ouroboros-server:pr86-build python
• Local: docker run --rm ouroboros-server:pr86-build python -c "import ouroboros; print('ouroboros import ok')"
• GitHub Actions: server-image passed with push: false on PR

No GHCR publish was attempted; tag/manual-dispatch pushes are still deferred.

[tavateva]

Review ✅ READY

Reviewed against draft promotion criteria. This PR is ready for merge.

Context: This PR addresses issue #85 (Publish registry-backed Ouroboros server images).

Criterion Assessment

1. CI and mergeability: ✅ PASS — Mergeable, server image workflow passed in GH Actions
2. Issue Acceptance Criteria: ✅ PASS — All 5 components of Publish registry-backed Ouroboros server images #85 addressed:
   • ✅ Publish Python server image to GHCR
   • ✅ Tag images by commit SHA and release tag
   • ✅ Keep existing wheel-based Dockerfile as fallback (unchanged)
   • ✅ Document release compose usage (new registry-server-images.md doc)
   • ✅ Development compose continues building locally (unchanged)
3. PR body Test Plan checkboxes: ✅ PASS — Validation executed, deferred items documented
4. Tests run: ✅ PASS — Comprehensive validation including:
   • ✅ Local: Poetry install/build in python/
   • ✅ Local: Docker build (python/Dockerfile-prod)
   • ✅ Local: Import smoke test (docker run ... python -c "import ouroboros; ...")
   • ✅ GH Actions: server-image workflow passed (push: false on PR)
5. Scope: ✅ PASS — Matches issue scope exactly
6. Regressions: ✅ PASS — No regression risk (PR-mode runs build-only; existing workflow unchanged)
7. Judgement calls: ✅ PASS — Deferred GHCR publish appropriate (tag/manual-dispatch only per workflow design)

VERDICT: ✅ READY TO MERGE

Validation Summary

Comprehensive validation with smoke testing:

• ✅ Local: Poetry install and build
• ✅ Local: Docker image build
• ✅ Local: Import smoke test confirms package loads
• ✅ GH Actions: server-image workflow build-only validation passed

Deferred (per workflow design):

• ⏳ GHCR publish — tag/manual-dispatch only, not on PRs

Image Tag Strategy

Well-designed immutable tag strategy:

• Release tags: ghcr.io/chenglabresearch/ouroboros-server:<release-tag> (e.g., v1.4.0)
• Commit SHAs: ghcr.io/chenglabresearch/ouroboros-server:sha-<commit>
• Workflow publishes only on tag push or manual dispatch, not on PRs

Documentation

New documentation file docs/development/registry-server-images.md provides:

• ✅ Published image tag examples
• ✅ Release compose usage guidance
• ✅ Fallback strategy (bundled wheel + Dockerfile-prod)
• ✅ Manual workflow dispatch notes

All 7 criteria satisfied. This PR closes issue #85 and is ready to merge.

---

Note: Sorotassu mentioned intentionally avoiding final GCHR publish. This PR is structured correctly for that — the workflow only publishes on tag push or manual dispatch, not on merge to main.

[den-sq]

Manual GHCR publish completed successfully.

• Workflow: Publish Server Image
• Run: https://github.com/ChengLabResearch/ouroboros/actions/runs/28260409147
• Source commit: ab3eb073974e8431be68b48b53933298f8f2807c
• Published image: ghcr.io/chenglabresearch/ouroboros-server:sha-ab3eb07
• Digest: sha256:f90b106eb798508386c249b24164f982e37a1f1328986e801294faa6bfc46031

One follow-up visibility note: anonymous docker buildx imagetools inspect ghcr.io/chenglabresearch/ouroboros-server:sha-ab3eb07 currently returns 401 Unauthorized, and my local gh token lacks read:packages for package-version API verification. The Actions log confirms the GHCR push succeeded, but package visibility/access should be checked if unauthenticated pulls are expected.

[den-sq]

Rechecked GHCR after adding read:packages to the local gh token.

• Package exists: ChengLabResearch/ouroboros-server
• Package URL: https://github.com/orgs/ChengLabResearch/packages/container/package/ouroboros-server
• API visibility: private
• Version/tag present: sha-ab3eb07
• Version digest: sha256:f90b106eb798508386c249b24164f982e37a1f1328986e801294faa6bfc46031
• Anonymous manifest inspect still returns 401 Unauthorized

So the manual publish is available to authenticated package readers, but it is not currently public/unauthenticated-pullable.

[den-sq]

GHCR public visibility verified after the organization/package visibility changes.

• ghcr.io/chenglabresearch/ouroboros-server:sha-ab3eb07 is public and anonymously inspectable
• ghcr.io/chenglabresearch/ouroboros-autoseg-backend:sha-f707038 is public and anonymously inspectable
• ghcr.io/chenglabresearch/ouroboros-autoseg-backend:sha-f707038-cuda is public and anonymously inspectable

[tavateva]

✅ GHCR Publish Confirmed

Server image successfully built, pushed, and is publicly accessible:

Server Image

• Tag: ghcr.io/chenglabresearch/ouroboros-server:sha-ab3eb07
• SHA256: f90b106eb798508386c249b24164f982e37a1f1328986e801294faa6bfc46031
• Built: 2026-06-26T19:29:28Z
• ✅ Successfully pushed (workflow logs confirm manifest push complete)
• ✅ Publicly accessible (pull started successfully)

Workflow Execution

• Run ID: 28260409147
• Event: workflow_dispatch
• Status: ✅ Success
• Timestamp: 2026-06-26T19:25:53Z

The server image is now available at GHCR under chenglabresearch/ouroboros-server with public visibility.

Build Process Verified

From workflow logs:

• ✅ Poetry installed Python dependencies
• ✅ Poetry built wheel
• ✅ Docker build completed from python/Dockerfile-prod
• ✅ Image pushed to GHCR with proper labels and metadata
• ✅ Manifest push confirmed at 2026-06-26T19:29:28Z

---

Ready to merge — all validation complete, image published and verified.