KD4EU Installation for Version 1.3

+ More

Table of Contents

Overview System Requirements Prerequisites Host Preparation Package Contents Installation Update Procedure

Overview 

This document provides engineering-level installation notes for deploying the Conversational AI (CAI) and AI Core components of Knowledge Discovery for End Users (KD4EU) on-premise in air-gap environments.

After the installation is complete, continue with: KD4EU Configuration for Version 1.3.

 

System Requirements  

  • OS:   Ubuntu Server 24.04 LTS (linux/amd64)   
  • CPU:  4 vCPU (6+ recommended)
  • RAM:  16 GB (24 GB recommended)
  • Disk: 100 GB free space (200 GB recommended)
  • Network: 
    • Static IPv4 address assigned to the VM.
    • DNS: the following FQDNs must resolve to the VM's static IPv4 (A records) and be reachable from your end users' browsers:
      • cai-admin.<your-domain>
      • cai-rail.<your-domain>
      • cai-preview.<your-domain>
      • cai-static.<your-domain>
      • cai-aicore.<your-domain>
    • TLS: a certificate covering all of the FQDNs above (wildcard *.<your-domain> or SAN), issued by a CA trusted by your end users' browsers.
    • Inbound ports: 443/tcp (HTTPS) open from end-user networks to the VM.
    • Outbound: no internet access required (air-gapped installation).

We recommend using a single partition for the entire disk (100G / 200G) mounted as /, rather than splitting it into multiple partitions (/var, /opt, /usr, etc.). This approach avoids space fragmentation and simplifies management.

 

Prerequisites  

Host Preparation  

Run on as a sudo-enabled account: 

# Disable SWAP (recommended for Kubernetes)
sudo swapoff –a;
sudo rm -f /swap.img;
sudo sed -i '/swap/ s/^[^#]/#&/' /etc/fstab
# updates and required packages
sudo apt update && sudo apt dist-upgrade –y;
sudo apt install -y dialog iptables-persistent nano less

 Note: The apt update, apt dist-upgrade and apt install commands need access to Ubuntu package repositories. On an air-gapped host, use one of these options:

  • run this step before the host is disconnected from the network, or
  • point APT to a local repository mirror available in your network (e.g. an internal Ubuntu mirror, or a proxy such as Nexus or Artifactory).

    The bundle itself does not contain operating system packages.
 

Package Contents  

The bundle unpacks into cai-airgap-bundle/ (after extracting cai-airgap.tar.gz):

  • bin/ – CLI tools (Helm, k9s)
  • k3s/ – K3s binary and its offline image bundle
  • charts/ – Helm charts (*.tgz) for ingress, MySQL, PostgreSQL, MinIO, and CAI
  • images/*/ – pre-exported container images as .tar files (per component)
  • scripts/ – installer scripts used by the setup menu
  • values/ – configuration files generated by the configurator or manual
  • secrets/ – secret manifests generated by the configurator or manual

Start the installer from the bundle root: bash ./setup-menu.sh

Installation    

tar -xvf cai-airgap.tar.gz 
cd cai-airgap-bundle 
bash ./setup-menu.sh

The interactive menu lets you run steps individually or choose an All-in-One path. For a new installation, use the All-in-One path::

  • Select Install All-in-One. You will be asked to configure the prerequisites (FQDN, SMTP, TLS) before the installation starts.
  • Provide the e-mail address for tenant provisioning. This e-mail address becomes the login to the Conversational AI administrator portal.

    Tip: Provide a real, accessible e-mail address. If SMTP is configured, the administrator can recover a lost password: on the login screen of the Conversational AI administrator portal, click Forgot password, and a password reset link will be sent to this e-mail address

     
  • Choose the tenant template: PRO or Enterprise, depending on the Matrix42 ITSM product you use. Note: Knowledge Discovery for End Users is designed for Matrix42 Enterprise. Select Enterprise if you are installing it for Knowledge Discovery for End Users.
  • Provide the password for the Conversational AI administrator portal account.
  • The installer now deploys all components. This can take several minutes. Do not interrupt the process until the tenant data is displayed.
  • Save the tenant data. When the installation completes, the installer creates the Conversational AI tenant and displays its access data, for example:
    CAI & AI Core tenants created (HTTP 201)
   CAI Admin login          : admin@example.com
   CAI Admin password       : ********
   Conversational AI URL    : https://cai-static.example.com
   Agent Console URL        : https://cai-rail.example.com
   Installation ID          : a27ec55f58cd77c444dc3aec44e59a537c9f9628c741aecf6782db16d73f5728
   Space ID                 : 4817
   AI Core URL              : https://cai-aicore.example.com
   AI Core admin URL        : https://cai-aicore.example.com/admin/login   
   AI Core admin login      : admin   
   AI Core admin password   : *****

    Store these values in a secure place. You will need them in the next steps.

     
  • Optionally, set cai as the default namespace, so that you do not need to add -n cai to every kubectl command:
    sudo kubectl config set-context --current --namespace=cai
  • Ensure that all pods are in running state using below command:
    kubectl get pods

Update Procedure  

If you're upgrading from a version older than 1.2.0, upgrading to 1.2.0 first is mandatory. Download version 1.2.0, open its installer, and execute the "Migrate application" section (steps 3 → 4) after completing step 2. Ensure all pods are in RUNNING state between step 1/2 and step 2/2. Only after this migration is complete, download version 1.2.1 and perform the regular update.

 

To upgrade a KD4EU installation to a newer bundle version, reuse the configuration from your current bundle: values/cai-values.yaml (mandatory) and secrets/. Upgrading without cai-values.yaml is not supported.

1. Back up. Create a snapshot of the VM before upgrading. It is the simplest way to roll back if the upgrade fails.

2. Keep the current bundle. The new bundle extracts to the same folder name,
  so rename the current folder first:

mv cai-airgap-bundle cai-airgap-bundle-<current-version>
tar -xvf cai-airgap.tar.gz

3. Copy your configuration into the new bundle:

cp cai-airgap-bundle-<current-version>/values/cai-values.yaml cai-airgap-bundle/values/
cp -r cai-airgap-bundle-<current-version>/secrets/. cai-airgap-bundle/secrets/

4. Run the upgrade from the new bundle folder:

cd cai-airgap-bundle
bash ./setup-menu.sh

  Then choose 2) Advanced options → f) apply secrets + install CAI.
  This upgrades the installation using the settings from values/cai-values.yaml.

  Alternatively, run the install script directly:

bash scripts/11-install-cai.sh

5. Verify. Check that all pods are in the Running or Completed state:

kubectl -n cai get pods

Keep the previous bundle folder until you have confirmed that the upgrade works.

 
  • CAI Admin login and CAI Admin password: to log in to the Conversational AI administrator portal (https://cai-admin.<your-domain>).
  • Conversational AI URL, Agent Console URL, Installation ID and Space ID: to activate the Knowledge Discovery for End Users extension in Matrix42 Enterprise. See: KD4EU Configuration for Version 1.3 → 1. Matrix42 Enterprise → Activate.
  • AI Core admin URL, AI Core admin login, AI Core admin password: to log in to the AI Core administrator portal (https://cai-aicore.<your-domain>/admin/login)

Related Articles