Setup via quick start (kubeadm)

LV Containers Quick Start (kubeadm)

This article outlines the minimum requirements necessary to deploy the LumenVox by Capacity solution in an on-premise environment. The installation leverages kubeadm to bootstrap a production-ready Kubernetes cluster on bare-metal hardware or virtual servers. Meeting these minimum specifications ensures a stable foundation for the Capacity components. Clients wanting to perform an on-premises Kubernetes installation can follow these steps for Linux (Some steps may differ to various Linux installations). This makes use of kubeadm to simply the installation process for clients.

Hardware requirements

The minimum server requirements are as follows:

Component	Minimum Requirement	Notes
Operating System	Supported Linux Distribution (e.g., RHEL, CentOS, Ubuntu LTS)	Requires a supported Linux distribution compatible with the latest stable release of Kubernetes.
CPU Cores	8 vCPUs (or physical cores)	This minimum is per single Kubernetes node (Control Plane or Worker).
RAM	16 GB	This memory is required for running the Linux OS, Kubeadm components, and the core LumenVox containers.
Disk Space	250 GB	Required storage space for the operating system, container images, and persistent volumes. SSD is strongly recommended for performance.

System Update and Upgrade

It is highly recommended to ensure your operating system is fully updated before installing new infrastructure software. This step fixes security vulnerabilities and updates core dependencies that the installer script may rely on.

Execute the following command, which performs both the update and the upgrade automatically:

sudo apt update && sudo apt upgrade -y

Download the necessary installation scripts

You need to download the required installation files, which are hosted in a GitHub repository.

You can use the git clone command to pull the entire repository containing the installation script and configuration files onto your machine.

git clone https://github.com/lumenvox/containers-quick-start.git
cd containers-quick-start
git clone https://github.com/lumenvox/mrcp-api.git
git clone https://github.com/lumenvox/mrcp-client.git

Configure Environment Settings in values.yaml

The values.yaml file contains all the customizable settings for the Helm chart that defines your LumenVox deployment within Kubernetes. You must edit this file to match the specifics of your environment.

cd ~/containers-quick-start
vi values.yaml

Edit Appropriate Settings:

clusterGuid:
hostnameSuffix:
loggingVerbosity:
url for external services:
asr language(s)
tts voice(s)

You must create a self-signed TLS certificate key pair. This pair will be used to create the required Kubernetes Secrets that enable secure communication for the speech components.

Create Self-Signed Certificate key

openssl genrsa -out server.key 2048

Create Self-Signed Certificate

Make sure the subjectAltName matches the hostnameSuffix in the values.yaml file.

openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650 \
-addext "subjectAltName = DNS:lumenvox-api.ubuntu12.testmachine.com, \
DNS:biometric-api.ubuntu12.testmachine.com, \
DNS:management-api.ubuntu12.testmachine.com, \
DNS:reporting-api.ubuntu12.testmachine.com, \
DNS:admin-portal.ubuntu12.testmachine.com, \
DNS:deployment-portal.ubuntu12.testmachine.com"

Ensure the script has execute permission 
sudo chmod +x *.sh

Execute the Installer script

After performing the necessary prerequisite steps, you are ready to execute the installer script. This script uses the provided configuration file (values.yaml) along with your SSL key and certificate (server.key and server.crt) to begin the installation process.

./lumenvox-control-install.sh values.yaml server.key server.crt

Set the External Services Password

Upon executing the installer script, you will be prompted to enter the password that will be used for external services integrated with the system.

Please adhere to the following requirement when defining this password:

