Migrate container deployment to GHCR and remove obsolete workflows

- Remove obsolete Quarto publish workflow (docs now use Sphinx/MyST)
- Fix docker-image.yml: point to container/Containerfile, use GHCR
  with built-in GITHUB_TOKEN (no external secrets needed)
- Remove uw3-release-candidate from binder-image.yml triggers
- Update all documentation and scripts to reference GHCR instead
  of DockerHub for both container types
- Update container/README.md with pull/run instructions for GHCR

Underworld development team with AI support from Claude Code

Author: lmoresi

.github/workflows/binder-image.yml

@@ -4,11 +4,11 @@ name: "GHCR: Binder Base Image"
 # The image is used by mybinder.org via the uw3-binder-launcher repository
 #
 # This is separate from docker-image.yml which builds command-line Docker
-# images for DockerHub.
+# images (also on GHCR, different image name).
 
 on:
   push:
-    branches: [main, uw3-release-candidate, development]
+    branches: [main, development]
     paths:
       # Only rebuild when these files change (Cython/dependencies require rebuild)
       - 'container/Dockerfile.base.optimized'

.github/workflows/docker-image.yaml

@@ -1,33 +1,61 @@
-name: "DockerHub: Command-Line Container"
+name: "GHCR: Command-Line Container"
+
+# Builds the Underworld3 command-line Docker image and pushes to GHCR.
+# Uses container/Containerfile (micromamba-based image for local use).
+#
+# This is separate from binder-image.yml which builds Binder-ready images
+# optimized for mybinder.org.
 
 on:
   push:
-    branches:
-      - development
+    branches: [main, development]
+    paths:
+      # Only rebuild when these files change
+      - 'container/Containerfile'
+      - 'environment.yaml'
+      - 'src/**/*.pyx'
+      - 'src/**/*.c'
+      - 'setup.py'
+      - 'pyproject.toml'
+  workflow_dispatch:
+    inputs:
+      force_rebuild:
+        description: 'Force full rebuild (no cache)'
+        type: boolean
+        default: false
 
 jobs:
-  push-to-dockerhub:
+  build-and-push:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Exact branch name
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Extract branch name
         run: echo "BRANCH=${GITHUB_REF##*/}" >> $GITHUB_ENV
 
-      - name: Login to DockerHub
+      - name: Login to GHCR
         uses: docker/login-action@v3
         with:
-          username: ${{ secrets.XXX_USERNAME }}
-          password: ${{ secrets.XXX_PWORD }}
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push Docker image
         uses: docker/build-push-action@v6
         with:
           context: .
           push: true
-          file: ./Dockerfile
+          file: container/Containerfile
           platforms: linux/amd64
-          # see https://github.com/docker/build-push-action/issues/276 for syntax help
-          tags: underworldcode/underworld3:${{ env.BRANCH }} #-$(date +%s)
+          no-cache: ${{ inputs.force_rebuild || false }}
+          tags: |
+            ghcr.io/underworldcode/underworld3:${{ env.BRANCH }}
+            ghcr.io/underworldcode/underworld3:latest

.github/workflows/publish.yaml

@@ -5,6 +5,11 @@ This directory contains all Dockerfiles for Underworld3, supporting two use case
 1. **Command-line containers** - For users who want to run UW3 locally without installation
 2. **Binder containers** - For mybinder.org web-based launches
 
+Both containers are hosted on **GitHub Container Registry (GHCR)** using the
+repository's built-in `GITHUB_TOKEN` for authentication (no external secrets required).
+
+---
+
 ## Command-Line Container (Containerfile)
 
 Lightweight container for local command-line use with Docker or Podman.
@@ -14,34 +19,54 @@ Lightweight container for local command-line use with Docker or Podman.
 | `Containerfile` | Micromamba-based image for local use |
 | `launch-container.sh` | Podman launch script with rootless support |
 
