Setup of MRCP API server

The MRCP API server (also referred to as the Media Server) provides the bridge between your telephony or speech platform and the Capacity Private Cloud speech services. It handles SIP/RTSP session negotiation and routes ASR and TTS requests between your IVR platform (such as Avaya Experience Portal, Cisco UCCX, or Asterisk) and the platform's speech engines. This guide covers the server requirements, Docker-based installation, environment configuration, and network port setup.

Installation

Server Requirements

The minimum server requirements are as follows:

• Linux OS capable of running Docker and Docker Compose plugin
• CPU – 2 CPU Cores
• Memory – 4 GB
• Boot Disk – 20 GB

The following steps are for an installation performed on Ubuntu Server. Some commands may vary on other Linux distributions.

Update the Operating System

sudo apt-get update
sudo apt-get upgrade

Install Docker

sudo apt-get install ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Set up Docker to start automatically after server reboot:

sudo systemctl enable docker
sudo systemctl start docker
sudo groupadd docker
sudo usermod -aG docker $USER

Log out and log back in for the group change to take effect.

If you receive a "Permission denied when trying to connect to Docker Daemon" error, run:

sudo chmod 666 /var/run/docker.sock

Install the MRCP API

git clone https://github.com/lumenvox/mrcp-api.git
cd mrcp-api/docker/

TLS Certificate Setup

If connecting to a lumenvox-api instance running with TLS, create the certificate directory and copy the certificate:

cd mrcp-api/docker/
mkdir certs

Copy the server.crt file from the instance running the lumenvox-api to the mrcp-api/docker/certs/ directory.

Edit the .env File

Edit the .env file to match your environment. Below is an example configuration:

PRODUCT_VERSION=7.0
# Control whether containers start automatically when they exit.
# Possible options: 'no', 'on-failure', 'always', 'unless-stopped'
# More info: https://docs.docker.com/config/containers/start-containers-automatically/
RESTART_POLICY=unless-stopped
# Make sure that certificate is matching selected domain
APPLICATION_DOMAIN=testmachine.com

# Timezone for logging. Acceptable values include "America/New_York", "Europe/Rome", etc.
CONTAINER_TIMEZONE=UTC

MEDIA_SERVER__DEPLOYMENT_ID=d80b9d9b-086f-42f0-a728-d95f39dc2229
MEDIA_SERVER__NUM_CHANNELS=200
MEDIA_SERVER__SERVER_IP=192.168.31.197
MEDIA_SERVER__LUMENVOX_API_ADDRESS=lumenvox-api-1.testmachine.com
MEDIA_SERVER__LUMENVOX_API_PORT=443
MEDIA_SERVER__LOGGING_LEVEL=3
MEDIA_SERVER__COMPATIBILITY_MODE=1

Hostname mapping: If you do not have a registered domain for the lumenvox-api, configure the host mapping. If you do have a registered domain, you can leave this empty or comment it out. The hostname should match the value of MEDIA_SERVER__LUMENVOX_API_ADDRESS.

MEDIA_SERVER__HOST_MAP=lumenvox-api.testmachine.com:<IP address of the lumenvox-api interface>

Launch the Docker Containers

docker compose up -d

Server Ports Setup

The MRCP API server provides connectivity between platforms that use MRCP and the Capacity Private Cloud speech services. Typically, platforms use either SIP or RTSP sessions to negotiate connection parameters, including which MRCP port and RTP ports will be used.

Either the SIP or RTSP port can be disabled by setting the port value to 0 if not required. Leaving an unused port enabled does not introduce significant overhead.

The platform supports SIP connections using either UDP or TCP protocols. Configure the appropriate setting when setting up your firewall rules. When the MRCP API server is installed on the same server as another platform that uses SIP connectivity, there may be a port conflict since both attempt to use port 5060 by default. In such cases, change the MRCP server SIP port to an alternative value (e.g. 5066).

For RTP connections, the port ranges for MRCP and RTP connectivity are configurable to avoid overlapping with port ranges used by other applications. RTP data is typically inbound to the MRCP server for ASR audio and outbound for TTS audio.