Skip to content

Deploy Helm Package on AWS

Overview

Enhance your productivity with our advanced Multilingual Dictation Platform, designed for seamless dictation in multiple languages, including Hebrew, English, and Arabic. This solution provides support for multiple speech models on the same site, allowing you to switch effortlessly between different languages and accents for accurate transcription.

With built-in integration for LDAP or SAML, managing users and permissions is streamlined, ensuring secure and flexible access. The platform also features customizable word mappings and keyboard shortcuts, enabling users to tailor the experience to their specific needs and workflows.

The intuitive and simple UI makes it easy for users of all skill levels to navigate and use the dictation platform without extensive training, boosting efficiency and reducing the time spent on manual transcription.

Optimize your organization's transcription processes today with our scalable, secure, and user-friendly dictation platform.

Features

  • Multilingual Dictation: Supports dictation in Arabic, English, and Hebrew.
  • SAML & LDAP Integration: Seamless user management with support for Active Directory and LDAP.
  • Customizable Word Mappings & Shortcuts: Configure word mappings and set up keyboard shortcuts for a personalized experience.
  • Simple & Intuitive UI: User-friendly interface for easy navigation and quick adoption.

Getting Started

Prerequisites

Before you begin, make sure you have the following:

  1. Updated Chrome/Edge Browser

  2. Kubernetes Cluster: Ensure you have access to a Kubernetes cluster (EKS) with:

    a. At least one node with 4 cores and 24GB RAM

    b. Dynamic Storage Provisioner with StorageClass (e.g: AWS EBS CSI Driver)

  3. Helm CLI: Helm must be installed on your local machine or CI/CD pipeline (Helm installation guide)

  4. kubectl CLI: kubectl must be installed and configured to interact with your Kubernetes cluster (kubectl installation guide)

AWS Permissions

Make sure your AWS account has the following permissions to use AWS Marketplace:

  • aws-marketplace:ViewSubscriptions
  • aws-marketplace:Subscribe
  • aws-marketplace:Unsubscribe

Step 1: Subscribe to Koldan on AWS Marketplace

  1. Go to the AWS Marketplace listing for Koldan.
  2. Click Continue to Subscribe.
  3. Review the pricing and terms.
  4. Click Subscribe.
  5. Once subscribed, you will receive access to the Helm chart.

Step 2: Obtain the Helm Chart

Once you are subscribed, you will receive a Helm chart repository URL in the AWS Marketplace listing page under the Usage Information tab.

Add the Helm repository:

helm repo add [repo-name] [repository-url]
helm repo update

Step 3: Values.yaml File

Before installation you must customize the deployment by creating a values.yaml file with defaults and placeholders, we will configure them in next steps:

###################################
# Koldan AWS Template values.yaml #
###################################

config: |
  koldan:
    s3:
      bucket: <BUCKET_NAME>
      accesskey: <S3_ACCESSKEY>
      secretkey: <S3_SECRETKEY>
    api:
      advertiseAddr: <ADV_ADDR>
      grpc:
        advertisePort: 8195
        ssl: false
    site:
      name: Koldan
      updatesUrlOverride: "https://koldan.dixilang.com/api/update"
  spring:
    datasource:
      username: <PG_UESRNAME>
      password: <PG_PASS>

web:
  replicaCount: 0
  image:
    repository: 709825985650.dkr.ecr.us-east-1.amazonaws.com/dixilang/m-koldan-backend
  oauth:
    clientSecret: |
      {"clientSecret": "<KOLDAN_API_HTTP_SECRET>"}
  persistence:
    updates:
      class: <UPDATES_STORAGE_CLASS>
      size: 1Gi
  service:
    type: LoadBalancer
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-disable-tcp-reset: "true"

grpc:
  replicaCount: 0
  image:
    repository: 709825985650.dkr.ecr.us-east-1.amazonaws.com/dixilang/m-koldan-backend
  oauth:
    clientSecret: |
      {"clientSecret": "<KOLDAN_API_GRPC_SECRET>"}
  service:
    type: LoadBalancer

