Add container runtime setup script

Author: francois-drielsma

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.13.3] - 2026-06-03
+
+### Added
+- **Container runtime setup script**: Add `/opt/spine/setup.sh` and `/opt/spine/check-env.sh` to the published container image so ROOT/LArCV/SPINE runtime environment setup is explicit, testable, and recoverable when unpacked-image runtimes fail to apply the container environment automatically.
+
 ## [0.13.2] - 2026-06-02
 
 ### Changed

README.md

@@ -80,6 +80,19 @@ apptainer exec --nv spine_<release>.sif \
 
 The Docker and Apptainer paths consume the same released image; the difference is only the container runtime.
 
+The published image now includes a canonical fallback setup script at
+`/opt/spine/setup.sh`. Normal Docker and Apptainer execution should not require
+manual sourcing. Some sites expose the image through CVMFS as an unpacked root
+filesystem; in that mode, the site integration should still apply the image
+environment automatically. If it does not, diagnose the runtime from inside that
+unpacked-image environment with:
+
+```bash
+source /opt/spine/setup.sh
+/opt/spine/check-env.sh
+python -c "import ROOT, larcv, spine"
+```
+
 ### Local Python Installation
 
 Use a local pip installation when you only need downstream tooling such as post-processing, analysis, visualization, documentation, or light development.

docker/README.md

@@ -244,6 +244,29 @@ apptainer run --nv \
 
 When pulled with Apptainer/Singularity, the fully built image is about **5.7 GB**.
 
