Advanced: How the build-system works


This section is not necessary for building, deploying or interacting with the platform. It provides a technical explanation of the steps performed by the build script.
For building the platform, refer to Build Kaapana.

Assuming the kaapana repository was cloned into the kaapana/ directory the build process is usually started by executing

python3 build-scripts/ -u <registriy_username> -p <registry_password>

inside kaapana/.


This document expects a basic knowledge of the following technologies

Configuration steps

At first step a path to the kaapana repository is determined. Then a config file is searched. The config file can be specified in the command line with the flag -c, --config <path-to-config-file>. If no config file was specified in the command line a file called build-config.yaml is searched in kaapana/build-scripts/ If this file is not present it will be created based on build-config-template.yaml and the build proccess exits with an error message.

Now all directories for external sources are checked if they are available. Directories for external sources can either be specified in the command line after the flag -es, --external-sources <list-of-external-source-directories> or in the config file as a comma-separated string for the key external_source_dirs.

Collecting available images and charts

Before the build process is initiated all available Dockerfiles are recursively collected from the kaapana repository directory and all directories specified as external sources. For each found Dockerfile an instance of the helper class Container is initialized. This step also checks if all required local images are present in the collection of images.


Local images

Not all images are pushed to the registry. If the Dockerfile contains the line LABEL REGISTRY="local-only" the image is build but not pushed to the specified registry. It is tagged as local-only/<image-name>:<version>.

In a similar manner the kaapana directory and all external source directories are scanned for Chart.yaml files. For each found file an instance of HelmChart is initialized and if existing the .tgz file is removed.

Generating deployment scripts

The next step is the creation of deployment scripts for each subdirectory of the kaapana/platforms/ directory. The deployment script for the kaapana-admin-chart for example can be found after a successful build at kaapana/build/kaapana-admin-chart/ It is based on kaapana/platforms/ and configured according to a config file e.g. kaapana/platforms/kaapana-admin-chart/deployment_config.yaml.


Platform charts

Currently there are two platforms build by default i.e. the admin-platform and the kaapana-platform. Each platform is entirely packaged as a single helm chart i.e. the kaapana-admin-chart and the kaapana-platform-chart. Platform charts are specified by the key-value pair kaapana_type: "platform" in the Chart.yaml file.

A filter can be applied in order to build only a subset of platform-charts e.g. only the kaapana-platform-chart. To do so use the command line flag -pf, --platform-filter <list-of-platform-chart-names> or adjust the value of platform_filter in the config file.

The actual build-proccess

The actual build-proccess consists of updating dependencies for helm charts, packaging and pushing helm charts and of tagging, building and pushing images. For each platform-chart that should be build the following steps are proccessed:

  1. A dependecy tree of helm charts is generated

  2. All helm charts in this tree are recursively packaged and the dependencies are updated, images associated with a chart are tagged in a uniform pattern

  3. The platform-chart is packaged and pushed.

  4. A list of images is generated in an order that allows to build them successively

  5. A deployment script is generated

  6. All images in the list generated in step 4 are build and all non-local images are pushed to the registry


Recursively proccessing charts

The basic component of step 2 is the static method build_platform(chart) of the HelmChart class. The method is first called for the platform-chart and then recursively for each chart it depends on. This way all charts of the dependency tree are proccessed in a depth-first approach. It updates dependencies, packages charts and tags images. (For special charts specified as collections also an image is build and pushed by this method.)



A collection can be identified with an image and a helm chart. In the scope of the build script a collection contains several charts as dependencies. The build scripts processes a collection by updating the dependencies for all charts and packaging all charts it depends on.



All packaged charts and all information regarding the build process like the log file or the dependecy trees are stored in kaapana/build/.