engineK2:
  image:
    repository: 709825985650.dkr.ecr.us-east-1.amazonaws.com/dixilang/m-koldan-k2-engine
  oauth:
    clientSecret: |
      {"clientSecret": "<KOLDAN_ENGINE_SECRET>"}

  instances:
  - id: "general"
    replicaCount: 0
    service: {}
    resources: {}
    autoscaling: {}
    volumes: []
    volumeMounts: []
    nodeSelector: {}
    tolerations: []
    affinity: {}
    hotwords:
      enabled: false
      content: ""

# Dependencies
keycloak:
  image:
    registry: 709825985650.dkr.ecr.us-east-1.amazonaws.com
    repository: dixilang/keycloak
  service:
    type: LoadBalancer
  externalDatabase:
    user: <PG_UESRNAME>
    password: <PG_PASS>
  ingress:
    enabled: false
    hostname: keycloak.koldan.changeme.com
    tls: true

postgresql:
  image:
    registry: 709825985650.dkr.ecr.us-east-1.amazonaws.com
    repository: dixilang/postgresql
  auth:
    postgresPassword: <PG_ROOT_PASS>
    username: <PG_UESRNAME>
    password: <PG_PASS>
  primary:
    persistence:
      existingClaim: ~
      storageClass: <PG_STORAGE_CLASS>
      size: 8Gi
    initdb:
      user: <PG_UESRNAME>
      password: <PG_PASS>

minio:
  image:
    repository: 709825985650.dkr.ecr.us-east-1.amazonaws.com/dixilang/m-minio
  rootUser: <S3_ACCESSKEY>
  rootPassword: <S3_SECRETKEY>
  persistence:
    storageClass: <S3_STORAGE_CLASS>
    size: 50Gi

zookeeper:
  image:
    registry: 709825985650.dkr.ecr.us-east-1.amazonaws.com
    repository: dixilang/zookeeper
  persistence:
    existingClaim: ~
    storageClass: <ZOOKEEPER_STORAGE_CLASS>
    size: 1Gi

elasticsearch:
  image: "709825985650.dkr.ecr.us-east-1.amazonaws.com/dixilang/m-elasticsearch"
  volumeClaimTemplate:
    storageClassName: <ELASTICSEARCH_STORAGE_CLASS>
    resources:
      requests:
        storage: 8Gi

Values Configurations

Database (PostgreSQL)

In order to configure the database we will have to decide on a master password (for an administrative user postgres), and username and password for our application. Find all the relevant placeholders and replace them with your desired values.

Placeholder Description Example Value
<PG_ROOT_PASS> Password for the master postgres admin user Generate Secure Password
<PG_USERNAME> Name for a koldan user to create koldan
<PG_PASS> Password for the koldan user Generate Secure Password

Object Storage (S3)

In addition we will have to configure the Object Storage settings for storing large files such as model files. Find all the relevant placeholders and replace them with your desired values.

Placeholder Description Example Value
<S3_ACCESSKEY> Username (access key) for S3 koldan
<S3_SECRETKEY> Password (secret key) for S3 Generate Secure Password
<BUCKET_NAME> S3 Bucket name koldan

Storage Classes

For the required PVC's we will need to set StorageClasses, Find all the relevant placeholders and replace them with your desired values.

Placeholder Description Example Value
<PG_STORAGE_CLASS> PostgreSQL primary StorageClass, should be fast but not large gp2
<S3_STORAGE_CLASS> StorageClass for S3, should be large but not fast gp2
<ZOOKEEPER_STORAGE_CLASS> ZooKeeper StorageClass, should be fast but not large gp2
<ELASTICSEARCH_STORAGE_CLASS> ElasticSearch StorageClass, should be both large and fast gp2
<UPDATES_STORAGE_CLASS> Desktop updates StorageClass, can be small and slow gp2

Server Installation

After configure the basics, you can now install using helm and wait for all services to become Ready

