Installing BotStream

    1 Introduction

    The document describes the steps involved in installing/upgrading components part of BotStream. All the required deb packages can be downloaded from this link .

    The installation prerequisites are:

    • Kubernetes environment for IraCluster and IraPass. (Cloud Kubernetes / Local k3OS VM)

    • Server with Debian 12 for handling Telephony (BotStream)

    • Server with Debian 12 for recording processing (mp3 creation) and uploading to long term storage.

    For integration testing or for demos one can get a desktop with Debian 11 or 12 / Ubuntu 22 as base OS, install KVM for virtualization and create a k3os VM on it for the Kubernetes environment.

    2 Install NTP

    Install NTP on all server machines.

    apt install ntp

    3 Configure AWS CLI

    Installation of AWS CLI is to be done on your local machine or the botstream machine. We will be using the AWS CLI to generate passwords which will be required for authenticating with AWS ECR to download IraCluster Helm Chart (section 3) .

    3.1   Install AWS CLI

    https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

    3.2  Configure AWS CLI

    $aws configure

    AWS Access Key ID [None]: AKIAQKHNZ22ZHLLF6GII

    AWS Secret Access Key [None]: 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

    Default region name [None]: us-east-1

    Default output format [None]: json

    3.3  Get AWS Password

    The command retrieves and displays the password that you can use to authenticate to an Amazon ECR public registry. Note down the value generated in this step for later use.

    $aws ecr get-login-password --region us-east-1

    Note:

    The password is valid for 12 hours.  Repeat 2.3 when you want to generate a new password. 

    4 Install Helm Charts

    4.1 Install Helm

    Install helm if not already available by following the link https://helm.sh/docs/intro/install/

    Run the below command after installing helm

    export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

    helm repo add k8tz https://k8tz.github.io/k8tz/

    helm install k8tz k8tz/k8tz --set timezone=Asia/Kolkata

    4.2 Epicode Helm Charts

    4.2.1 Helm registry login for private helm charts

    Generate the AWS password by following section 2.3 of this document.

    Paste the generated password into a file password.txt on the machine where the helm chart is to be installed.

    Run the below command from the directory where password.txt exists.

    cat password.txt|helm registry login -u AWS --password-stdin 021973554866.dkr.ecr.us-east-1.amazonaws.com


    4.2.2 Install IraCluster Helm Chart

    helm install iracluster -f iracluster-values.yaml oci://public.ecr.aws/epicode-modules/iracluster-helmchart

    Sample iracluster-values.yaml

    config:
      SYS_NATS_PUBLIC: ""
      SYS_NATS_SEED: ""
      NORMAL_NATS_PUBLIC: ""
      NORMAL_NATS_SEED: ""

    epi-nats:

      config:

        merge:

          accounts:

            sysAcc:

              users:

                - nkey: ""

              exports:

                - stream: ira.sys.disconnect.>

            normal:

              jetstream: enabled

              users:

                - nkey: ""

              imports:

                - stream: { account: sysAcc, subject: ira.sys.disconnect.>}

          system_account: sysAcc

    4.2.3 Install IraPass Helm Chart

    Finally, install the IraPass helm chart using the below command by replacing <your_cluster_id> with the cluster ID provided to you and <release_name> with the name of your choice (Ex: irapass). 

    helm install --set config.iraClusterId=<your_cluster_id> <release_name> oci://public.ecr.aws/epicode-modules/irapass-helmchart

    A single instance of IraCluster can be used for supporting multiple BotStream clusters. This is achieved by installing the IraPass helm chart multiple times, one for each cluster. Make sure to give a unique release name for each cluster to identify it during upgrade and uninstallation.


    4.2.4 Install Botstream Monitor Helm Chart

    helm install --set config.ira_cluster_id=<your_cluster_id> <release_name> oci://021973554866.dkr.ecr.us-east-1.amazonaws.com/botstream-monitor-helmchart

    4.2.5 Install bot connect helm chart

    helm install -f bot-connect-values.yaml bot-connect oci://public.ecr.aws/epicode-modules/bot-connect-helmchart

    Sample bot-connect-values.yaml

    replicaCount: 2
    config:
      cluster_id: "<cluster_id>"
      default_websocket_host: "127.0.0.1"
      default_websocket_port: "11000"

      default_speech_threshold: "500"

      default_silence_threshold: "5"

      initial_botaudio_delay_threshold: "4"


    4.2.6 Install CDR HTTP Helm Chart

    helm install -f cdr-http-values.yaml cdr-http oci://public.ecr.aws/epicode-modules/cdr-http-helmchart

    Sample cdr-http-values.yaml

    config:

      cluster_id: "k3slt"

      nats_subscribe_subject: "k3slt.botstream.result"

      http_post_url: "http://172.16.3.16:1323"

      http_bearer_token: ""

      http_timeout: 60

      max_concurrent_requests: 5

      log_level: "info"

      email_alert:

        url: "https://mailerweb.epicode.in/send_bstm_email"

        bearer_token: "3p!c0ded"

        customer_name: ""

        site_name: ""

        error_threshold: 100

        error_check_interval: 300

        error_track_duration: 300

    4.2.7 Install bstm-router Deployment File

    Create a YAML file as “bstmrouter-depl.yaml”  by replacing <your_cluster_id> with the cluster ID provided to you and image <version> accordingly. 

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: bstmrouter-depl
    spec:
      selector:
    matchLabels:
      app: bstmrouter
      replicas: 1 # tells deployment to run 2 pods matching the template
      template:
    metadata:
      labels:
        app: bstmrouter
    spec:
      containers:
      - name: bstmrouter
        image: public.ecr.aws/epicode-modules/bstmrouter:<version>
        imagePullPolicy: IfNotPresent
        command: [ "/usr/local/bin/IraBstmRouter", "<your_cluster_id>", "NORMAL" ]
        env:
          - name: NORMAL_NATS_SEED_KEY
            valueFrom:
              configMapKeyRef:
                name: nats-config
                key: NORMAL_NATS_SEED
          - name: NORMAL_NATS_PUBLIC_KEY
            valueFrom:
              configMapKeyRef:
                name: nats-config
                key: NORMAL_NATS_PUBLIC
          - name: IRA_NATS_URL
            valueFrom:
              configMapKeyRef:
                name: nats-config
                key: IRA_NATS_WEBURL
      imagePullSecrets:
      - name: ira-ecr-user

    Run the below command : 

    kubectl apply -f bstmrouter-depl.yaml

    4.2.8 Upgrade helm charts

    To upgrade to a newer version:

    4.2.6.1 (i) IraCluster helm chart

    helm upgrade iracluster oci://021973554866.dkr.ecr.us-east-1.amazonaws.com/iracluster-helmchart

    4.2.6.2 (ii) IraPass helm chart

    helm upgrade <release_name> oci://public.ecr.aws/epicode-modules/irapass-helmchart

    5 Install BotStream

    BotStream is released as a deb package for Debian 12 Bookworm. Procure a VM/physical machine with Debian 12 installed.

    The following instructions apply both for a fresh installation as well as for upgrading from an older version of the package to a newer version.

    5.1  Install Ira-Dependency Repository

    Download the latest version of the ira-dependency-repo deb package from this link .

    Copy it to the target Debian machine and install it using the apt install command.

    sudo apt install ./ira-dependency-repo_1.3.0-0.deb

    Run apt-get update after installing dependency repo so that the package manager knows about the new repo.

    sudo apt-get update

    5.2  Install IraBase

    Download the latest version of the Irabase deb package from this link .

    Copy it to the target Debian machine and install it using the apt install command.

    sudo apt install ./irabase_2.0.2-0.deb

    Enter the NATS url and cluster key, Seed keys when prompted for the same during the installation.

    Note : If you wish to change the NATS url and/or cluster key at a later date, run:

    sudo dpkg-reconfigure irabase

    5.3  Install Botstream

    Download the latest version of the Botstream deb package from this link .

    Copy it to the target Debian machine and install it using the apt install command.

    sudo apt install ./botstream_1.11.1-0.deb

    Note: If you changed the NATS url and/or cluster key in the irabase, run the below command for botstream : 

    sudo dpkg-reconfigure botstream

    6 BotStream Monitoring

    The BotStream deb includes a command line utility for monitoring the system status. This will display the following details in real time:

    • License issued and license usage

    • Load across all BotStream instances in the cluster

    • Physical SIP Gateways defined and their usage statistics

    • Logical Gateways defined and their usage statistics

    This can be invoked by running /usr/local/epi/scripts/monitor.sh

    Press Ctrl+C to stop the monitoring.

    7 BotStream API Usage Samples

    BotStream deb includes a set of python scripts showcasing the usage of Botstream APIs.

    These can be found in the directory /usr/local/epi/scripts/py

    In order to run the scripts, follow the following steps.

    1) Change the current directory to the sample scripts folder

    cd /usr/local/epi/scripts/py

    2) Activate the python virtual environment which includes the required python dependency libraries.

    source venv/bin/activate

    3) Run the required sample script.

    python3 <script_name>

    Example:

    python3 reload_lic.py

    4) Deactivate the python virtual environment once done.

    deactivate

    8 IraDummyVAI

    BotStream deb includes a Dummy voice AI application to mimic a conversational AI application. This application will receive all call events via NATS, request for the media stream to itself and accept the stream and respond back with a random message.

    This can be run in 2 modes.

    • sleg mode: Requires the botstream sleg(Stream leg license). Receives stream continuously and plays a file back saying “hundred” once in every 5 seconds.

    • slegvad mode: Requires the botstream slegvad(Stream leg: Voice Activity Detection license). Receives the media stream as a chunk as soon as the user pauses while speaking. The DummyVAI will respond back with a random sentence to indicate that it has heard you. One can speak short or long sentences and the IraDummyVAI will respond with a random remark as soon as you complete the sentence and pause.

    The IraDummyVAI can be invoked by running the shell script:

    /usr/local/epi/scripts/start_tester.sh

    By default, when BotStream is installed, the IraDummyVAI will be in the slegvad mode.

    While the shell script is running, any outbound calls made through the makecall sample script will be handled by Botstream and IraDummyVAI.

    To stop the script press Ctrl+C.


    9 Uninstallation

    9.1 Kubernetes components

    To uninstall helm charts

    9.1.0.1 (i) IraCluster, IraPass & BotStream Queue helm chart

    helm uninstall <release_name>

    Examples:

    helm uninstall iracluster

    helm uninstall irapass

    helm uninstall botstream_monitor

    To Uninstall Deployments 

    9.1.0.2 bstm-router 

    kubectl delete deployment <deployment_name>

    9.2 Debian components

    The Debian packages can be uninstalled with the “apt remove” command.

    sudo apt remove <package_name>

    So the the Botstream and related components can be uninstalled from their respective servers as follows:

    sudo apt remove botstream
    sudo apt remove irabase

    Sudo apt remove ira-dependency-repo
    Published