Pin smoke Dockerfile to amd64; fail fast on missing overlay template

README.md

@@ -35,7 +35,7 @@ The venv lives outside the overlay because fuse2fs is single-threaded (~10 MB/s)
 | `VENV_PATH` | `/scratch/$USER/venvs/pufferdrive` |
 | `CONTAINER_PYTHON` | `/ext3/miniforge3/bin/python3` |
 
-The defaults match NYU Greene's filesystem layout. Override the env vars before invoking `setup_container.sh` if your cluster differs.
+The defaults match NYU Greene's filesystem layout. Override the env vars before invoking `setup_container.sh` if your cluster differs. In particular, the `/share/apps` defaults (`IMAGE_PATH`, `OVERLAY_TEMPLATE`) exist only on NYU Greene. `OVERLAY_TEMPLATE` is just a gzipped empty ext3 image: on other clusters point it at your site's template, or skip `create-overlay` and create the overlay directly with `apptainer overlay create --size 15360 --create-dir /ext3 <overlay-path>`. Set `IMAGE_PATH` to any CUDA-capable `.sif` (e.g. `apptainer pull docker://nvcr.io/nvidia/cuda:12.8.1-cudnn-devel-ubuntu24.04`).
 
 **One-time setup:**
 

docs/cluster_training.md

@@ -8,6 +8,8 @@ How to run PufferDrive training on a SLURM cluster. This is written with the NYU
 # One-time per cluster: create the singularity overlay and install deps
 # into the venv (this also installs submitit and the other submission
 # deps as part of the project's pyproject.toml).
+# Non-NYU clusters: export OVERLAY_TEMPLATE/IMAGE_PATH first, or create the
+# overlay with `apptainer overlay create` (see the README defaults table).
 ./scripts/setup_container.sh create-overlay
 sbatch --account=<acct> --gres=gpu:1 --cpus-per-task=8 --mem=32gb --time=60 \
     --wrap "./scripts/setup_container.sh install"

scripts/setup_container.sh

@@ -52,6 +52,15 @@ create_overlay() {
         exit 1
     fi
 
+    if [ ! -f "$OVERLAY_TEMPLATE" ]; then
+        echo "ERROR: overlay template not found at $OVERLAY_TEMPLATE"
+        echo "The default template path exists only on NYU Greene. Either:"
+        echo "  - export OVERLAY_TEMPLATE to your cluster's gzipped blank-ext3 template, or"
+        echo "  - create the overlay directly (singularity >= 3.8: 'singularity overlay create'):"
+        echo "      apptainer overlay create --size 15360 --create-dir /ext3 \"$OVERLAY_PATH\""
+        exit 1
+    fi
+
     echo "Copying and extracting overlay (this may take a few minutes)..."
     cp "$OVERLAY_TEMPLATE" "$CONTAINER_DIR/"
     TEMPLATE_NAME=$(basename "$OVERLAY_TEMPLATE")

tests/smoke_tests/Dockerfile

@@ -14,7 +14,13 @@
 #       -v "$PWD/tests/smoke_tests/data:/app/tests/smoke_tests/data" \
 #       pufferdrive-smoke
 # then commit tests/smoke_tests/data/drive_smoke_golden.json.
-FROM python:3.11-slim-bookworm
+#
+# This image is x86-64-only by definition: the golden is bit-exact AVX2 math
+# run under qemu-x86_64-static, and setup.py ships only the amd64 raylib
+# archive. On ARM hosts (e.g. Apple Silicon) Docker runs it under emulation —
+# pass --platform linux/amd64 to docker build/run if the FROM pin below is
+# not honored.
+FROM --platform=linux/amd64 python:3.11-slim-bookworm
 
 ENV DEBIAN_FRONTEND=noninteractive \
     PUFFER_CPU=1 \