helm install koldan -n koldan koldan-chart.tgz -f values.yaml --create-namespace && \
  kubectl wait --for=condition=Ready pods --all --namespace koldan --timeout=300s

Generating Client Secrets

  1. Access your Keycloak instance via the browser (via LoadBalancer or Ingress): kubectl get service keycloak --namespace koldan -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

  2. Login with username admin and password admin, you will be prompt to change it on first login

  3. Select 'dixilang' Realm (In the left sidebar, click on Realm Selector and choose dixilang).

  4. Navigate to 'Clients' (In the left sidebar, select Clients under the dixilang realm)

    There are 3 clients that should be considered: koldan-api-grpc, koldan-api-http and koldan-engine

For each relevant client, we will create a secret key and replace it with the appropriate placeholder in the values.yaml file.

To generate secret, click on a client name, navigate to 'Credentials' tab and click the Regenerate button to create a new client secret.

Client Placeholder
koldan-api-grpc <KOLDAN_API_GRPC_SECRET>
koldan-api-http <KOLDAN_API_HTTP_SECRET>
koldan-engine <KOLDAN_ENGINE_SECRET>

Set user for Koldan console

To set admin user for Koldan, follow these steps:

  1. log into keycloak console
  2. switch realm to dixilang (top left corner).
  3. Navigate to users and choose admin user.
  4. Select the credential tab, NOTE that the default is set to temporary password, disable it and set your own password.

In order for the API to know how to publish its own address (for discovery), the gRPC address must be defined as exposed to the outside. If you followed this guide, the gRPC is exposed by a service with type LoadBalancer. Therefore, we must understand what the address we received is:

kubectl get service koldan-grpc-service --namespace koldan -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

In values.yaml, find <ADV_ADDR> and replace it with the returned value (e.g: xxx-xxx.xx-xxx-x.elb.amazonaws.com).

Scale up Web and gRPC services

In the values.yaml file change web, and grpc replicaCount to 1, i.e:

...
web:
  replicaCount: 1
...
grpc:
  replicaCount: 1
...

Upgrade koldan installation to apply the changes and wait for all services to become Ready:

helm upgrade koldan -n koldan koldan-chart.tgz -f values.yaml && \
  kubectl wait --for=condition=Ready pods --all --namespace koldan --timeout=300s

Engine

Find the Koldan Web console URL from service type LoadBalancer:

kubectl get service koldan-web-service --namespace koldan -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

Browse to that url with port 8193, e.g: http://xxx-xxx.xx-xxx-x.elb.amazonaws.com:8193

And login with the username admin and the password you defined for user admin in keycloak.

Create Model

Navigate to Presets & Models -> Models Regisrty and click on Add Model and fill the form:

  • Model Name: Choose name identifier to the model, alhapbetic only without spaces, i.e: myfirsthebrewmodel
  • Display Name: Choose display name for the model, can be same as name (i.e: myfirsthebrewmodel)
  • Sample Rate: Keep it 16kHz for most cases
  • Upload Model: Choose "Select Model" tab and choose "Hebrew General" model from the list
  • Language: Choose model language, i.e: HEBREW

Then click Create and wait few minutes for the model to create.

Create Preset

Naviagte to Presets tab, click on Add Preset button and fill the form:

  • Preset Name: Choose name identifier to the preset, alhapbetic only without spaces, i.e: general
  • Display Name: Choose display name for preset, that's what the user will see when selecting model (i.e: General Hebrew)
  • Description: Choose description for the preset, the user will see that when choosing models
  • Allowed Roles: Choose what roles has access to that preset, default is koldan-user for every koldan user
  • Choose Model: Choose the model we created in previous step (myfirsthebrewmodel)

Click Create to create the preset.

Start Engine Instance

Once Preset is configured, open the values.yaml file and find the engineK2.instances[] place.

Change instance ID to name of preset (i.e: general) and change replicaCount to 1, i.e:

...
engineK2:
  instances:
  - id: "general"
    replicaCount: 1
...

