Skip to content

K3s Manual Install Checklist

This checklist is to assist with the steps for installing IVAAP on a single server VM host running K3s, in the case that you want to install manually without using ivaap install. For the standard, fully automated installation process, please refer to the K3s Single Node Installation Guide instead.

Info

This guide was written in the context of using base64 encoded secrets in the deployment configuration YAML. This is, however, optional.

This guide assumes the VM has already been provisioned and meets the requirements outlined in the Technical Datasheet. This checklist also assumes deployment on a Debian based VM (Ubuntu 24.04, in this case). These commands will vary for other distribution types.

Starting with IVAAP 2026.1, the delivery is a unified zip from the SLB Software Download Center containing a single self-extracting ivaap binary. The binary embeds the Helm chart, all container images (core + datanode connectors), the database schema, ivaap-helpers, and the documentation zip. For this manual checklist, the binary is used only to extract the payload to disk — every subsequent step (image load, postgres deploy, secret generation, helm upgrade) is performed manually so the operator stays in control. In this guide we will be adding the geofiles datanode connectors (geofilesmasternode, geofilesseismicnode, geofilesreservoirsnode) on top of the base deployment. Connector selection will vary by license, but the process is identical.

Basic Environment Setup

  • Update the host 

    sudo apt-get update && sudo apt-get upgrade -y

  • Install Java and JQ - Java nor JQ are hard requirments, however, they are needed for some of the scripts in ivaap-helpers. 

    sudo apt-get update && sudo apt-get upgrade -y && sudo apt-get install -y openjdk-21-jdk jq && sudo reboot now

  • Install K3s per official documentation for your distribution: Requirements | K3s

    • For Ubuntu, this quick script should handle the install. If there are errors in your environment, please refer back to k3s official documentation. Please ensure to run this script as the user you intend to deploy and manage IVAAP with, as this script will configure appropriate user permissions for K3s. This is not meant to be run as root. root should never be used to manage your IVAAP deployment. 
      #!/bin/bash

# Install k3s
curl -sfL https://get.k3s.io | sudo sh -

# Checks nodes are available as root
sudo k3s kubectl get nodes

# Create local kube config
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
echo 'export KUBECONFIG=$HOME/.kube/config' >> ~/.bashrc

# Checks nodes are available as $user
k3s kubectl get nodes

  • Install Helm 

    curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | sudo bash -s -

IVAAP Installation

  • Make a new directory /opt/ivaap, and change ownership to your user. 

    sudo mkdir /opt/ivaap && sudo chown $USER:$USER /opt/ivaap

  • Extract the embedded payload into /opt/ivaap using the ivaap binary from the unzipped delivery. This streams the embedded tar directly to disk without launching the guided installer: 

    chmod +x ./ivaap
./ivaap extract-payload --dest /opt/ivaap

After extraction, /opt/ivaap contains:

Path Contents
IVAAPHelmTemplate/ Helm chart — Chart.yaml, values.yaml, templates/, deployment-examples/, collect-image-list.sh
ivaap-helpers/ aliases/, scripts/ (including circle-of-trust.sh, encrypt_ivaap_passwd.sh, ivaap-helm-template/deploy-k3s-postgres.sh), image-retagging/
connectors/ Individual .tar.gz image archives for every licensed datanode + scheduled task
docker-images.tar.gz Core image archive — proxy, ActiveMQ, frontend, adminserver, and all coreNodes backend images
ivaap-postgres-2026-06-01.sql Starting database schema for Zalando PostgreSQL
IVAAP_Documentation_*.zip Bundled documentation site
package-metadata.json Build metadata — package name, chart version, Helm chart commit

The ivaap binary itself is not required for any of the steps below — once the payload is extracted, the remaining work is kubectl, helm, and the bundled helper scripts. You can keep the unzipped delivery in your home directory for re-extraction or future upgrades.

  • Add ivaap-helpers aliases and functions to ~/.bashrc 

    echo "source /opt/ivaap/ivaap-helpers/aliases/ivaap_k8s_aliases.sh" >> ~/.bashrc
source ~/.bashrc

  • Prepare the /opt/ivaap/ivaap-volumes directory with proper permissions.

Warning

Ownership of all sub-directories within the logs directory (with the exception of proxy) must be set to UID 1000 to match the UID inside the pods.

