Overview 

This document provides engineering-level installation and configuration notes for deploying the Knowledge Discovery component on-premise in air-gap environments.

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)
• Net:  Static IPv4 (your FQDN records must resolve to this address)

Prerequisites  

Host preparation  

Run on as a sudo-enabled account: 

# passwordless sudo for the current admin user 
echo "$(whoami) ALL=(ALL) NOPASSWD:ALL" | sudo tee "/etc/sudoers.d/$(whoami)" > /dev/null sudo chmod 440 "/etc/sudoers.d/$(whoami)" 
# 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

Make sure the host has a static IPv4, and your FQDNs (e.g. cai-admin.example.com) point in DNS to this host’s IP. 

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  

Getting Started  

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:

• Start by running “Generator CAI (values & secrets)” to set FQDN/SMTP/TLS.
• All-in-One — when FQDN/TLS are ready.

Quick post-install checks: 

kubectl -n cai get pods 
kubectl -n cai get ingress 
# or use k9s (very convenient) 

Configuration

# useful seting to switch cai namespace as current namespace ( without “-n cai” in use): 
sudo kubectl config set-context --current --namespace=cai

AiCore admin  

#AiCore admin gui password can be taken from kubectl tool in bash: 
kubectl get secrets -n cai aicore-gui-password -o jsonpath="{.data.password}" |  base64 -d; echo 

AI Core Quick Setup Instructions  

1. Log in to the administrator account  (https://<aicore-fqdn>/admin) using the username "admin" and the password retrieved from Kubernetes (CLI command: kubectl –n cai get secret aicore-gui-password -o jsonpath="{.data.password}" | base64 -d 
   The AiCore URL is provided in cai-values.yaml (in section global.fqdn.aicore), or  CLI command: kubectl -n cai get ingress aicore  (listed as HOSTS) .  
2. Navigate to CONFIG → SECRETS and click the "ADD SECRET" button.
3. Add an LLM provider with an OpenAI-compatible API (supports Azure, llamacpp, Mistral, and others). Specify the API URL and key, then check the appropriate boxes if using Azure.
4. Click Save.
5. Navigate to CONFIG → PASSTHROUGH.
6. Enable "Enable pass through" and select the backend you just configured. Available models from the provider's API should appear in the "Force Model" dropdown. Select one of the suggestions. If no models appear, verify your configuration in SECRETS, as your URL or API key may be incorrect.
7. Navigate to CONFIG → "API & Authentication" and reset the "API Key". Save the key immediately, as it cannot be displayed later, only reset.
8. The API key and the address where the AI Core container is running will be required for Project configuration in the CAI panel. You can verify their correctness using tools such as curl or Postman, or any OpenAI-compatible client. Example queries are available on the main page of the AI Core management panel. 

Conversational AI admin

1. Create the first tenant (admin): 
   
   After registration, an activation link will be sent via email. 
2. Log-in to CAI admin with credentials provided during registration
   • Add aiCore API Key as Secret:
   • Navigate to: BUILD / AI Chatbot / Secrets
   • Click "New secret" button
   • In "Name" field: enter any name in UPPERCASE letters for this key
   • In "Value" field: paste the API key from your LLM backend created during aiCore configuration
   • Recommended: Uncheck "Allow viewing the secret value" checkbox to prevent viewing this secret value from admin panel after creation
   • Save the secret
3. Add aiCore Configuration:
   • Navigate to: BUILD / AI Chatbot / AI Core Configurations
   • Click "New configuration" button  
   • In "Name" field: enter any name for this configuration  
   • In "API URL" field: paste the LLM backend URL created during aiCore configuration  
   • In "Select an API Key" dropdown: select the secret created in step 3  
   • Save the configuration
4. Assign aiCore Configuration to Project:
   • Navigate to: BUILD / AI Chatbot / Projects
   • Open the available project
   • Go to "Knowledge sources" section
   • In "Type" field: select “AiCore”
   • In "AiCore model" dropdown: select the configuration created in step 4
   • Click green "Save" button in the top-left corner
     From this moment, the widget in this project will respond using the specified AiCore backend.
5. Enable M42 Enterprise authentication
   • Navigate to: BUILD / AI Chatbot / Projects  
   • Open the available project
   • Go to "Advanced" section
   • Navigate to “M42 Enterprise authentication”
   • Click “Enable authentication”
   • Provide authentication URL in following format: 
     https://your-dwp-instance-url/m42Services/api/userinfo
   • Click green "Save" button in the top-left corner 

Update procedure  

To upgrade CAI to a newer bundle version, you must reuse the same values file:

1. Make sure your previously generated cai-values.yaml is present here: 
   values/cai-values.yaml ## in cai-airgap-bundle folder.  
   This file is usually created by "simple-config-generator" during installation. 
   Upgrading without file cai-values.yaml is not supported.
2. Recommended way (using setup-menu.sh), run:

bash setup-menu.sh   # is placed in in cai-airgap-bundle main folder

Then choose:
[[ 2) Advanced options ]] ---> [[ f) apply secrets + install CAI ]]

This will upgrade the current CAI installation to the new version, using the existing settings from values/cai-values.yaml.

An optional way to update is to run the script directly: Instead of setup-menu.sh run the install script directly: 
bash scripts/11-install-cai.sh # in cai-airgap-bundle main folder 
It still requires existing values/cai-values.yaml with the current configuration (mandatory).