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

Authenticate with the GitLab container registry:
```
docker login registry.hzdr.de
```
(Create a Personal Access Token in GitLab profile settings if needed)
Build the container image:
```
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:
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.

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, 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 and then running linuxdeploy in the directory.