##!/bin/bash

echo 'Creating log directories'
sudo mkdir -p /opt/ivaap/ivaap-volumes/logs/{activemq,adminserver,backend,proxy,scheduledtasks}

echo 'Modifying ivaap-volumes dir permissions'
sudo chown $(id -u):$(id -g) /opt/ivaap/ivaap-volumes

echo 'Modifying logs dirs permissions'
sudo chown -R 1000:1000 /opt/ivaap/ivaap-volumes/logs

echo 'Modifying proxy logs dir permissions'
sudo chown -R 101:101 /opt/ivaap/ivaap-volumes/logs/proxy

Verification: 

find /opt/ivaap/ivaap-volumes/ -type d -exec ls -ldn {} \; | column -t

Awaited output: 

drwxr-xr-x  3  1000  1000  4096  Nov  7  16:01  /opt/ivaap/ivaap-volumes/
drwxr-xr-x  7  1000  1000  4096  Nov  7  16:07  /opt/ivaap/ivaap-volumes/logs
drwxr-xr-x  2  1000  1000  4096  Nov  7  16:07  /opt/ivaap/ivaap-volumes/logs/activemq
drwxr-xr-x  2  101   101   4096  Nov  7  16:07  /opt/ivaap/ivaap-volumes/logs/proxy
drwxr-xr-x  2  1000  1000  4096  Nov  7  16:07  /opt/ivaap/ivaap-volumes/logs/scheduledtasks
drwxr-xr-x  2  1000  1000  4096  Nov  7  16:07  /opt/ivaap/ivaap-volumes/logs/adminserver
drwxr-xr-x  2  1000  1000  4096  Nov  7  16:07  /opt/ivaap/ivaap-volumes/logs/backend

  • Create the ivaap namespace. This can be anything you choose, but it will need to be reflected later in the deployment yaml. For this checklist, we will choose ivaap for the namespace. 

    kubectl create namespace ivaap

  • Load the core container images into k3s. docker-images.tar.gz contains the proxy, ActiveMQ, frontend, adminserver, and every backend core node image (seednode, adminnode, playnode, epsgnode, mqgatewaynode, messagingnode, dataimportnode). 

    sudo k3s ctr images import /opt/ivaap/docker-images.tar.gz
    NB: sudo needed due to the rights on the /run/k3s/containerd/containerd.sock socket.

Datanode connector images live as individual .tar.gz files under /opt/ivaap/connectors/. Only load the connectors entitled by your license. In this guide we deploy geofiles, which is sharded across three datanodes: 

sudo k3s ctr images import /opt/ivaap/connectors/geofilesmasternode-3.1-9.tar.gz
sudo k3s ctr images import /opt/ivaap/connectors/geofilesseismicnode-3.1-9.tar.gz
sudo k3s ctr images import /opt/ivaap/connectors/geofilesreservoirsnode-3.1-9.tar.gz

Loading all connectors at once

To load every bundled connector (useful for evaluation deployments), iterate the directory: 

