Setup via quick start (kubeadm)

This guide walks through deploying Capacity Private Cloud in an on-premises environment using kubeadm to bootstrap a production-ready Kubernetes cluster. It covers hardware prerequisites, cluster setup, platform installation, and basic ASR/TTS verification. The steps below target Linux-based bare-metal hardware or virtual servers; some commands may vary depending on your specific Linux distribution.

Hardware Requirements

The minimum server requirements are as follows:

System Update and Upgrade

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 to perform both the update and upgrade:

sudo apt update && sudo apt upgrade -y

Download the Installation Scripts

Download the required installation files from the GitHub repository. Use the git clone command to pull the 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 deployment within Kubernetes. You must edit this file to match your environment.

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

Edit the following settings:

• clusterGuid
• hostnameSuffix
• loggingVerbosity
• url for external services
• ASR language(s)
• TTS voice(s)

View full size

Create Self-Signed Certificate

Generate the private key:

openssl genrsa -out server.key 2048

Generate the certificate:

Ensure 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"

Run the Installer

Set execute permissions on the scripts:

sudo chmod +x *.sh

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

The installer script will prompt you to enter a password for the external services integrated with the system. Please adhere to the following requirements:

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

View full size

Installation Time and Infrastructure Setup

Once the password is confirmed, the script begins the main installation process. This phase is fully automated and takes a few minutes to complete. During this time, the script installs and configures all the necessary infrastructure components.

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 platform services are deployed and brought online.

View full size

Verify Pod Status

After the installer script finishes, verify that all services (pods) are coming online successfully. 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:

View full size

Access the Admin Portal to Create a Deployment

The next step 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.<hostnameSuffix>

Hosts File Modification

Since there is no public DNS record for the target FQDN, you must manually add entries to your local machine's hosts file. This tells your computer to resolve the domain names directly to the installation machine's IP address.

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

[YOUR_MACHINE_IP]  admin-portal.<hostnameSuffix>
[YOUR_MACHINE_IP]  management-api.<hostnameSuffix>
[YOUR_MACHINE_IP]  deployment-portal.<hostnameSuffix>
[YOUR_MACHINE_IP]  lumenvox-api.<hostnameSuffix>

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

https://management-api.<hostnameSuffix>

View full size

Then access the Admin Portal to create a deployment:

https://admin-portal.<hostnameSuffix>

View full size

Click on "CREATE DEPLOYMENT" and enter the connection string information for the external services.

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

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

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

View full size

If successful, the Status should change to Ready. You may need to refresh the page a few times.

View full size

Configuring the MRCP API (Media Server)

Navigate to the MRCP API Docker configuration directory:

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

Edit the .env file using your preferred editor:

vi .env

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

• APPLICATION_DOMAIN
• MEDIA_SERVER__DEPLOYMENT_ID
• MEDIA_SERVER__LUMENVOX_API_ADDRESS
• MEDIA_SERVER__HOST_MAP

View full size

After saving the .env file, start the MRCP API (Media Server) containers. The -d flag runs the containers in detached mode (in the background).

docker compose up -d

To ensure the certificate file can be safely copied and accessed by the Docker volumes, bring down the running MRCP API containers:

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

After copying the server.crt into the designated volume directory, restart the containers to use the new certificate for secure communication:

docker compose up -d

Test Functionality with simple_mrcp_client

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

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

Once the container is started, exec into it to interact with the MRCP testing utility:

docker exec -ti simple_mrcp_client bash

ASR Test: Run a basic speech recognition test to verify the Media Server is correctly recognizing speech input.

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

If the connection is successful and the Media Server recognizes the digits, you should see output similar to the following:

View full size

TTS Test: Verify the Media Server can generate speech from text and save it as an audio file.

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

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

If successful, you should see output similar to the following:

View full size

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 Capacity Private Cloud deployment.