Configure Docker build with SSH authentication for private repos

- Update Dockerfile to use SSH forwarding for private dependencies (paladin, Mussel)
- Add build.sh script to handle SSH agent setup for local builds
- Update pyproject.toml to use SSH URLs for private repos
- Configure GitHub Actions workflow for SSH-based Docker builds
- Add SSH agent setup with webfactory/ssh-agent action
- Configure dual registry support (GHCR + Docker Hub)
- Push to GHCR on all branches, Docker Hub only on main
- Update Makefile to use mskmind/mosaic as default image name
- Add CI/CD documentation to CONTRIBUTING.md
- Add github_token to .gitignore

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.github/workflows/docker.yml

@@ -10,8 +10,10 @@ on:
   workflow_dispatch:
 
 env:
-  REGISTRY: ghcr.io
+  GHCR_REGISTRY: ghcr.io
+  DOCKER_REGISTRY: docker.io
   IMAGE_NAME: ${{ github.repository }}
+  DOCKER_HUB_IMAGE: mskmind/mosaic
 
 jobs:
   build:
@@ -33,19 +35,27 @@ jobs:
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
 
-    - name: Log in to Container Registry
+    - name: Log in to GitHub Container Registry
       if: github.event_name != 'pull_request'
       uses: docker/login-action@v3
       with:
-        registry: ${{ env.REGISTRY }}
+        registry: ${{ env.GHCR_REGISTRY }}
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}
 
-    - name: Extract metadata
-      id: meta
+    - name: Log in to Docker Hub
+      if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.DOCKER_REGISTRY }}
+        username: ${{ secrets.DOCKER_HUB_USERNAME }}
+        password: ${{ secrets.DOCKER_HUB_TOKEN }}
+
+    - name: Extract metadata for GHCR
+      id: meta-ghcr
       uses: docker/metadata-action@v5
       with:
-        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+        images: ${{ env.GHCR_REGISTRY }}/${{ env.IMAGE_NAME }}
         tags: |
           type=ref,event=branch
           type=ref,event=pr
@@ -53,27 +63,60 @@ jobs:
           type=semver,pattern={{major}}.{{minor}}
           type=sha,prefix={{branch}}-
 
-    - name: Build and push Docker image
+    - name: Extract metadata for Docker Hub
+      id: meta-dockerhub
+      if: github.ref == 'refs/heads/main'
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.DOCKER_REGISTRY }}/${{ env.DOCKER_HUB_IMAGE }}
+        tags: |
+          type=raw,value=latest
+          type=semver,pattern={{version}}
+          type=semver,pattern={{major}}.{{minor}}
+          type=sha
+
+    - name: Build and push to GHCR
       uses: docker/build-push-action@v5
       with:
         context: .
         push: ${{ github.event_name != 'pull_request' }}
-        tags: ${{ steps.meta.outputs.tags }}
-        labels: ${{ steps.meta.outputs.labels }}
-        ssh: default
+        tags: ${{ steps.meta-ghcr.outputs.tags }}
+        labels: ${{ steps.meta-ghcr.outputs.labels }}
+        ssh: default=${{ env.SSH_AUTH_SOCK }}
         cache-from: type=gha
         cache-to: type=gha,mode=max
-        secrets: |
-          github_token=${{ secrets.GITHUB_TOKEN }}
+
+    - name: Build and push to Docker Hub
+      if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        push: true
+        tags: ${{ steps.meta-dockerhub.outputs.tags }}
+        labels: ${{ steps.meta-dockerhub.outputs.labels }}
+        ssh: default=${{ env.SSH_AUTH_SOCK }}
+        cache-from: type=gha
 
     - name: Docker Summary
       run: |
         echo "## Docker Build :whale:" >> $GITHUB_STEP_SUMMARY
         echo "" >> $GITHUB_STEP_SUMMARY
-        echo "Registry: ${{ env.REGISTRY }}" >> $GITHUB_STEP_SUMMARY
+        echo "### GitHub Container Registry" >> $GITHUB_STEP_SUMMARY
+        echo "Registry: ${{ env.GHCR_REGISTRY }}" >> $GITHUB_STEP_SUMMARY
         echo "Image: ${{ env.IMAGE_NAME }}" >> $GITHUB_STEP_SUMMARY
         echo "" >> $GITHUB_STEP_SUMMARY