for f in /opt/ivaap/connectors/*.tar.gz; do
  sudo k3s ctr images import "$f"
done
Connector image filenames carry the version embedded by the build (e.g. geofilesmasternode-3.1-9.tar.gz); check package-metadata.json and /opt/ivaap/IVAAPHelmTemplate/values.yaml if you need exact tags for cross-referencing.

  • Deploy Zalando PostgreSQL Operator. Optionally, PostgreSQL can be install directly on the host if this method is prefered. Refer to the Database Administration guide for more details.

Note

The deploy-k3s-postgres.sh script requires user input for the full path of the provided, starting dump.sql file. Collect and copy this full path first before running the script.

# Collect the full path of the dump file before proceeding (filename varies by build date)
readlink -f /opt/ivaap/ivaap-postgres-*.sql
/opt/ivaap/ivaap-postgres-2026-06-01.sql

# Run the ivaap-helpers script to deploy Zalando Postgres
/opt/ivaap/ivaap-helpers/scripts/ivaap-helm-template/deploy-k3s-postgres.sh

This script will install Zalando PostgreSQL Operator. This is intended for use with IVAAP K3s single server VM deployments only.
Ensure that K3s is installed and running, and that /opt/ivaap/ivaap-volumes directory has been created.
The script will require user input of the full path to the provided database schema to load.
get IVAAP running on your system. Please refer the IVAAP Deployment Operations Guide for full deployment steps.


Proceed with Zalando Operator installation? (y/n) y
Enter full path for postgres dump to load into the database: /opt/ivaap/ivaap-postgres-2026-06-01.sql
Ensure there are no errors in the schema loading process. The helper script installs the Zalando operator into the default namespace and creates a cluster named ivaap-postgres-cluster — the IVAAP_SERVER_ADMIN_DATABASE_HOST value later in this checklist reflects this placement.

  • Copy k3s custom template to begin configuration. This file can be any name of your chooising, but in this checklist, we will keep it simple with the name ivaap.values.yaml. This file will be where your deployment specific IVAAP configuration will live. 
    cp /opt/ivaap/IVAAPHelmTemplate/deployment-examples/deploy-with-two-values-files/example-k3s-native-secrets.yaml /opt/ivaap/ivaap.values.yaml
    This deployment example deploys a basic, local authentication version of IVAAP with the geofiles connector. More connectors can be added depending on what was provided in your package. It is important to note that it is not required to use this example file as a starting template. Alternatively, the primary values.yaml file in the IVAAP Helm Template can also be copied as a starting point, and things can be stripped out or added as needed.

Basic Configuration

  • .Values.environment.hostname - set to the DNS name of your deployment, without hypertext protocol. Ex: ivaap.slb.com
  • .Values.geofiles.localGeofilesPath - This should point to the location of your geofiles data on the file system. We recommend keeping all volumes in the ivaap-volumes directory for easy reference to any persisted data, but this could also point to any localtion you choose.
  • .Values.configmap.adminserver.IVAAP_SERVER_ADMIN_AUTO_MIGRATE - This value should be set to true for initilization of first time deployment. This will do necessary database migrations required for your specific version of IVAAP. Once migrations have been applied, this envar should be set to false for safety.

Secrets

All secrets in this section will need to be base64 encoded. This can be done easily with the following command: 

echo -n "<secret_value>" | base64 -w 0
As an example: 
# Encode the secret
user@linux:~$ echo -n "myNewSecret" | base64 -w 0
bXlOZXdTZWNyZXQK

# Decode a secret
user@linux:~$ echo "bXlOZXdTZWNyZXQK" | base64 -d
myNewSecret
It is important to use the -n option for echo to remove the possiblity of new line characters being added to the encoded value.

Please be mindful of newline handling when encoding secrets. Alternatively, there are online resources that can also help to encode/decode values for you without using CLI syntax.

Circle of Trust

  • .Values.secrets.type.k8sSecrets.circle-of-trust-secrets.* - there are default values configured in this file as an example, but it is strongly recommended to generate your own Circle of Trust secrets per deployment. This can be done with the ivaap-helpers script /opt/ivaap/ivaap-helpers/scripts/circle-of-trust.sh Once new values are generated, base64 encode the values and set for the corresponding secrets in ivaap.values.yaml

ActiveMQ PW

  • .Values.secrets.type.k8sSecrets.activemq-conf-secrets.IVAAP_WS_MQ_QUEUE_PASSWORD For more information, refer to the Updating ActiveMQ Password section of the operations guide.

License

  • .Values.secrets.type.k8sSecrets.ivaap-license-secret.LM_LICENSE_FILE

Starting with IVAAP 2026.1, LM_LICENSE_FILE is a FlexNet port@host reference to a running SLB FlexNet license server, not raw FEATURE-line content. The adminserver and backend nodes check out feature entitlements from the FlexNet server at runtime. The license server must already be running and reachable from the IVAAP pods before deployment.

# Plain text form (.Values.secrets.base64EncodedValues: false)
LM_LICENSE_FILE: '27000@your-flex-server.example.com'

If you are using the base64-encoded form of secrets, encode the entire port@host string with -n to avoid a trailing newline: 

user@linux:/opt/ivaap/$ echo -n "27000@your-flex-server.example.com" | base64 -w 0 && echo
MjcwMDBAeW91ci1mbGV4LXNlcnZlci5leGFtcGxlLmNvbQ==

Always use echo -n

Without -n, a trailing newline is included in the encoded value and the license check will fail at deployment time. The same applies to every other base64-encoded secret in this guide.

License server placement

SLB recommends running the FlexNet license server on a separate host (your corporate FlexNet server or a dedicated VM). The host portion of port@host should resolve from inside the cluster — use a real DNS name or add a hostAlias to the backend pods. Loopback values (127.0.0.1, localhost, ::1) do not work directly because each pod's loopback is its own network namespace; in that scenario ivaap install injects a synthetic pod-facing hostname (e.g. ivaap-flexnet.local) and writes it into the backend hostAlias. For manual installs against a loopback license server, replicate that pattern by hand: set LM_LICENSE_FILE to <port>@ivaap-flexnet.local and add .Values.ivaapBackendNodes.hostAlias pointing that name at the k3s host IP.

For more information on the FlexNet integration, refer to the Final Commercial License section of the operations guide.

Database Connection Details

  • .Values.secrets.type.k8sSecrets.adminserver-conf-secrets.* 
    secrets:
  type:
    k8sSecrets:
      adminserver-conf-secrets:
        # ----- PostgreSQL DB Connection Configuration
        IVAAP_SERVER_ADMIN_DATABASE_HOST: "aXZhYXAtcG9zdGdyZXMtaG9zdA=="
        IVAAP_SERVER_ADMIN_DATABASE_NAME: "aXZhYXBkYg=="
        IVAAP_SERVER_ADMIN_DATABASE_PORT: "NTQzMg=="
        IVAAP_SERVER_ADMIN_DATABASE_USERNAME: "aXZhYXBzZXJ2ZXI="
        IVAAP_SERVER_ADMIN_DATABASE_ENCRYPTION_KEY: "ZGJFbmNyeXB0aW9uS2V5"
        IVAAP_SERVER_ADMIN_DATABASE_ENCRYPTED_PASSWORD: "ZW5jcnlwdGVkLWRiLXBhc3N3b3Jk"

Info

All values below assume installation of Zalando operator using the ivaap-helpers script. Rember - in this guide example, all secrets are base64 encoded.

  • IVAAP_SERVER_ADMIN_DATABASE_HOST = ivaap-postgres-cluster.default.svc.cluster.local
  • IVAAP_SERVER_ADMIN_DATABASE_NAME = ivaapdb
  • IVAAP_SERVER_ADMIN_DATABASE_PORT = 5432
  • IVAAP_SERVER_ADMIN_DATABASE_USERNAME = ivaapserver
  • IVAAP_SERVER_ADMIN_DATABASE_ENCRYPTION_KEY = Encryption key used to encrypt the password - Encryption steps below
  • IVAAP_SERVER_ADMIN_DATABASE_ENCRYPTED_PASSWORD = Encrypted password - Encryption steps below

Encrypt Database Password

Zalando Postgres auto-generates a password for the ivaapserver user. The database password can be retrieved by running the following command: 

# Input command
kubectl get secret ivaapserver.ivaap-postgres-cluster.credentials.postgresql.acid.zalan.do -n default -o jsonpath='{.data.password}' | base64 -d && echo

# Output
KZYuNL31HDWccCAeE5MEeiEeaghRItIQfz7rA9wphwLsZ97t6tBYwV8UwEDG5pbi

This password will now need to be encrypted using IVAAP's built in java encryption system. This can be done with the ivaap-helpers script /opt/ivaap/ivaap-helpers/scripts/encrypt_ivaap_passwd.sh 

user@linux:/opt/ivaap/ivaap-helpers/scripts$ ./encrypt_ivaap_passwd.sh
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Encryption Key to use to encrypt plain text for IVAAP backend: [uhwcuOAkLNTBJrzMrKpwwllgBKGhSpeEuDbDicUC]
myEncryptionKey
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Plain text value to encrypt for IVAAP backend:
KZYuNL31HDWccCAeE5MEeiEeaghRItIQfz7rA9wphwLsZ97t6tBYwV8UwEDG5pbi
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

ORIGINAL PASSWORD  : KZYuNL31HDWccCAeE5MEeiEeaghRItIQfz7rA9wphwLsZ97t6tBYwV8UwEDG5pbi
ENCRYPTION KEY     : myEncryptionKey
ENCRYPTED PASSWORD : 2erEqGfW+Lno5q3Q+3xO3A46ej5eFFUhVU3Ad7Grw40VLCMULTFn/8HAIVdXveR5SjMaqQ8V80Sgsx60c6RSsGPsdMAm5AGUFNYuRaB/SI4=

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Now, these values still need to be base64 encoded, then set for IVAAP_SERVER_ADMIN_DATABASE_ENCRYPTION_KEY and IVAAP_SERVER_ADMIN_DATABASE_ENCRYPTED_PASSWORD.

If you are unable to, or choose not to install java on the host, there is an alternative method for encrypting this database password. There is an ivaap-helpers function called encryptZalandoPGPassword. This function requires IVAAP to already be running, as it uses the adminserver pod to encrypt the password. IVAAP-Helpers 

# Syntax
user@linux:~$ encryptZalandoPGPassword
Error: Namespace argument is required.
Usage: encryptZalandoPGPassword <ivaap-namespace>

user@linux:~$ encryptZalandoPGPassword ivaap
Enter your desired encryption key for encrypting the password: my.Encryption.Key
Encrypting VWwSsvrg9oYN95GckxsoqrcFYHJ3kqJxXp9BsL6IcdMqkusKOxxqSmU3ZQcjdXrW ...
b3oRF4XO6iYyrFDWb47BOvvoU3uF+vEGsv+0UldbKCpPnmld/hdGc2/oeAjz1HUAw02szGBu4Q6WQ+RNgXIrAOsV2QpGIV67hvMwrH6RrTs=

Once encrypted, these values still need to be base64 encoded, then set for IVAAP_SERVER_ADMIN_DATABASE_ENCRYPTION_KEY and IVAAP_SERVER_ADMIN_DATABASE_ENCRYPTED_PASSWORD, and the adminserver pod will need to be recreated before the changes take effect.

TLS Secret

  • .Values.environment.TLSSecret.secretName In our example file, the TLS secret name is ivaap-tls-secret. This can be set to whatever name you choose. Before deploying, create the secret with the following kubectl command: 
    kubectl create -n ivaap secret tls <secretName> \
  --cert=path/to/cert.crt \
  --key=path/to/private.key

If your certificate is self-signed, additional steps may be required to add the root CA to the JVM keystore for backend components. Refer to Adding Self Signed Root CA to Java Keystore for steps on this process.

Deploy IVAAP

It's now time to deploy IVAAP.

helm upgrade --install ivaap /opt/ivaap/IVAAPHelmTemplate \
    -f /opt/ivaap/IVAAPHelmTemplate/values.yaml \
    -f /opt/ivaap/ivaap.values.yaml \
    --namespace <namespace>

Example: 

user@linux:/opt/ivaap/IVAAPHelmTemplate$ helm upgrade --install ivaap /opt/ivaap/IVAAPHelmTemplate \
    -f /opt/ivaap/IVAAPHelmTemplate/values.yaml \
    -f /opt/ivaap/ivaap.values.yaml \
    --namespace ivaap
Release "ivaap" has been upgraded. Happy Helming!
NAME: ivaap
LAST DEPLOYED: Wed Jun 10 12:25:09 2026
NAMESPACE: ivaap
STATUS: deployed
REVISION: 2
TEST SUITE: None

user@linux:/opt/ivaap/IVAAPHelmTemplate$ kubectl -n ivaap get pods
NAME                                                  READY   STATUS    RESTARTS   AGE
adminserver-deployment-6b4bfb4497-cxk6x               1/1     Running   0          6m17s
ivaap-activemq-deployment-6b6956684f-rwhp6            1/1     Running   0          6m17s
ivaap-admin-deployment-57669dd46d-6s8hz               1/1     Running   0          6m17s
ivaap-backend-deployment-7bf8c78445-4lbdp             10/10   Running   0          6m17s
ivaap-dashboard-deployment-96b65978f-d5vdk            1/1     Running   0          6m17s
ivaap-dashboard-publish-deployment-6bc4d97ddf-52drd   1/1     Running   0          6m17s
ivaap-proxy-deployment-cb8ff766b-wh44c                1/1     Running   0          6m17s

The ivaap-backend-deployment runs the IVAAP core nodes (seednode, adminnode, playnode, epsgnode, mqgatewaynode, messagingnode, dataimportnode) plus every enabled datanode as containers in a single pod. The READY column reports <running>/<total containers> for that pod — 10/10 here is 7 core nodes + 3 geofiles datanodes. Your container count will differ based on which connectors you enabled.