Added Dockerfile commands to build casatools container, locally and via GitHub Actions.

Author: iancze

.github/workflows/docker-publish.yml

@@ -0,0 +1,67 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    branches: [ "main" ]
+    tags: [ 'v*.*.*' ]
+  pull_request:
+    branches: [ "main" ]
+
+env:
+  REGISTRY: ghcr.io
+  # Dynamically set the image name to lowercase 'ghcr.io/MPoL-dev/examples'
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Sets up QEMU for multi-platform support (e.g., amd64, arm64)
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      # Sets up Docker Buildx (required for multi-arch builds and advanced caching)
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      # Log in to GitHub Container Registry
+      - name: Log in to the Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Extract metadata (tags, labels) for Docker
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=sha,format=short
+
+      # Build and push Docker image
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./casatools-env
+          file: ./Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ id.meta.outputs.tags }}
+          labels: ${{ id.meta.outputs.labels }}
+          # Specifying platforms ensures optimization across target architectures
+          platforms: linux/amd64,linux/arm64
+          # Utilizing GitHub Actions native caching dramatically speeds up subsequent builds
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

00-download-and-extract-datasets/README.md

@@ -1,14 +1,16 @@
 # Download and extract datasets
 
-Contend with the fact that `casatools` frequently lags supported SPEC 0 Python versions, creating a situation where one needs a Python version old enough to run `casatools` but new enough to support modern development. These requirements are often mutually exclusive and require multiple Python versions as part of the same analysis.
-
-We've tried to decouple these somewhat, by isolating the `casatools` dependency to this specific example folder.
-
 # Installation and running
 
-As of 21 May 2026, the latest version supported by `casatools` is Python 3.10. 
+In this 'example,' one merely downloads and extracts the ALMA datasets to a common data format like `.npz` or `.asdf`. This step requires the `casatools` package, which frequently has restrictions on Python versions and installation environments.
+
+To simplify this step for users of the tutorials, one can use our Docker container via 
+```
+./run.sh
+```
 
-You can run to download individual datasets, or all of them at once.
+Depending on the speed of your internet connection, it may take some time to download the several Gb measurement sets from the archive servers.
 
+Upon successful completion, you should see the following items in your directory:
 
-For subsequent examples, you will be asked to copy some of the data products into those folders.
+Alternatively, if one already has their own Python environment compatible casatools, one can install the [relevant packages](../casatools-env/requirements.txt) into that environment.

00-download-and-extract-datasets/run.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+docker run --rm --platform linux/amd64 \
+  -v "$(pwd)":/workspace \
+  casatools-env \
+  snakemake -c1 all

casatools-env/Dockerfile

@@ -0,0 +1,44 @@
+# casatools-env/Dockerfile
+# need to force the platform here so that casatools is available for the right
+# architecture. Doesn't work with Apple Silicon.
+FROM --platform=linux/amd64 ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install core system dependencies
+RUN apt-get update && apt-get install -y \
+    python3.12 \
+    python3.12-dev \
+    python3.12-venv \
+    python3-pip-whl \
+    gfortran \
+    libgomp1 \
+    wget \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
+
+RUN python3.12 -m venv /opt/casa_venv
+
+# Add the virtual environment binaries to the container path
+# This automatically "activates" the venv
+ENV PATH="/opt/casa_venv/bin:$PATH"
+
+# Upgrade pip inside the virtual environment
+RUN pip install --no-cache-dir --upgrade pip setuptools wheel
+
+# Copy and install requirements
+COPY requirements.txt /workspace/requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# create casa data directory
+# https://casadocs.readthedocs.io/en/stable/notebooks/external-data.html
+RUN mkdir -p /root/.casa/data
+
+COPY casasiteconfig.py /workspace/casasiteconfig.py
+ENV CASASITECONFIG="/workspace/casasiteconfig.py"
+
+# Trigger the initial measures data download inside the container build, 
+# so that this isn't redone each time the user runs the container
+# https://casadocs.readthedocs.io/en/stable/api/casaconfig.html#casasiteconfig-py
+RUN python3 -c "from casaconfig import pull_data; pull_data('/root/.casa/data')"

casatools-env/README.md

@@ -0,0 +1,16 @@
+# Docker image with casatools
+
+This folder contains the instructions and Dockerfile for how to build a Docker container that will run `casatools`, necessary for the `00-download-and-extract-datasets` example. In the normal course of events, this container is built automatically as part of the GitHub Actions workflow, and you can download it from the GitHub Container Registry following the instructions in the [00 example](../00-download-and-extract-datasets/README.md).
+
+The following instructions are aimed at developers of the examples. It is assumed that you have already installed a [Docker environment](https://www.docker.com/), e.g., such as Docker Desktop.
+
+Building the container locally, from within this directory, and tag as `casatools-env`
+```
+docker build --platform linux/amd64 -t casatools-env .
+```
+Note that the `--platform linux/amd64` is necessary to accommodate the modular casa packages, which to my understanding are not built for Apple Silicon architecture.
+
+Run the container and enter a bash shell
+```
+docker run --rm -it --platform linux/amd64 casatools-env
+```

casatools-env/build_locally.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+# note: it is not required to run this script to build the container,
+# it should already be built by GitHub workflows and available via the
+# GitHub Container Registry
+# However, if you want to build the container locally, then use this
+docker build --platform linux/amd64 -t casatools-env .

casatools-env/casasiteconfig.py

@@ -0,0 +1,18 @@
+# https://casadocs.readthedocs.io/en/stable/api/casaconfig.html#casasiteconfig-py
+# An example site config file.
+# Place this in a location checked by casaconfig:
+#  /opt/casa/casasiteconfig.py
+#  /home/casa/casasiteconfig.py
+#  the environment value CASASITECONFIG - use the fully qualified path
+#  anywhere in the python path, e.g. the site-packages directory in the CASA being used
+
+# This file should be edited to set measurespath as appropriate
+
+# Set this to point to the location where the site maintained casarundata can be found
+# by default datapath will include measurespath
+
+measurespath = "/root/.casa/data"
+
+# turn off all auto updates of data
+measures_auto_update = False
+data_auto_update = False