Installation and Updates

This page describes how to install Cadenza on Kubernetes using Helm and how to update existing deployments. Before following these instructions, ensure you have completed the configuration steps described in Configuration and Helm Values.

The installation and update process includes:

  • First installation with database schema preparation

  • Verifying the installation

  • Updating Cadenza to a new version with database migration

  • Configuration-only updates without version changes

Installing Cadenza

If the custom-values.yaml is prepared with the desired settings, deploy Cadenza to your Kubernetes cluster.

We will use my-cadenza and my-namespace as examples for release and namespace names throughout this document. You will have to use unique names per installation. For convenience, the following examples assume that your Kubernetes context is set to the my-namespace namespace. You can set the namespace context with: kubectl config set-context --current --namespace=my-namespace

First Installation: Database Schema Preparation

Before Cadenza can run for the first time, the required database schemas must be prepared. See Database Preparation for details on the required schemas.

  • Demo Mode: In demo mode, the Helm chart uses H2 databases that are automatically created and initialized. H2 databases are not suitable for production use and not suitable for multi-node operation.

  • Production Mode: For production deployments, you must use the integrated Database Migration Tool to initialize PostgreSQL database schemas.

For production deployments, the Database Migration Tool runs as a Kubernetes Job and can be activated using the Helm value cadenza.migrate.enabled=true.

Step 1: Run the database migration Job

helm install my-cadenza oci://registry-ext.disy.net/cadenza-helm/cadenza \
  --version 10.4.x \
  -f custom-values.yaml \
  --set cadenza.migrate.enabled=true \
  --wait --wait-for-jobs

This creates a Kubernetes Job that initializes the database schemas. The --wait --wait-for-jobs flags ensure that the command waits until the migration Job has completed.

Step 2: Check the migration Job logs

After the migration Job has completed, verify the logs to ensure it ran successfully:

kubectl logs job/my-cadenza-cadenza-migrate

Step 3: Install Cadenza

After the migration Job has completed successfully, install Cadenza without the migration flag:

helm upgrade my-cadenza oci://registry-ext.disy.net/cadenza-helm/cadenza \
  --version 10.4.x \
  -f custom-values.yaml

Verifying the Installation

After running the helm install command, Helm will display a summary showing the release name, namespace, deployment status, and revision number. However, a successful Helm installation only means that the chart was processed correctly and that the resources on Kubernetes could be created successfully. The Cadenza pods may still be initializing and not yet ready to serve requests.

Check Pod Status

First, verify that the Cadenza pod is running:

kubectl get pods

You should see output similar to this:

NAME                                READY   STATUS    RESTARTS   AGE
cadenza-5d4c8b9f7-abc12             1/1     Running   0          2m

The Cadenza pod should show STATUS: Running and READY: 1/1.

Check Deployment Status

After the pod is ready, verify that the Cadenza deployment itself is in a ready state:

kubectl get deployment

You should see output similar to this:

NAME       READY   UP-TO-DATE   AVAILABLE   AGE
cadenza    1/1     1            1           5m

The deployment is ready when the READY column shows 1/1.

Access Cadenza via Ingress

If you enabled Ingress creation in your Helm values, Cadenza should now be accessible via the configured Ingress host in your browser. Open your browser and navigate to the URL you specified in your Ingress configuration (e.g., https://my-cadenza.example.com/cadenza).

If you encounter issues during installation or startup, refer to Troubleshooting for common problems and solutions.

Updating Cadenza

Helm’s upgrade mechanism can be used to update Cadenza to a new version or to make changes to the deployment configuration. Changes to the installation-specific custom-values.yaml can thus be implemented without a new installation. We strongly encourage using the compare view in the Helm chart documentation to review changes in the default values between chart versions.

Database Schema Migration for Updates

Database schema migration must be performed for all Cadenza updates, including both major version updates and patch version updates.

During the database migration process, Cadenza must be completely stopped. This means no Cadenza pods may be running that could access the database schemas.

Update Process

Follow this process to update Cadenza to a new version:

Step 1: Update Helm values

Edit your custom-values.yaml file to specify the new Cadenza version:

cadenza:
  image:
    tag: "10.4.x-release"  # Update to new patch version

Step 2: Review and apply configuration changes

Review the Cadenza release notes for your target version and make any necessary configuration changes in your custom-values.yaml file. The release notes document required and recommended configuration changes.

Step 3: Run Helm upgrade with database migration

Execute the Helm upgrade with the migration enabled. This will stop the Cadenza deployment and run the database migration Job:

helm upgrade my-cadenza oci://registry-ext.disy.net/cadenza-helm/cadenza \
  --version 10.4.x \
  -f custom-values.yaml \
  --set cadenza.migrate.enabled=true \
  --wait --wait-for-jobs

This command will scale down the Cadenza deployment to zero replicas and create a migration Job. The --wait --wait-for-jobs flags ensure that the command waits until the migration Job has completed.

Step 4: Check the migration Job logs

After the migration Job has completed, verify the logs to ensure it ran successfully:

kubectl logs job/my-cadenza-cadenza-migrate

Step 5: Upgrade the Cadenza deployment

After the migration Job has completed successfully, upgrade Cadenza to start the deployment with the new version:

helm upgrade my-cadenza oci://registry-ext.disy.net/cadenza-helm/cadenza \
  --version 10.4.x \
  -f custom-values.yaml

This will deploy Cadenza with the new version and updated configuration.

Configuration Updates Without Version Change

If you only need to update the configuration without changing the Cadenza version, you can use a simplified update process without database migration:

helm upgrade my-cadenza oci://registry-ext.disy.net/cadenza-helm/cadenza \
  --version 10.4.x \
  -f custom-values.yaml