+### CVMFS / Unpacked Image Environments
+
+Some sites distribute container root filesystems through CVMFS or another
+unpacked-image mechanism instead of asking users to run a local `.sif` file.
+That is a supported distribution model, but the site integration layer is still
+responsible for applying the image environment automatically. Users should not
+normally need to set `PYTHONPATH` or `LD_LIBRARY_PATH` by hand.
+
+The SPINE image includes `/opt/spine/setup.sh` as the canonical fallback recipe
+for the runtime environment, plus `/opt/spine/check-env.sh` for diagnostics. If
+an unpacked-image launch path starts SPINE but cannot import ROOT or LArCV,
+run the following from inside that same unpacked-image environment:
+
+```bash
+source /opt/spine/setup.sh
+/opt/spine/check-env.sh
+python -c "import ROOT, larcv, spine"
+```
+
+If that succeeds, the image contains the expected dependencies and the remaining
+issue is that the CVMFS/OSG launch path is not applying the image environment
+before starting SPINE.
+
 ### HPC SLURM Example
 
 ```bash

docker/spine/Dockerfile

@@ -127,21 +127,29 @@ RUN pip install --no-cache-dir \
 ARG OPT0FINDER_REF=v1.0.0
 ARG OPT0FINDER_COMMIT=bd03fa90eaae9d753a68db390df80470a6181039
 ARG OPT0FINDER_MAX_JOBS=2
-ENV FMATCH_BASEDIR=/opt/OpT0Finder \
+ENV SPINE_RUNTIME_DIR=/opt/spine \
+    ROOTSYS=/opt/root \
+    LARCV_BASEDIR=/app/larcv2 \
+    LARCV_LIBDIR=/app/larcv2/build/lib \
+    LARCV_PYTHONDIR=/app/larcv2/python \
+    FMATCH_BASEDIR=/opt/OpT0Finder \
     FMATCH_BUILDDIR=/opt/OpT0Finder/build \
     FMATCH_LIBDIR=/opt/OpT0Finder/build/lib \
     FMATCH_INCDIR=/opt/OpT0Finder/build/include \
     FMATCH_BINDIR=/opt/OpT0Finder/build/bin \
     FMATCH_DATADIR=/opt/OpT0Finder/dat \
-    LD_LIBRARY_PATH=/opt/OpT0Finder/build/lib:${LD_LIBRARY_PATH} \
-    PYTHONPATH=/opt/OpT0Finder/python:${PYTHONPATH} \
-    PATH=/opt/OpT0Finder/bin:/opt/OpT0Finder/build/bin:${PATH}
+    LD_LIBRARY_PATH=/opt/root/lib:/app/larcv2/build/lib:/opt/OpT0Finder/build/lib:${LD_LIBRARY_PATH} \
+    PYTHONPATH=/app/larcv2/python:/opt/OpT0Finder/python:/opt/root/lib:${PYTHONPATH} \
+    PATH=/opt/root/bin:/opt/OpT0Finder/bin:/opt/OpT0Finder/build/bin:${PATH}
 RUN git clone https://github.com/DeepLearnPhysics/OpT0Finder.git ${FMATCH_BASEDIR} && \
     cd ${FMATCH_BASEDIR} && \
     git checkout ${OPT0FINDER_REF} && \
     test "$(git rev-parse HEAD)" = "${OPT0FINDER_COMMIT}" && \
     bash -lc "source ./configure.sh && make -j${OPT0FINDER_MAX_JOBS}"
 
+COPY docker/spine/setup.sh docker/spine/check-env.sh /opt/spine/
+RUN chmod 755 /opt/spine/setup.sh /opt/spine/check-env.sh
+
 # Make ROOT/LArCV/OpT0Finder imports survive user-provided PYTHONPATH overrides,
 # such as `-e PYTHONPATH=/workspace/src` for editable notebook sessions.
 RUN python -c "import site; print('\n'.join(site.getsitepackages()))" | \
@@ -177,6 +185,14 @@ COPY src/ ./src/
 # Install SPINE with all dependencies
 RUN pip install --no-cache-dir --no-build-isolation .[all]
 
+# Verify that the default container environment and the explicit fallback setup
+# recipe both provide the compiled dependency imports SPINE needs at runtime.
+RUN python -c "import ROOT, larcv, spine; print('container runtime imports ok')"
+RUN /opt/spine/check-env.sh
+RUN env -u ROOTSYS -u LARCV_BASEDIR -u LARCV_LIBDIR -u LARCV_PYTHONDIR \
+    -u PYTHONPATH -u LD_LIBRARY_PATH bash -lc \
+    "source /opt/spine/setup.sh && /opt/spine/check-env.sh"
+
 # Set working directory for user data
 WORKDIR /workspace
 

docker/spine/check-env.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+source /opt/spine/setup.sh
+
+echo "which python: $(command -v python)"
+python - <<'PY'
+import os
+import sys
+
+print(f"sys.executable: {sys.executable}")
+for key in (
+    "ROOTSYS",
+    "LARCV_BASEDIR",
+    "LARCV_LIBDIR",
+    "LARCV_PYTHONDIR",
+    "PYTHONPATH",
+    "LD_LIBRARY_PATH",
+):
+    print(f"{key}: {os.environ.get(key, '')}")
+
+import ROOT
+
+print(f"ROOT OK: {ROOT.gROOT.GetVersion()}")
+
+import larcv
+
+print(f"larcv OK: {larcv}")
+
+import spine
+
+print(f"spine OK: {spine}")
+PY

docker/spine/setup.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+
+# Canonical runtime environment for SPINE container dependencies.
+# This script is primarily a fallback for runtimes that expose the image
+# filesystem but fail to apply the container environment automatically.
+
+if [ "${BASH_SOURCE[0]:-}" = "$0" ]; then
+    echo "Source this file instead of executing it: source /opt/spine/setup.sh" >&2
+    exit 1
+fi
+
+_spine_prepend_path() {
+    local var_name="$1"
+    local entry="$2"
+    local current_value
+
+    if [ ! -e "${entry}" ]; then
+        return 0
+    fi
+
+    current_value="${!var_name:-}"
+    case ":${current_value}:" in
+        *":${entry}:"*) ;;
+        "")
+            export "${var_name}=${entry}"
+            ;;
+        *)
+            export "${var_name}=${entry}:${current_value}"
+            ;;
+    esac
+}
+
+export SPINE_RUNTIME_DIR="${SPINE_RUNTIME_DIR:-/opt/spine}"
+export ROOTSYS="${ROOTSYS:-/opt/root}"
+export LARCV_BASEDIR="${LARCV_BASEDIR:-/app/larcv2}"
+export LARCV_LIBDIR="${LARCV_LIBDIR:-${LARCV_BASEDIR}/build/lib}"
+export LARCV_PYTHONDIR="${LARCV_PYTHONDIR:-${LARCV_BASEDIR}/python}"
+export FMATCH_BASEDIR="${FMATCH_BASEDIR:-/opt/OpT0Finder}"
+export FMATCH_BUILDDIR="${FMATCH_BUILDDIR:-${FMATCH_BASEDIR}/build}"
+export FMATCH_LIBDIR="${FMATCH_LIBDIR:-${FMATCH_BUILDDIR}/lib}"
+export FMATCH_INCDIR="${FMATCH_INCDIR:-${FMATCH_BUILDDIR}/include}"
+export FMATCH_BINDIR="${FMATCH_BINDIR:-${FMATCH_BUILDDIR}/bin}"
+export FMATCH_DATADIR="${FMATCH_DATADIR:-${FMATCH_BASEDIR}/dat}"
+
+_spine_prepend_path PATH "${ROOTSYS}/bin"
+_spine_prepend_path PATH "${FMATCH_BASEDIR}/bin"
+_spine_prepend_path PATH "${FMATCH_BINDIR}"
+
+_spine_prepend_path LD_LIBRARY_PATH "${ROOTSYS}/lib"
+_spine_prepend_path LD_LIBRARY_PATH "${LARCV_LIBDIR}"
+_spine_prepend_path LD_LIBRARY_PATH "${FMATCH_LIBDIR}"
+
+_spine_prepend_path PYTHONPATH "${LARCV_PYTHONDIR}"
+_spine_prepend_path PYTHONPATH "${FMATCH_BASEDIR}/python"
+_spine_prepend_path PYTHONPATH "${ROOTSYS}/lib"
+
+unset -f _spine_prepend_path

src/spine/version.py

@@ -1,3 +1,3 @@
 """Module which stores the current software version."""
 
-__version__ = "0.13.2"
+__version__ = "0.13.3"