Build and publish Docker image to GHCR in CI

scottstanie · claude · scottstanie · commit 1526a70c528f · 2026-05-01T12:20:51.000-04:00
- Add `dockerize` job to ci.yml: builds on every push/PR (no push for PRs),
  tags `:&lt;version&gt;` always, `:develop` on main, `:latest` on `v*` tags.
  Uses Buildx + GHA cache so the pixi conda solve survives across runs.
- Pass setuptools_scm version into the build via `--build-arg VERSION=`
  so the image reports the real version; image tag uses a sanitized form
  (Docker tags forbid `+`, but PEP 440 forbids `-`, so we keep both).
- Add `.dockerignore` to keep build context lean (skips node_modules,
  .pixi, data/, screenshots, .git, etc).
- Add OCI labels (title, description, source, licenses, ...) to Dockerfile.
- Update deploy/README.md: pull-from-GHCR is now the primary path, and
  document the local-build prerequisites (frontend bundle, --platform
  linux/amd64 on Apple Silicon).

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.dockerignore b/.dockerignore
@@ -0,0 +1,62 @@
+# Pixi environment (recreated inside the container)
+.pixi/
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging (root-anchored — does NOT exclude src/bowser/dist/)
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Test / coverage / type-check caches
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Documentation build output
+docs/_build/
+site/
+
+# IDE / editor / OS files
+.vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+Thumbs.db
+*.local
+
+# Git
+.git/
+.gitignore
+.git-blame-ignore-revs
+.gitattributes
+
+# Frontend tooling: bundle is built on the runner before `docker build`,
+# so node_modules itself is not needed in the image context.
+node_modules/
+
+# Local data and artifacts that have no business in the build context
+data/
+tests/data/
+screenshots/
+iris-screenshots/
+tre-maps-screenshots/
+viz-lonboard-*.html
+viz-lonboard-*.ipynb
+*.parquet/
+work-walkthrough2
+
+# Notebook checkpoints
+.ipynb_checkpoints/
+
+# Env / secrets
+.env
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -38,3 +38,79 @@ jobs:
       - name: Test
         run: |
           pixi run -e all pytest