Upgrade koldan installation to apply the changes and wait for all services to become Ready:

helm upgrade koldan -n koldan koldan-chart.tgz -f values.yaml && \
  kubectl wait --for=condition=Ready pods --all --namespace koldan --timeout=300s

Install the Client

Install on windows machine koldan-installer.exe, after installed, open the application and choose "Organization", then select "Manual Properties".

In the manual properties form, fill the fields:

  • Hostname: The LoadBalancer hostname of gRPC service (or ingress, if enabled) (kubectl get service koldan-grpc-service --namespace koldan -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
  • Port: The default port is 8195
  • SSL: In this guide we do not cover the topic of SSL, so the checkbox should be unchecked

Click Next and put same username and password as you did for the web console (username is admin and the password as you defined in previus steps).

Learn more about the client

Upgrading the Helm Chart

Fetch the Latest Chart Version

Ensure you have the latest chart by updating your Helm repositories:

helm repo update

Apply the Upgrade

helm upgrade <release-name> <chart-name> --namespace <namespace> -f values.yaml

Verify the Upgrade

After the upgrade, verify that the deployment was successful:

kubectl get all --namespace <namespace>

Roll Back if Necessary

If the upgrade caused issues, you can roll back to the previous version:

helm rollback <release-name> <revision-number> --namespace <namespace> -f values.yaml

What's Next?

There are quite a few actions that can be performed starting from this stage, but we will not cover them in this guide. for example:

  • Users can be created through the Users page in Keycloak
  • The web service (console) can be exposed through Ingress with SSL
  • An LDAP server or SAML service can be connected for authentication (this may require exposing Keycloak in Ingress with SSL)

Health Monitoring

You can monitor the health and functionality of the application by following these steps:

Via AWS

Check Node health:

  • Connect to the AWS Console.
  • Navigate to the EC2 dashboard.
  • Ensure that the nodes (EC2 instances) are in a healthy state.
    • Look for Running and 2/2 checks passed status.
  • If any instance is unhealthy or not running, check its logs for further details.

Check EKS cluster health:

To check if your pods are running on AWS using Amazon Elastic Kubernetes Service (EKS), follow these steps:

  • If you don’t have kubectl installed, you can install it by following the official Kubernetes guide.
  • Make sure your kubectl is configured to connect to your EKS cluster. You can do this using the AWS CLI:
aws eks --region <region-name> update-kubeconfig --name <cluster-name>
  • Once your kubectl is configured, run the following command to list all pods in the cluster:
kubectl get pods -n koldan

You should see an output that looks like this:

NAME                                       READY   STATUS                   RESTARTS       AGE
elasticsearch-0                            1/1     Running                  0              12m
koldan-engine-k2-hebmed-d789769c4-7wjsk    1/1     Running                  0              12m
koldan-grpc-74ddf4f688-7k9m7               1/1     Running                  0              12m
koldan-web-756f5d5869-w8hwh                1/1     Running                  0              12m
minio-89f5447c8-pgw6l                      1/1     Running                  0              12m
postgresql-0                               1/1     Running                  0              12m
zookeeper-0                                1/1     Running                  0              12m
keycloak-0                                 1/1     Running                  0              12m

READY shows how many containers are running in the pod.

STATUS should show Running for a healthy pod. If you see Pending, Error, or CrashLoopBackOff, there might be an issue.

Via web browser

Log Into the Website:

  • Open your browser and navigate to the website URL.
  • Log in using your credentials.

Check if the Engine is Running:

  • After logging in, navigate to the Preset & Models Page.
  • Look for the green dot to the left of the preset name. This indicates that the engine is running.
  • If the green dot is not visible, the engine may not be running. Investigate by checking the backend logs or restarting the services.

Uninstalling the Helm Chart

To uninstall Koldan server and all associated resources:

helm uninstall koldan --namespace koldan && \
  kubectl delete pvc -n koldan --all && \
  kubectl delete namespace koldan

Support

For support, please contact us at office@dixilang.com.