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 the automated installation script. 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.

IVAAP will be provided with multiple packages, but usually there will be a single base package that contains all components necessary to run IVAAP, as well as separate, individual image tar files for the backend datanode connectors. In this guide, the base package will be 2025.1.1_BASE_IVAAPHelmTemplate_Chart-v1.1.8-2025-11-18.tar.gz, and we will be adding geofiles datanode connectors that will be loaded from a separate tar file. These package names and datanode connectors could vary for your specific scenario, but the ideas and processes are the same.

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

Decompress the IVAAP package into /opt/ivaap

sudo tar xvf 2025.1.*_IVAAPHelmTemplate_Chart*.tar.gz -C /opt/ivaap --strip-components=1

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 container images into k3s
```
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.

Don't forget to also load the backend datanode connector images. Remember, no datanode connectors will be provided in the base IVAAP package - these will always be provided as separate tar files. In our case, we will be deploying geofiles, which is comprised of three sharded nodes (meaning three separate images will need to be loaded).

sudo k3s ctr images import /path/to/geofilesmasternode-3.0-7.tar.gz
sudo k3s ctr images import /path/to/geofilesseismicnode-3.0-7.tar.gz
sudo k3s ctr images import /path/to/geofilesreservoirsnode-3.0-7.tar.gz

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
readlink -f /opt/ivaap/ivaap-postgres-2024.1-2024-12-06.sql
/opt/ivaap/ivaap-postgres-2024.1-2024-12-06.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 2025.1+ 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-2024.1-2024-12-06.sql

Ensure there are no errors in the schema loading process.

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.

It is also important to note that sometimes quotation matters. when encoding/decoding a secret. For example, if we use the above syntax to encode a license using double quotes for the echo command, the encoded value of the license will lose it's double quotes within the actual license itself:

# Encoding the license
user@linux:~$ echo -n "{{{FEATURE IVAAPServer INTD 1.0 9-oct-2025 uncounted VENDOR_STRING=users:16 HOSTID=ANY SIGN="022B 6B4F 7G92 85AB asdf 4AB1 142S 4524 BB2B 3EEF 0001 1BDD D69C A8FC asdf 6208 9CFC B54C CF12 F252 77E1"}}}" | base64 -w 0
e3t7RkVBVFVSRSBJVkFBUFNlcnZlciBJTlREIDEuMCA5LW9jdC0yMDI1IHVuY291bnRlZCBWRU5ET1JfU1RSSU5HPXVzZXJzOjE2IEhPU1RJRD1BTlkgU0lHTj0wMjJCIDZCNEYgN0c5MiA4NUFCIGFzZGYgNEFCMSAxNDJTIDQ1MjQgQkIyQiAzRUVGIDAwMDEgMUJERCBENjlDIEE4RkMgYXNkZiA2MjA4IDlDRkMgQjU0QyBDRjEyIEYyNTIgNzdFMX19fQo=

# Decoding the license
user@linux:~$ echo "e3t7RkVBVFVSRSBJVkFBUFNlcnZlciBJTlREIDEuMCA5LW9jdC0yMDI1IHVuY291bnRlZCBWRU5ET1JfU1RSSU5HPXVzZXJzOjE2IEhPU1RJRD1BTlkgU0lHTj0wMjJCIDZCNEYgN0c5MiA4NUFCIGFzZGYgNEFCMSAxNDJTIDQ1MjQgQkIyQiAzRUVGIDAwMDEgMUJERCBENjlDIEE4RkMgYXNkZiA2MjA4IDlDRkMgQjU0QyBDRjEyIEYyNTIgNzdFMX19fQo=" | base64 -d
{{{FEATURE IVAAPServer INTD 1.0 9-oct-2025 uncounted VENDOR_STRING=users:16 HOSTID=ANY SIGN=022B 6B4F 7G92 85AB asdf 4AB1 142S 4524 BB2B 3EEF 0001 1BDD D69C A8FC asdf 6208 9CFC B54C CF12 F252 77E1}}}

# Notice in the decoded license, the hashed value within the license is no longer in quotes
# Instead, we can wrap the entire license in single quotes '' for the echo command to avoid this issue:
user@linux:~$ echo -n '{{{FEATURE IVAAPServer INTD 1.0 9-oct-2025 uncounted VENDOR_STRING=users:16 HOSTID=ANY SIGN="022B 6B4F 7G92 85AB asdf 4AB1 142S 4524 BB2B 3EEF 0001 1BDD D69C A8FC asdf 6208 9CFC B54C CF12 F252 77E1"}}}' | base64 -w 0
e3t7RkVBVFVSRSBJVkFBUFNlcnZlciBJTlREIDEuMCA5LW9jdC0yMDI1IHVuY291bnRlZCBWRU5ET1JfU1RSSU5HPXVzZXJzOjE2IEhPU1RJRD1BTlkgU0lHTj0iMDIyQiA2QjRGIDdHOTIgODVBQiBhc2RmIDRBQjEgMTQyUyA0NTI0IEJCMkIgM0VFRiAwMDAxIDFCREQgRDY5QyBBOEZDIGFzZGYgNjIwOCA5Q0ZDIEI1NEMgQ0YxMiBGMjUyIDc3RTEifX19Cg==

user@linux:~$ echo "e3t7RkVBVFVSRSBJVkFBUFNlcnZlciBJTlREIDEuMCA5LW9jdC0yMDI1IHVuY291bnRlZCBWRU5ET1JfU1RSSU5HPXVzZXJzOjE2IEhPU1RJRD1BTlkgU0lHTj0iMDIyQiA2QjRGIDdHOTIgODVBQiBhc2RmIDRBQjEgMTQyUyA0NTI0IEJCMkIgM0VFRiAwMDAxIDFCREQgRDY5QyBBOEZDIGFzZGYgNjIwOCA5Q0ZDIEI1NEMgQ0YxMiBGMjUyIDc3RTEifX19Cg==" | base64 -d
{{{FEATURE IVAAPServer INTD 1.0 9-oct-2025 uncounted VENDOR_STRING=users:16 HOSTID=ANY SIGN="022B 6B4F 7G92 85AB asdf 4AB1 142S 4524 BB2B 3EEF 0001 1BDD D69C A8FC asdf 6208 9CFC B54C CF12 F252 77E1"}}}

Please be mindful of this 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

# Example license.dat file that will be provided by SLB
user@linux:/opt/ivaap/$ cat license.dat
FEATURE IVAAPServer INTD 1.0 9-oct-2025 uncounted \
        VENDOR_STRING=users:16 HOSTID=ANY SIGN="022B 6B4F 7G92 85AB \
        asdf 4AB1 142S 4524 BB2B 3EEF 0001 1BDD D69C A8FC asdf 6208 \
        9CFC B54C CF12 F252 77E1"

# Example command to setup proper formatting and base64 encode the license. Set the output of this command for LM_LICENSE_FILE
user@linux:/opt/ivaap/$ echo -n "{{{$(cat license.dat | tr -d '\\\n' | tr -s '[:space:]' ' ')}}}" | base64 -w 0 && echo
e3t7RkVBVFVSRSBJVkFBUFNlcnZlciBJTlREIDEuMCA5LW9jdC0yMDI1IHVuY291bnRlZCBWRU5ET1JfU1RSSU5HPXVzZXJzOjE2IEhPU1RJRD1BTlkgU0lHTj0iMDIyQiA2QjRGIDdHOTIgODVBQiBhc2RmIDRBQjEgMTQyUyA0NTI0IEJCMkIgM0VFRiAwMDAxIDFCREQgRDY5QyBBOEZDIGFzZGYgNjIwOCA5Q0ZDIEI1NEMgQ0YxMiBGMjUyIDc3RTEifX19Cg==

Warning

When running the command to format and base64 encode the license, ensure to use the -n option with the echo command. This prevents a newline character, which can cause the encoded license to fail in the deployment.

For more information on this process, 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: Tue Sep  2 04:31:00 2025
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             9/9     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