+
+  dockerize:
+    name: Build Docker image and push to GHCR
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - name: Build frontend bundle
+        # Dockerfile copies src/ which must contain the built frontend at
+        # src/bowser/dist/. That directory is gitignored, so it has to be
+        # produced on the runner before `docker build` is invoked.
+        run: |
+          npm ci
+          npm run build
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+      - name: Compute version from setuptools_scm
+        run: |
+          pip install setuptools_scm
+          version=$(python -m setuptools_scm)
+          # BOWSER_VERSION stays PEP 440 (keeps '+') — used for the build arg
+          # so setuptools_scm can read it back inside the image.
+          # BOWSER_IMAGE_TAG sanitizes '+' to '-' because Docker tags forbid '+'.
+          echo "BOWSER_VERSION=${version}" >> "$GITHUB_ENV"
+          echo "BOWSER_IMAGE_TAG=${version//+/-}" >> "$GITHUB_ENV"
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Login to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build, tag, and push image to GHCR
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          build-args: |
+            VERSION=${{ env.BOWSER_VERSION }}
+          tags: |
+            ghcr.io/${{ github.repository }}:${{ env.BOWSER_IMAGE_TAG }}
+          labels: |
+            org.opencontainers.image.version=${{ env.BOWSER_VERSION }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.created=${{ github.event.head_commit.timestamp }}
+          # GHA-cache layers across runs — biggest win is the pixi conda solve
+          # in stage 1, which otherwise re-runs from scratch each build.
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - name: Add develop tag (main branch only)
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: akhilerm/tag-push-action@v2.2.0
+        with:
+          src: ghcr.io/${{ github.repository }}:${{ env.BOWSER_IMAGE_TAG }}
+          dst: ghcr.io/${{ github.repository }}:develop
+      - name: Add latest tag (release tags only)
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: akhilerm/tag-push-action@v2.2.0
+        with:
+          src: ghcr.io/${{ github.repository }}:${{ env.BOWSER_IMAGE_TAG }}
+          dst: ghcr.io/${{ github.repository }}:latest
diff --git a/Dockerfile b/Dockerfile
@@ -7,28 +7,47 @@ FROM ghcr.io/prefix-dev/pixi:0.65.0 AS install
 
 WORKDIR /app
 
+# `.git` is excluded from the build context (.dockerignore), so setuptools_scm
+# cannot read the version from git. The CI workflow passes the real version
+# via --build-arg VERSION=...; local builds default to 0.0.0.
+ARG VERSION=0.0.0
+ENV SETUPTOOLS_SCM_PRETEND_VERSION_FOR_BOWSER_INSAR=${VERSION}
+
 COPY pyproject.toml pixi.lock ./
 
-# Create minimal source structure so pixi can resolve the editable workspace
+# Minimal source structure so pixi can resolve the editable workspace
 RUN mkdir -p src/bowser && \
     touch src/bowser/__init__.py && \
-    printf 'version = "0.0.0"\n__version__ = version\n' > src/bowser/_version.py
+    printf 'version = "%s"\n__version__ = version\n' "${VERSION}" > src/bowser/_version.py
 
-ENV SETUPTOOLS_SCM_PRETEND_VERSION_FOR_BOWSER_INSAR=0.0.0
 RUN --mount=type=cache,target=/root/.cache/rattler/cache,sharing=private \
     pixi install -e default
 
 # Stage 2: drop the real source + bake the activation script
 FROM install AS build
 
+ARG VERSION=0.0.0
+ENV SETUPTOOLS_SCM_PRETEND_VERSION_FOR_BOWSER_INSAR=${VERSION}
+
 COPY src/ /app/src/
 
+# _version.py is gitignored, so the real source tree probably lacks it.
+# Re-write it with the build-arg version so the running image reports correctly.
+RUN printf 'version = "%s"\n__version__ = version\n' "${VERSION}" > src/bowser/_version.py
+
 RUN pixi shell-hook -e default > /activate.sh && \
     chmod +x /activate.sh
 
 # Stage 3: minimal production image — no pixi, just the resolved env
 FROM ubuntu:24.04 AS production
 
+LABEL org.opencontainers.image.title="bowser"
+LABEL org.opencontainers.image.description="Web browsing tool for InSAR data"
+LABEL org.opencontainers.image.source="https://github.com/opera-adt/bowser"
+LABEL org.opencontainers.image.url="https://github.com/opera-adt/bowser"
+LABEL org.opencontainers.image.documentation="https://github.com/opera-adt/bowser#readme"
+LABEL org.opencontainers.image.licenses="BSD-3-Clause OR Apache-2.0"
+
 RUN apt-get update && apt-get install -y --no-install-recommends \
         ca-certificates curl \
     && rm -rf /var/lib/apt/lists/*
diff --git a/deploy/README.md b/deploy/README.md
@@ -1,21 +1,27 @@
 # Deploy
 
-Minimal path to run bowser on one EC2 instance serving a catalog of GeoZarr
-stores from S3.
+Minimal path to run bowser on one EC2 instance serving a catalog of GeoZarr stores from S3.
 
 ## Build the image
 
+CI builds and pushes `ghcr.io/opera-adt/bowser:<version>` (plus `:develop` on `main` and `:latest` on `v*` tags) — see `.github/workflows/ci.yml`. Pull the published image with:
+
+```bash
+docker pull ghcr.io/opera-adt/bowser:latest
+```
+
+To build locally:
+
 ```bash
-docker build -t bowser:local .
-# or tag for a registry and push
-docker tag bowser:local ghcr.io/opera-adt/bowser:latest
-docker push ghcr.io/opera-adt/bowser:latest
+# Frontend bundle is gitignored; build it first so it gets COPY'd into the image.
+npm ci && npm run build
+
+# On Apple Silicon, force linux/amd64 — pyproject.toml's pixi platforms list
+# doesn't include linux-aarch64.
+docker build --platform linux/amd64 -t bowser:local .
 ```
 
-The image uses a three-stage pixi build: pixi resolves conda-forge GDAL /
-rasterio / rioxarray in stage 1, the final `ubuntu:24.04` stage ships only
-the resolved env and bowser source. No pixi, no python build tools in
-production.
+The image uses a three-stage pixi build: pixi resolves conda-forge GDAL / rasterio / rioxarray in stage 1, the final `ubuntu:24.04` stage ships only the resolved env and bowser source. No pixi, no python build tools in production.
 
 ## Run locally
 
@@ -49,12 +55,9 @@ aws s3 cp catalog.toml s3://bowser-demo-data/catalog.toml
 
 Launch an EC2 instance (Amazon Linux 2023 or Ubuntu 24.04):
 - Instance type: `t3.medium` is enough for a demo; `c6i.large` for concurrent viewers.
-- IAM instance profile: needs `s3:GetObject` on the data bucket (both the
-  catalog object and the dataset prefixes it references).
-- Security group: open port 80 (HTTP). For HTTPS, add Caddy or put an ALB
-  in front.
-- User data: `deploy/ec2-bootstrap.sh`, with `IMAGE` and `CATALOG_S3` edited
-  at the top.
+- IAM instance profile: needs `s3:GetObject` on the data bucket (both the catalog object and the dataset prefixes it references).
+- Security group: open port 80 (HTTP). For HTTPS, add Caddy or put an ALB in front.
+- User data: `deploy/ec2-bootstrap.sh`, with `IMAGE` and `CATALOG_S3` edited at the top.
 
 First boot takes 1-2 min (docker install + image pull). Check progress:
 ```bash
