.. _docker_guide:

Using Sassena with Docker
=========================

Sassena provides a convenient ``runner.sh`` script that handles building and running Sassena inside a Docker container. This approach ensures you have all the correct dependencies without modifying your local system.

.. note::
   You must have **Docker** installed on your system to use these features.

If you are unfamiliar with Docker, it is a platform for developing, shipping, and running applications in isolated environments called containers. You can learn more about the fundamentals in the `official Docker overview <https://docs.docker.com/get-started/overview/>`_.

Key Concepts
------------

If you are new to containerization, here is a brief explanation of the terminology used in this script:

*   **Docker Build**: This creates a self-contained "image"—a snapshot of a Linux operating system with Sassena and all its complex dependencies (HDF5, Boost, MPI) pre-installed. This guarantees reproducibility: if the simulation runs on your laptop, it will run exactly the same way on a cluster or a colleague's machine.

*   **Local Build**: This compiles the code directly on your computer's operating system (without Docker). This requires you to manually install all development libraries. This is primarily useful for developers modifying the C++ source code who want faster incremental compilation, but it is harder to set up.

*   **Cache vs. No-Cache**: Docker remembers previous build steps to save time. If you change one file, it usually only recompiles that specific part (using the **cache**). Using ``--no-cache`` forces Docker to ignore previous work and rebuild everything from scratch. This is useful if you suspect a build artifact is corrupted or if you want to ensure you have the absolute latest system updates.


The Runner Script
-----------------

The ``runner.sh`` script is located in the root of the repository. It acts as a wrapper around Docker commands.

Basic Usage
^^^^^^^^^^^

.. code-block:: bash

   ./runner.sh [command] [options]

Available Commands
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Command
     - Description
   * - ``build``
     - Builds the Docker image containing Sassena.
   * - ``run``
     - Runs Sassena inside the container using your local data.
   * - ``test``
     - Runs the test suite (Unit/Integration) in Docker or locally.
   * - ``build-local``
     - Compiles Sassena directly on your machine (no Docker).
   * - ``help``
     - Displays the help message with all available options.

Workflow Example
----------------

1. Build the Image
^^^^^^^^^^^^^^^^^^

First, build the Docker image. You can choose between a CPU or CUDA (GPU) build.

.. code-block:: bash

   # Build for CPU (default)
   ./runner.sh build --cpu

   # Build for NVIDIA GPU support
   ./runner.sh build --cuda

2. Run Sassena
^^^^^^^^^^^^^^

Once built, you can run Sassena. The script automatically mounts your current directory to ``/data`` inside the container.

.. code-block:: bash

   # Simple run (implicit Sassena flags)
   ./runner.sh run --config scatter.xml

   # Run using MPI with 4 processes (explicit separation)
   ./runner.sh run --mpi -np 4 --sassena --config scatter.xml

3. Run Tests
^^^^^^^^^^^^

You can run the test suite to ensure everything is working correctly.

.. code-block:: bash

   # Run unit tests in Docker (default)
   ./runner.sh test --unit

   # Run all tests (including integration)
   ./runner.sh test --all

   # Run tests locally (requires build-local with tests enabled first)
   ./runner.sh build-local --cpu --tests
   ./runner.sh test --local --unit


Command Reference
-----------------

Build Options
^^^^^^^^^^^^^

* ``--cpu``: Build the standard CPU version (default).
* ``--cuda``: Build the version with CUDA support.
* ``--no-cache``: Force a complete rebuild of the Docker image.

Build-Local Options
^^^^^^^^^^^^^^^^^^^

When building locally without Docker:

* ``--cpu``: Build for CPU (default).
* ``--cuda``: Build for CUDA/GPU.
* ``--clean``: Delete the build directory before building (useful if fixing generator errors).
* ``--install-deps``: Attempt to install system dependencies (requires sudo).
* ``--tests``: Enable building the test suite (required for ``./runner.sh test --local``).


Run Options
^^^^^^^^^^^

The ``run`` command uses a flexible argument parser. You can switch between passing flags to the runner script, the MPI launcher, or the Sassena application using delimiters.

**Syntax:**

.. code-block:: bash

   ./runner.sh run [runner_flags] [--mpi <mpi_flags>] [--sassena <sassena_flags>]

**Runner Flags:**

* ``--use-cuda``: Use the CUDA-enabled Docker image.
* ``--data-dir DIR``: Local directory to mount (default: current directory).

**Delimiters:**

* ``--mpi``: All subsequent flags are passed to ``mpiexec`` (e.g., ``-np 4``, ``--allow-run-as-root``).
* ``--sassena``: All subsequent flags are passed to the ``sassena`` application (e.g., ``--config``).

**Note:** If no delimiters are used, the script defaults to "runner mode". Any flag not recognized as a runner flag (like ``--use-cuda``) is automatically treated as a Sassena flag.

Test Options
^^^^^^^^^^^^

The ``test`` command allows running the test suite in a CI-like Docker environment or locally.

* ``--unit``: Run unit tests only (default).
* ``--integration``: Run integration tests only.
* ``--all``: Run all tests.
* ``--use-cuda``: Use the CUDA-enabled CI image.
* ``--local``: Run tests on the host machine (requires ``build-local``).
* ``--build-dir DIR``: Specify a custom build directory for local tests.


Troubleshooting
---------------

**Permission Issues:**
If you encounter permission errors with output files, ensure your user ID inside the container matches your host user. The runner script attempts to handle this automatically.

**MPI Errors:**
If running in an environment that requires root privileges (like some CI pipelines), pass the flag within the MPI section:

.. code-block:: bash

   ./runner.sh run --mpi -np 4 --allow-run-as-root --sassena --config scatter.xml