How to run a pipeline using a Spack container
=============================================

This guide explains how to run a pipeline using a pre-built ``ska-sdp-spack`` OCI image. As a
concrete example, it shows how to run the CIMG pipeline inside the container. User can run any
pipeline provided by ``ska-sdp-spack``.

Related
-------

- `ska-sdp-spack documentation <https://developer.skao.int/projects/ska-sdp-spack/en/latest/>`_
- `CIMG pipeline documentation <https://developer.skao.int/projects/ska-sdp-cimg/en/latest/>`_

Prerequisites
-------------

- `Docker <https://docs.docker.com/get-docker/>`_ (or an OCI-compatible runtime such as `Podman
  <https://podman.io/>`_) installed on your machine.
- Input data files accessible from your working directory:

  - A Measurement Set (MSv2)
  - A pipeline configuration file (e.g. ``config.yaml``); example configs are available in the
    config directory of the `CIMG repository
    <https://gitlab.com/ska-telescope/sdp/science-pipeline-workflows/ska-sdp-cimg>`_
  - [Optional] A solutions file (``.h5``)
  - [Optional] A facet regions file (``.reg``)

Steps
-----

1. Set the image tag for the Spack container you want to use:

   .. code-block:: bash

       export OCI_TAG=2026.04.5

2. Pull the Spack image from the SKAO Central Artefact Repository. Currently, you can choose between
   an Ubuntu-based image and a RHEL-9 based image:

   .. code-block:: bash

       # Ubuntu
       docker pull artefact.skao.int/ska-sdp-spack-ubuntu:${OCI_TAG}

       # RHEL-9
       docker pull artefact.skao.int/ska-sdp-spack-rhel9:${OCI_TAG}

3. Change to the directory that contains your input data:

   .. code-block:: bash

       cd /path/to/your/data

4. Start an interactive shell inside the container, mounting your current directory as ``/work``:

   .. code-block:: bash

       docker run --rm -it \
           -v "$PWD":/work \
           -w /work \
           artefact.skao.int/ska-sdp-spack-ubuntu:${OCI_TAG} \
           /bin/bash

   Replace ``ska-sdp-spack-ubuntu`` with ``ska-sdp-spack-rhel9`` if you pulled the RHEL-9 image.

   The container entrypoint automatically initialises Spack and activates the bundled environment.
   Your host files would be available under ``/work``.

5. Inside the container, run the CIMG pipeline:

   .. code-block:: bash

       python -m ska_sdp_cimg --config-path config.yaml \
           --solutions-path field-solutions.h5 \
           --facet-regions-path facet_regions.reg \
           --output-dir output \
           --tmp-dir temp \
           --ms-path calibrated_input.ms

   Adjust the argument values to match your actual file names and paths.

Verification
------------

After the pipeline finishes, check the ``output`` directory (inside your working directory on the
host) for the expected data products. Refer to the `CIMG pipeline documentation
<https://developer.skao.int/projects/ska-sdp-cimg/en/latest/>`_ for details on the expected output
files and logs.