From 93d94c9af5a2087634315cbee300f66c8b1661e7 Mon Sep 17 00:00:00 2001
From: David Northover <david.northover@psu.edu>
Date: Tue, 23 Jun 2026 01:00:56 -0400
Subject: [PATCH 1/2] ci(docker): publish server images to GHCR

---
 .github/workflows/server-image.yml            | 67 +++++++++++++++++++
 .../development/registry-server-images.md     | 28 ++++++++
 documentation/mkdocs.yml                      |  1 +
 3 files changed, 96 insertions(+)
 create mode 100644 .github/workflows/server-image.yml
 create mode 100644 documentation/docs/development/registry-server-images.md

diff --git a/.github/workflows/server-image.yml b/.github/workflows/server-image.yml
new file mode 100644
index 0000000..284d2b3
--- /dev/null
+++ b/.github/workflows/server-image.yml
@@ -0,0 +1,67 @@
+name: Publish Server Image
+
+on:
+  push:
+    tags:
+      - v*.*.*
+  workflow_dispatch:
+
+env:
+  REGISTRY_IMAGE: ghcr.io/chenglabresearch/ouroboros-server
+
+jobs:
+  server-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@v4
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Poetry
+        uses: abatilo/actions-poetry@v2
+        with:
+          poetry-version: '2.1.3'
+
+      - name: Install Python Dependencies
+        working-directory: ./python
+        run: poetry install
+
+      - name: Build Wheel
+        working-directory: ./python
+        run: poetry build
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker Metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY_IMAGE }}
+          tags: |
+            type=ref,event=tag
+            type=sha,prefix=sha-
+
+      - name: Build and Push Server Image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./python
+          file: ./python/Dockerfile-prod
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
diff --git a/documentation/docs/development/registry-server-images.md b/documentation/docs/development/registry-server-images.md
new file mode 100644
index 0000000..15510bd
--- /dev/null
+++ b/documentation/docs/development/registry-server-images.md
@@ -0,0 +1,28 @@
+# Registry Server Images
+
+Ouroboros can publish the Python server Docker image to GHCR during release-tag workflows. This avoids turning every production startup into a local image build once release packaging is ready to reference immutable image tags.
+
+## Published Image
+
+The `Publish Server Image` workflow builds the Python wheel, builds `python/Dockerfile-prod`, and publishes:
+
+- `ghcr.io/chenglabresearch/ouroboros-server:<release-tag>` for release tags such as `v1.4.0`
+- `ghcr.io/chenglabresearch/ouroboros-server:sha-<commit>` for the exact source revision
+
+Both tags are produced from the same wheel artifact that the Dockerfile installs.
+
+## Release Compose Usage
+
+Release packaging should prefer an immutable image tag when the corresponding image exists:
+
+```yaml
+services:
+  ouroboros-server:
+    image: ghcr.io/chenglabresearch/ouroboros-server:v1.4.0
+```
+
+Keep the bundled wheel and `Dockerfile-prod` path available as a fallback until installers consistently ship a release-specific compose file. Development compose files should keep building locally from source so local edits do not depend on registry state.
+
+## Manual Runs
+
+The workflow also supports `workflow_dispatch` for validating or re-publishing the image from the current branch. Release consumers should still use tag or SHA image references rather than mutable names.
diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml
index 3ba8e4a..f0c7854 100644
--- a/documentation/mkdocs.yml
+++ b/documentation/mkdocs.yml
@@ -16,6 +16,7 @@ nav:
     - Python: https://github.com/ChengLabResearch/ouroboros/blob/main/python/README.md
     - Plugins: https://github.com/ChengLabResearch/ouroboros/blob/main/plugins/plugin-template/README.md
     - Docker Builds: 'development/docker-builds.md'
+    - Registry Server Images: 'development/registry-server-images.md'
   - Releases: 'https://github.com/ChengLabResearch/ouroboros/releases'
   - Repository: https://github.com/ChengLabResearch/ouroboros
 

From ab3eb073974e8431be68b48b53933298f8f2807c Mon Sep 17 00:00:00 2001
From: David Northover <david.northover@psu.edu>
Date: Fri, 26 Jun 2026 13:25:13 -0400
Subject: [PATCH 2/2] ci(docker): validate server image builds on PRs

---
 .github/workflows/server-image.yml | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/server-image.yml b/.github/workflows/server-image.yml
index 284d2b3..527da4e 100644
--- a/.github/workflows/server-image.yml
+++ b/.github/workflows/server-image.yml
@@ -1,6 +1,10 @@
 name: Publish Server Image
 
 on:
+  pull_request:
+    paths:
+      - .github/workflows/server-image.yml
+      - python/**
   push:
     tags:
       - v*.*.*
@@ -42,6 +46,7 @@ jobs:
         uses: docker/setup-buildx-action@v3
 
       - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
@@ -57,11 +62,11 @@ jobs:
             type=ref,event=tag
             type=sha,prefix=sha-
 
-      - name: Build and Push Server Image
+      - name: Build Server Image
         uses: docker/build-push-action@v6
         with:
           context: ./python
           file: ./python/Dockerfile-prod
-          push: true
+          push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}