CI Pipeline
===========

Sassena uses GitLab CI/CD for automated building, testing, and deployment.
The pipeline is defined in ``.gitlab-ci.yml`` and consists of three stages:
build, test, and deploy.

Docker Containers
-----------------

Sassena uses Docker containers for both CI builds and VSCode dev containers.
Two container configurations are maintained:

* ``Dockerfile`` - CPU-only build environment (Ubuntu-based)
* ``.devcontainer/cuda/Dockerfile`` - CUDA-enabled development environment

Both containers include all dependencies required for building Sassena and
running the CI pipeline (Boost, Sphinx, Doxygen, etc.).

**Building and Updating Containers**

1. Authenticate with the GitLab container registry:

   .. code-block:: bash

      docker login registry.hzdr.de

   (Create a Personal Access Token in GitLab profile settings if needed)

2. Build the container image:

   .. code-block:: bash

      docker build -t registry.hzdr.de/daphne4nfdi/sassena .

   This will build the `Dockerfile` in the current directory and store it with
   the name ``registry.hzdr.de/daphne4nfdi/sassena``. If you have made changes to
   the docker container and want to push it to the GitLab container registry and therefore CI, simply use the command:

3. Push to the GitLab registry:
   .. code-block:: bash

      docker push registry.hzdr.de/daphne4nfdi/sassena


Pipeline Configuration
----------------------

The CI pipeline is defined by the file ``.gitlab-ci.yml``, which resides in the
root of the project. It is a YAML file and further information on its structure
can be found on the
`GitLab CI Documentation <https://docs.gitlab.com/ee/ci/>`_.

The file defines three main steps in the pipeline. Firstly, the project is
compiled at the pushed commit. This is done in exactly the same way as specified
in the README or User Guide section of the docs. Docs can also be built if the
user has Doxygen and Sphinx installed and passes the ``SASS_BUILD_DOCS=ON``
argument to CMake (see user guide for further information).

The test section of the pipeline runs unit and integration tests,
which could also be run locally if developer mode is enabled and the user runs
``ninja test`` (or similar if using ``make``) to run the ``test`` target. The
integration tests are simply ``scatter.xml`` files which live in the
``tests/waterdyn4/ci_configs`` directory and are compared to a known good
``signal.h5`` file on the CI using a Python script.

The final stage of the pipeline is the deployment step. For documentation, this
corresponds to copying the output of the docs from the build stage into a
specific directory for GitLab Pages. The deployment step also contains
a job which builds an AppImage of Sassena and uploads it to the "Releases"
section of the project using ``curl``.

AppImages are made using the utility `linuxdeploy
<https://github.com/meefik/linuxdeploy>`_, which is included in the Sassena
container. If you want to create your own AppImages locally, we recommend you
download and install linuxdeploy locally or use the existing one provided (e.g.
through VSCode's Dev Containers). AppImages are created according to the
`AppImage user
guide <https://docs.appimage.org/packaging-guide/from-source/native-binaries.html#cmake>`_
and then running linuxdeploy in the directory.