-        echo "### Tags" >> $GITHUB_STEP_SUMMARY
+        echo "**Tags:**" >> $GITHUB_STEP_SUMMARY
         echo '```' >> $GITHUB_STEP_SUMMARY
-        echo "${{ steps.meta.outputs.tags }}" >> $GITHUB_STEP_SUMMARY
+        echo "${{ steps.meta-ghcr.outputs.tags }}" >> $GITHUB_STEP_SUMMARY
         echo '```' >> $GITHUB_STEP_SUMMARY
+        if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Docker Hub" >> $GITHUB_STEP_SUMMARY
+          echo "Registry: ${{ env.DOCKER_REGISTRY }}" >> $GITHUB_STEP_SUMMARY
+          echo "Image: ${{ env.DOCKER_HUB_IMAGE }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Tags:**" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "${{ steps.meta-dockerhub.outputs.tags }}" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+        fi

.gitignore

@@ -19,3 +19,7 @@ flagged/
 gradio_cached_examples/
 *.svs
 *.png
+
+# GitHub tokens and secrets
+github_token
+*_token

CONTRIBUTING.md

@@ -256,6 +256,56 @@ When adding new features:
 - Ensure dependencies are compatible with the project's license
 - Pin dependency versions in `pyproject.toml`
 
+## GitHub Actions CI/CD
+
+### Required Repository Secrets
+
+For the Docker build workflow to work properly in GitHub Actions, the following secrets must be configured in your repository settings (Settings → Secrets and variables → Actions):
+
+1. **`SSH_PRIVATE_KEY`** (Required)
+   - Your SSH private key that has access to the private repositories (paladin and Mussel)
+   - Generate with: `ssh-keygen -t ed25519 -C "github-actions@mosaic"`
+   - Add the public key to your GitHub account with repo access
+   - Add the private key to GitHub secrets
+
+2. **`DOCKER_HUB_USERNAME`** (Optional - only needed for Docker Hub pushes)
+   - Your Docker Hub username
+   - Required only if you want to push images to Docker Hub (on main branch)
+
+3. **`DOCKER_HUB_TOKEN`** (Optional - only needed for Docker Hub pushes)
+   - Your Docker Hub access token
+   - Generate at: https://hub.docker.com/settings/security
+   - Required only if you want to push images to Docker Hub (on main branch)
+
+### CI/CD Workflows
+
+The project includes several GitHub Actions workflows:
+
+- **`tests.yml`** - Runs pytest test suite on every push/PR
+- **`code-quality.yml`** - Runs black and pylint checks
+- **`docker.yml`** - Builds and pushes Docker images:
+  - Builds on every push to main/dev branches and PRs
+  - Pushes to GitHub Container Registry (ghcr.io) for all branches
+  - Pushes to Docker Hub (docker.io/mskmind/mosaic) only on main branch
+
+### Docker Build Process
+
+The Docker build uses SSH forwarding to access private dependencies:
+
+```bash
+# Local build (using build.sh)
+./build.sh
+
+# Or using Make
+make docker-build
+```
+
+The GitHub Actions workflow automatically:
+1. Sets up SSH agent with the private key
+2. Configures Docker Buildx with SSH forwarding
+3. Builds the image with access to private repositories
+4. Pushes to GHCR and optionally Docker Hub
+
 ## Questions?
 
 If you have questions about contributing, please:

Dockerfile

@@ -4,35 +4,35 @@ FROM python:3.10-slim AS env-builder
 RUN apt-get update && apt-get install -y \
     build-essential \
     curl \