Allowed Characters: The password must be alphanumeric (containing only letters and numbers).
Restricted Characters: The password must not contain any special characters (e.g., !, @, #, $, %, etc.).

Installation Time and Infrastructure Setup

Once the password is confirmed, the script will begin the main installation process.

This phase is highly automated and will take a few minutes to complete. During this time, the script installs and configures all the necessary infrastructure components required to run LumenVox.

The infrastructure deployed includes:

Docker: The containerization platform.
Kubernetes (K8s): The container orchestration system.
Helm: The package manager for Kubernetes.

You will see output indicating the progress as these components and the LumenVox services are deployed and brought online.

Verify Pod Status

After the installer script finishes setting up the infrastructure, you should verify that all necessary services (pods) are coming online successfully. You can use the kubectl get po -A command to check the status of all pods across all namespaces.

watch kubectl get po -A

You should see a list of all pods. Look for the following states:

Status	Meaning
`Running`	The pod is fully operational and healthy.
`Error` / `CrashLoopBackOff`	Indicates a problem. If you see this, wait a few minutes, as the service may be restarting. If the status persists, you will need to troubleshoot.

Access the Admin Portal to Create a Deployment

The next step in configuring your LumenVox system is to create a deployment via the Admin Portal.

The Admin Portal is accessed using the following Fully Qualified Domain Name (FQDN):

https://admin-portal.ubuntu12.testmachine.com

Note: This should match the hostnameSuffix in the values.yaml file

Hosts File Modification

Since there is no public DNS record for the target FQDN (admin-portal.ubuntu12.testmachine.com), you must manually add an entry to your local machine's hosts file. This tells your computer to resolve the domain name directly to the installation machine's IP address.

Add the following entry, replacing [YOUR_MACHINE_IP] with the actual IP address of the server:

[YOUR_MACHINE_IP] admin-portal.ubuntu12.testmachine.com

[YOUR_MACHINE_IP] http://management-api.ubuntu12.testmachine.com

[YOUR_MACHINE_IP] http://deployment-portal.ubuntu12.testmachine.com

[YOUR_MACHINE_IP] http://lumenvox-api.ubuntu12.testmachine.com

After saving the hosts file, you can access the management-api portal to load the self-signed certificate.

https://management-api.ubuntu12.testmachine.com

Then, access the admin-portal to create a deployment:

https://admin-portal.ubuntu12.testmachine.com/

Click on “CREATE DEPLOYMENT”

Enter the connection string information for the external services.

Below are examples of the connection string for the external services:

Redis

redis://:password@machine-ip:6379

Postgres

postgres://lvuser:password@machine-ip:5432/lumenvox_single_db?sslmode=disable&search_path=public

MongoDB

mongodb://lvuser:password@machine-ip:27017

If successful, the Status should be changed to Ready. You may need to refresh the page a few times for this to take place.

Configuring the MRCP-API (Media Server)

The MRCP API, also referred to as the Media Server, is the core component that communicates directly with your telephony or speech platform (such as Avaya Experience Portal, Cisco UCCX, Asterisk, etc.). This server handles the actual speech processing requests (ASR/TTS).

Navigate to the mrcp-api docker configuration directory:

cd ~/containers-quick-start/mrcp-api/docker

Edit the .env file using your preferred editor (e.g, nano or vi):

vi .env

Locate the following variables in the file and set them according to your specific environment:

APPLICATION_DOMAIN
MEDIA_SERVER__DEPLOYMENT_ID
MEDIA_SERVER__LUMENVOX_API_ADDRESS
MEDIA_SERVER__HOST_MAP

After you have saved the changes to the .env file, you can start the MRCP API (Media Server) containers using docker compose. The -d flag runs the containers in detached mode (in the background).

docker compose up -d

To ensure that the certificate file can be safely copied and accessed by the Docker volumes without conflicts, you must bring down the running MRCP API containers.

docker compose down
sudo cp ~/containers-quick-start/server.crt certs

After successfully copying the server.crt into the designated volume directory, you can now restart the containers to ensure they use the new certificate for secure communication.

docker compose up -d

Test Functionality with simple_mrcp_client

To confirm that your Media Server (MRCP API) is running correctly and capable of handling speech requests (ASR and TTS), you can use the built-in simple_mrcp_client utility. This utility runs as a standalone Docker container and connects directly to your newly configured Media Server.

cd ~/containers-quick-start/mrcp-client
docker compose up -d

Once the simple_mrcp_client container is successfully started, you need to "bash" into the container to interact with the MRCP testing utility inside.

docker exec -ti simple_mrcp_client bash

Once you have successfully entered the simple_mrcp_client container, you can run a basic ASR test to verify the Media Server is correctly recognizing speech input.

simple_mrcp_client -v2 -g builtin:grammar/digits -a audio/1234.ulaw

If the connection is successful and the Media Server recognizes the digits, you should see output similar to the following, which indicates a successful recognition result:

After confirming ASR is working, you should run a basic TTS test to verify the Media Server can successfully generate speech from text and save it as an audio file.

Ensure you are still inside the simple_mrcp_client container, then execute the following command:

simple_mrcp_client -t "This is a test of LumenVox T T S" -o audio/test.wav

If the connection is successful and the Media Server generates the audio file, you should see output similar to the following, indicating a successful synthesis result:

The audio file audio/test.wav should now be present inside the container's file system, ready for playback or transfer.

This completes the installation, configuration, and basic ASR/TTS functionality testing for your LumenVox Media Server deployment.

Was this article helpful?