Build Kaapana

It is important to note that the building of Kaapana (including the cloning of the repository etc.) is completely separated from the actual installation / deployment of the platform. Building the repository, which is described in this chapter, refers to the creation of the required containers and Helm Charts needed for an installation. The results of this build (containers and charts) are usually pushed into a registry and downloaded from there for the installation on the actual deployment server (where the platform will be running).

Important

1) Do you really need to build the project?
Only build the project if you don’t have access to an existing registry containing the Kaapana binaries or if you want to setup your own infrastructure. Registry access can be requested from the DKFZ Kaapana Team via Slack.

2) You don’t need to build the repository on the deployment server!
A typical misconception we often hear is that you need to clone the repository on the deployment server and build it there. That is not the case! The repository can be built on a completely different machine and the results then made available via a registry. Practically, it is even recommended to separate the repository and the deployment server. Of course it is possible to build the repository on the deployment server (and there is also the possibility to work completely without a registry) - but this should be done in rather rare cases.

Build Requirements

Perform these steps on the build machine. The recommended build system is Ubuntu 24.04 (x64). Kaapana can only be built and run on x64 systems. Building on other operating systems or architectures has not been tested and may lead to unexpected issues, for which no official support is provided.

Important

Disk space needed:
For the complete build of the project ~90GB (~110GB including build cache) of container images will be stored at /var/snap/docker/common/var-lib-docker.
When creating offline installation tarball, ~80GB additional disk space is needed.

Before you get started you should be familiar with the basic concepts and components of Kaapana (see What is Kaapana?). You should also have the following packages installed on your build-system.

Dependencies

sudo apt update && sudo apt install -y nano curl git python3 python3-pip
Clone the repository:

git clone -b master https://github.com/kaapana/kaapana.git
Python requirements

python3 -m pip install -r kaapana/build-scripts/requirements.txt
Tip

Use a virtual environment for installing Python dependencies.

This is a recommended best practice.

On Ubuntu 24.04 and similar distributions, due to changes in Python packaging (see PEP 668), installing packages with pip outside of a virtual environment may result in errors or warnings.

To avoid issues, create and activate a virtual environment before running the requirements installation:
Recommended for beginners!

Creation step (only needed once):
# Install the 'venv' package if not already installed sudo apt install -y python3-venv # Create the virtual environment (only needed once) python3 -m venv kaapana/.venv
Activation step (needed each time you use the Python code):
# Activate the virtual environment source kaapana/.venv/bin/activate
Then install the Python requirements.
Installation step (only needed once):
# Install pipenv pip install pipenv # Create and activate the environment (only needed once) pipenv install
Activation step (needed each time you use the Python code):
# Activate the environment pipenv shell
Then install the Python requirements.
Installation step (only needed once):
# Install Poetry pip install poetry # Create and activate the environment (only needed once) poetry install
Activation step (needed each time you use the Python code):
# Activate the environment poetry shell
Then install the Python requirements.
Licensing Notice: Anaconda has licensing restrictions for commercial use. For details, refer to the Anaconda Terms of Service.

Conda can be installed in various ways, and it’s important to research the best option for your needs to ensure compliance with the relevant licensing terms.

If you have Conda installed, you can create and activate a Conda environment and then proceed to install the Python requirements.

Creation step (only needed once):
# Create a Conda environment (only needed once) conda create -n kaapana python=3.x
Activation step (needed each time you use the Python code):
# Activate the Conda environment conda activate kaapana
Then install the Python requirements
Snap

Check if snap is already installed: snap help --all

If not run the following commands:

sudo apt install -y snapd

A reboot is needed afterwards!
Docker

sudo snap install docker --classic --channel=latest/stable
In order to execute docker commands as non-root user you need to execute the following steps:

sudo groupadd docker

sudo usermod -aG docker $USER

For more information visit the Docker docs
Helm

sudo snap install helm --classic --channel=latest/stable
Reboot

sudo reboot
Test Docker

docker run hello-world

-> this should work now without root privileges
Helm plugin

helm plugin install --verify=false https://github.com/instrumenta/helm-kubeval

Start Build

We recommend building the project using a registry. If you do not have access to an established registry, we recommend using Gitlab, which provides a cost-free option to use a private container registry.

python3 build-scripts/cli.py --default-registry <registry-url> registry-username --registry-pw <registry-password>

Note

If the username and password are not working, you may need to use an access token instead.
Ensure that the username/access token does not contain spaces.

Not recommended.
If a private registry is not available, it is possible to setup a local registry.
This may be helpful for one-time show-casing, testing, developing, or if there are any issues with connection to the remote registry.
This solution is only persistent while the docker container containing the registry is running. It also works only locally and cannot be distributed.
For building with a local registry, you need to set up a local Docker registry with basic authentication with following steps:

Create credentials (replace <registry user> and <registry password>):

mkdir auth
docker run --entrypoint htpasswd httpd:2.4.58 -Bbn <registry user> <registry password> > auth/htpasswd

Start the Docker registry with basic authentication:

docker run -d -p 5000:5000 --restart unless-stopped --name registry -v "$(pwd)"/auth:/auth -e "REGISTRY_AUTH=htpasswd" -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd registry:2.8.3

Configure build_config.yaml:

python3 build-scripts/cli.py --registry-username <registry user> --registry-password <registry password> --default-registry "localhost:5000"

Not recommended.
In case platfrom should be deployed in the machine without internet access (i.e. offline),
installation files, containers and helm charts need to be pre-build on the server
with internet access and copied on the server, where requirements can be installed and platfrom deployed.
This configuration creates an image tarball and offline microk8s installer

python3 build-scripts/cli.py --build-only --create-offline-installation --default-registry offline

Installer will be available in kaapana/build/microk8s-offline-installer

Tarball will be available in kaapana/build/kaapana-admin-chart/kaapana-admin-chart-<version>-images.tar

This takes usually (depending on your hardware) around 1h. You can find the build-logs and results at ./kaapana/build

Hint

You can also set parameters as environment variables or store them in a .env file in your working directory. For a full list of all options execute python3 build-scripts/cli --help

The next step will explain how to install the Kubernetes cluster via the kaapanactl.sh script.