-    git gh \
-    vim \
+    git \
+    openssh-client \
     && rm -rf /var/lib/apt/lists/*
 
 # Install uv
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
-# Clone paladin repo
-WORKDIR /deps
-RUN --mount=type=secret,id=github_token \
-    export GITHUB_TOKEN=$(cat /run/secrets/github_token) && \
-    git clone --branch dev https://oauth2:$GITHUB_TOKEN@github.com/pathology-data-mining/paladin.git
-
-# Create non-root user for runtime
-RUN useradd -m -u 1000 user
-RUN chown -R user:user /deps
+# Setup SSH for git (as root)
+RUN mkdir -p /root/.ssh && ssh-keyscan github.com >> /root/.ssh/known_hosts
 
 WORKDIR /app
-RUN chown -R user:user /app
+
+# Copy project files
+COPY pyproject.toml README.md ./
+COPY src/ ./src/
+
+# Create venv and install with dependencies (as root, before switching users)
+RUN --mount=type=ssh \
+    uv venv && \
+    uv pip install -e .
+
+# Create non-root user for runtime
+RUN useradd -m -u 1000 user && \
+    chown -R user:user /app
 
 USER user
-COPY --chown=user pyproject.toml README.md ./
-COPY --chown=user src/ ./src/
 
-RUN uv sync 
 ENV PATH="/app/.venv/bin:$PATH"
 
 EXPOSE 7877
 
-# HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health
-
 ENTRYPOINT ["gradio_app"]

Makefile

@@ -4,9 +4,9 @@
 .DEFAULT_GOAL := help
 
 # Variables
-DOCKER_IMAGE_NAME := mosaic
+DOCKER_IMAGE_NAME := mskmind/mosaic
 DOCKER_TAG := latest
-DOCKER_REGISTRY := # Set your registry here (e.g., docker.io/username)
+DOCKER_REGISTRY := docker.io
 PYTHON := uv run python
 PYTEST := uv run pytest
 BLACK := uv run black
@@ -83,11 +83,17 @@ run-batch: ## Run batch analysis from CSV (usage: make run-batch CSV=settings.cs
 
 ##@ Docker
 
-docker-build: ## Build Docker image
-	docker build -t $(DOCKER_IMAGE_NAME):$(DOCKER_TAG) .
+docker-build: ## Build Docker image with SSH forwarding
+	@echo "Building Docker image with SSH authentication..."
+	@./build.sh
 
 docker-build-no-cache: ## Build Docker image without cache
-	docker build --no-cache -t $(DOCKER_IMAGE_NAME):$(DOCKER_TAG) .
+	@echo "Building Docker image with SSH authentication (no cache)..."
+	@eval "$$(ssh-agent -s)" && \
+	ssh-add ~/.ssh/id_ed25519 && \
+	export DOCKER_BUILDKIT=1 && \
+	docker build --no-cache --ssh default=$$SSH_AUTH_SOCK -t $(DOCKER_IMAGE_NAME):$(DOCKER_TAG) . && \
+	eval "$$(ssh-agent -k)"
 
 docker-run: ## Run Docker container (web UI mode)
 	docker run -it --rm \

build.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+set -e
+
+# Start SSH agent and add key
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+
+# Enable BuildKit
+export DOCKER_BUILDKIT=1
+
+# Build with SSH forwarding
+docker build --ssh default=$SSH_AUTH_SOCK -t mskmind/mosaic:latest .
+
+# Kill SSH agent
+eval "$(ssh-agent -k)"

pyproject.toml

@@ -43,7 +43,7 @@ disable = [
 
 [tool.uv.sources]
 paladin = { git = "ssh://git@github.com/pathology-data-mining/paladin.git", rev = "dev" }
-mussel = { git = "https://github.com/pathology-data-mining/Mussel.git", rev = "mosaic-dev" }
+mussel = { git = "ssh://git@github.com/pathology-data-mining/Mussel.git", rev = "mosaic-dev" }
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

uv.lock

@@ -1803,7 +1803,7 @@ requires-dist = [
     { name = "lightning", specifier = ">=2.6.0" },
     { name = "loguru", specifier = ">=0.7.3" },
     { name = "memory-profiler", specifier = ">=0.61.0" },
-    { name = "mussel", extras = ["torch-gpu"], git = "https://github.com/pathology-data-mining/Mussel.git?rev=mosaic-dev" },
+    { name = "mussel", extras = ["torch-gpu"], git = "ssh://git@github.com/pathology-data-mining/Mussel.git?rev=mosaic-dev" },
     { name = "paladin", git = "ssh://git@github.com/pathology-data-mining/paladin.git?rev=dev" },
     { name = "seaborn", specifier = ">=0.13.2" },
     { name = "spaces", specifier = ">=0.30.0" },
@@ -1879,7 +1879,7 @@ wheels = [
 [[package]]
 name = "mussel"
 version = "1.1.1"
-source = { git = "https://github.com/pathology-data-mining/Mussel.git?rev=mosaic-dev#c848d4dc07845198cff79e9ddc0b261976846095" }
+source = { git = "ssh://git@github.com/pathology-data-mining/Mussel.git?rev=mosaic-dev#c848d4dc07845198cff79e9ddc0b261976846095" }
 dependencies = [
     { name = "configargparse" },
     { name = "einops" },
@@ -2082,7 +2082,7 @@ name = "nvidia-cudnn-cu12"
 version = "9.1.0.70"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12", marker = "(platform_machine != 'aarch64' and sys_platform == 'linux') or (sys_platform != 'darwin' and sys_platform != 'linux')" },
+    { name = "nvidia-cublas-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/9f/fd/713452cd72343f682b1c7b9321e23829f00b842ceaedcda96e742ea0b0b3/nvidia_cudnn_cu12-9.1.0.70-py3-none-manylinux2014_x86_64.whl", hash = "sha256:165764f44ef8c61fcdfdfdbe769d687e06374059fbb388b6c89ecb0e28793a6f", size = 664752741, upload-time = "2024-04-22T15:24:15.253Z" },
@@ -2109,9 +2109,9 @@ name = "nvidia-cusolver-cu12"
 version = "11.4.5.107"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12", marker = "(platform_machine != 'aarch64' and sys_platform == 'linux') or (sys_platform != 'darwin' and sys_platform != 'linux')" },
-    { name = "nvidia-cusparse-cu12", marker = "(platform_machine != 'aarch64' and sys_platform == 'linux') or (sys_platform != 'darwin' and sys_platform != 'linux')" },
-    { name = "nvidia-nvjitlink-cu12", marker = "(platform_machine != 'aarch64' and sys_platform == 'linux') or (sys_platform != 'darwin' and sys_platform != 'linux')" },
+    { name = "nvidia-cublas-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
+    { name = "nvidia-cusparse-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
+    { name = "nvidia-nvjitlink-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/bc/1d/8de1e5c67099015c834315e333911273a8c6aaba78923dd1d1e25fc5f217/nvidia_cusolver_cu12-11.4.5.107-py3-none-manylinux1_x86_64.whl", hash = "sha256:8a7ec542f0412294b15072fa7dab71d31334014a69f953004ea7a118206fe0dd", size = 124161928, upload-time = "2023-04-19T15:51:25.781Z" },
@@ -2122,7 +2122,7 @@ name = "nvidia-cusparse-cu12"
 version = "12.1.0.106"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink-cu12", marker = "(platform_machine != 'aarch64' and sys_platform == 'linux') or (sys_platform != 'darwin' and sys_platform != 'linux')" },
+    { name = "nvidia-nvjitlink-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/65/5b/cfaeebf25cd9fdec14338ccb16f6b2c4c7fa9163aefcf057d86b9cc248bb/nvidia_cusparse_cu12-12.1.0.106-py3-none-manylinux1_x86_64.whl", hash = "sha256:f3b50f42cf363f86ab21f720998517a659a48131e8d538dc02f8768237bd884c", size = 195958278, upload-time = "2023-04-19T15:51:49.939Z" },
@@ -3833,7 +3833,7 @@ name = "triton"
 version = "3.1.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "filelock", marker = "(platform_machine != 'aarch64' and sys_platform == 'linux') or (sys_platform != 'darwin' and sys_platform != 'linux')" },
+    { name = "filelock", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/98/29/69aa56dc0b2eb2602b553881e34243475ea2afd9699be042316842788ff5/triton-3.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6b0dd10a925263abbe9fa37dcde67a5e9b2383fc269fdf59f5657cac38c5d1d8", size = 209460013, upload-time = "2024-10-14T16:05:32.106Z" },