-### Building
+### Pulling Pre-Built Images
 
 ```bash
-# From repository root (requires Docker or Podman)
-podman build . --rm \
-    --format docker \
-    -f ./container/Containerfile \
-    -t underworldcode/underworld3:local
+# Pull the latest development image
+docker pull ghcr.io/underworldcode/underworld3:development
 
-# Or with Docker
-docker build -f container/Containerfile -t underworldcode/underworld3:local .
+# Or a specific branch
+docker pull ghcr.io/underworldcode/underworld3:main
 ```
 
 ### Running
 
 ```bash
-# Using the launch script (Podman, recommended)
-./container/launch-container.sh
+# Run the pre-built image
+docker run -it --rm -p 8888:8888 ghcr.io/underworldcode/underworld3:development
 
-# Or manually with Docker
-docker run -it --rm -p 8888:8888 underworldcode/underworld3:local
+# Using the launch script (Podman, recommended for local builds)
+./container/launch-container.sh
 ```
 
 The launch script:
 - Maps `$HOME/uw_space` into the container for file transfer
 - Runs Jupyter on port 10000 (http://localhost:10000)
 - Handles rootless Podman UID/GID mapping
 
+### Building Locally
+
+```bash
+# From repository root (requires Docker or Podman)
+podman build . --rm \
+    --format docker \
+    -f ./container/Containerfile \
+    -t underworld3:local
+
+# Or with Docker
+docker build -f container/Containerfile -t underworld3:local .
+```
+
+### GitHub Actions
+
+The `docker-image.yml` workflow automatically builds and pushes to GHCR when:
+- `container/Containerfile` changes
+- `environment.yaml` changes
+- Cython files (`.pyx`) or C files change
+- `setup.py` or `pyproject.toml` changes
+
+Can also be triggered manually via workflow_dispatch.
+
 ### Architecture
 
 At present only amd64 architecture is built, because vtk-osmesa isn't available for arm by default.
@@ -109,7 +134,7 @@ docker run --rm -p 8888:8888 ghcr.io/underworldcode/uw3-base:test-slim
 
 ### Layer Size Constraints
 
-mybinder.org has an ~1GB layer size limit. The optimized Dockerfile splits the `lib` directory into multiple layers to stay under this limit. See `docs/developer/BINDER_CONTAINER_SETUP.md` for details.
+mybinder.org has an ~1GB layer size limit. The optimized Dockerfile splits the `lib` directory into multiple layers to stay under this limit. See `docs/developer/guides/BINDER_CONTAINER_SETUP.md` for details.
 
 ### GitHub Actions
 
@@ -130,12 +155,13 @@ It also triggers the launcher repo to update its image reference.
 | **File** | `Containerfile` | `Dockerfile.base.optimized` |
 | **Base** | micromamba | Ubuntu + Pixi |
 | **Size** | ~2GB | ~3.4GB (slim) |
-| **Registry** | DockerHub | GHCR |
+| **Registry** | GHCR | GHCR |
+| **Image** | `ghcr.io/underworldcode/underworld3:<branch>` | `ghcr.io/underworldcode/uw3-base:<branch>-slim` |
 | **Use case** | Local `docker run` | mybinder.org |
 | **Workflow** | `docker-image.yml` | `binder-image.yml` |
 
 ## Related
 
-- **Binder setup docs**: `docs/developer/BINDER_CONTAINER_SETUP.md`
+- **Binder setup docs**: `docs/developer/guides/BINDER_CONTAINER_SETUP.md`
 - **Launcher repo**: https://github.com/underworldcode/uw3-binder-launcher
 - **Badge generator**: `scripts/binder_wizard.py`

container/README.md

@@ -40,7 +40,7 @@ podman run -it --rm \
   --gidmap 0:1:$gid \
   --gidmap $(($gid+1)):$(($gid+1)):$((subgidSize-$gid)) \
   -v "${HOME}/uw_space":/home/mambauser/host \
-  docker.io/underworldcode/underworld3:development
+  ghcr.io/underworldcode/underworld3:development
 
 ## Description of rootless podman and uidmap/gidmap.
 # Rootless podman allows a non-root user to run a container without elevated permissions.

container/launch-container.sh

@@ -15,7 +15,7 @@ This log tracks significant development work at a conceptual level, suitable for
   - Pushes to `ghcr.io/underworldcode/uw3-base:<branch>-slim`
   - Cross-repo dispatch updates launcher repository automatically
 
-- **Command-line images** (`docker-image.yml`): Separate workflow for DockerHub (micromamba-based)
+- **Command-line images** (`docker-image.yml`): Separate workflow for GHCR (micromamba-based)
 
 - **Launcher auto-update**: `uw3-binder-launcher` receives `repository_dispatch` events and updates its Dockerfile reference automatically
 

docs/developer/CHANGELOG.md

@@ -40,7 +40,7 @@ podman run -it --rm \
   --gidmap 0:1:$gid \
   --gidmap $(($gid+1)):$(($gid+1)):$((subgidSize-$gid)) \
   -v "${HOME}/uw_space":/home/mambauser/host \
-  docker.io/underworldcode/underworld3:development 
+  ghcr.io/underworldcode/underworld3:development
 
 ## Description of rootless podman and uidmap/gidmap.
 # Rootless podman allows a non-root user to run a container without elevated permissions.

docs/developer/container/launch-container.sh

@@ -18,7 +18,7 @@ Underworld3 provides two container deployment strategies for different use cases
          │                  │              │binder-image │
          │                  │              │    .yml     │
          ▼                  ▼              └──────┬──────┘
-   GHCR (binder)      DockerHub                   │
+   GHCR (binder)      GHCR (CLI)                  │
    ~3.4GB slim        ~2GB                        ▼
          │                               uw3-binder-launcher
          │                               (auto-updated)
@@ -54,7 +54,7 @@ ghcr.io/underworldcode/uw3-base:<branch>-slim
 ghcr.io/underworldcode/uw3-base:latest-slim
 ```
 
-Branch-specific tags (`main-slim`, `uw3-release-candidate-slim`, `development-slim`) enable testing different versions.
+Branch-specific tags (`main-slim`, `development-slim`) enable testing different versions.
 
 ### Build Triggers
 
@@ -93,7 +93,6 @@ uw3-binder-launcher/
 | Launcher Branch | UW3 Branch | Binder URL |
 |-----------------|------------|------------|
 | `main` | `main` | `mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/main` |
-| `uw3-release-candidate` | `uw3-release-candidate` | `mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/uw3-release-candidate` |
 | `development` | `development` | `mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development` |
 
 ### Automation Pipeline
@@ -135,7 +134,7 @@ Command-line containers provide a lightweight option for users who want to run U
 |------|----------|---------|
 | `Containerfile` | `container/` | Micromamba-based image (~2GB) |
 | `launch-container.sh` | `container/` | Podman launch script |
-| `docker-image.yml` | `.github/workflows/` | DockerHub build workflow |
+| `docker-image.yml` | `.github/workflows/` | GHCR build workflow |
 
 ### Building Locally
 
@@ -167,7 +166,7 @@ This script:
 **Manual Docker run**:
 
 ```bash
-docker run -it --rm -p 8888:8888 underworldcode/underworld3:development
+docker run -it --rm -p 8888:8888 ghcr.io/underworldcode/underworld3:development
 ```
 
 ### Rootless Podman
@@ -181,7 +180,7 @@ podman run -it --rm \
   --uidmap 0:1:$uid \
   # ... additional mappings
   -v "${HOME}/uw_space":/home/mambauser/host \
-  docker.io/underworldcode/underworld3:development
+  ghcr.io/underworldcode/underworld3:development
 ```
 
 ```{warning}
@@ -190,13 +189,14 @@ Do NOT run the launch script with `sudo`. Rootless Podman requires the executing
 
 ### Image Registry
 
-Command-line images are pushed to DockerHub:
+Command-line images are pushed to GHCR (same registry as binder images):
 
 ```
-underworldcode/underworld3:<branch>
+ghcr.io/underworldcode/underworld3:<branch>
+ghcr.io/underworldcode/underworld3:latest
 ```
 
-Currently only the `development` branch triggers automated builds.
+Builds trigger on pushes to `main` and `development` branches when container-related files change. Can also be triggered manually via workflow_dispatch.
 
 ## Comparison
 
@@ -205,7 +205,7 @@ Currently only the `development` branch triggers automated builds.
 | **Dockerfile** | `Dockerfile.base.optimized` | `Containerfile` |
 | **Base** | Ubuntu + Pixi | Micromamba |
 | **Size** | ~3.4GB (slim) | ~2GB |
-| **Registry** | GHCR | DockerHub |
+| **Registry** | GHCR | GHCR |
 | **Use case** | mybinder.org | Local `docker run` |
 | **Workflow** | `binder-image.yml` | `docker-image.yml` |
 | **Automation** | Full (build + launcher update) | Build only |