Documentation
hila platform
Applications
Conversational Finance
VIANAI
Documentation
Conversational Finance

    Install hila

    hila is an infrastructure-agnostic platform that can be deployed on any cloud infrastructure, whether it is public or private, such as AWS, Azure, GCP, OCI, or on-premises. As long as the infrastructure supports Kubernetes, hila can be deployed on it.

    These instructions describe how to deploy hila on a single-node Kubernetes cluster (k3s microstack) or a multi-node Kubernetes cluster (Full install).

    Minimum requirements

    To deploy hila in your environment, the following resources must be installed.

    Name Version
    Kubernetes 1.27+
    Helm 3.7 / 3.8 / 3.9
    kubectl 1.27+
    curl latest
    Kustomize 4.5
    Python (Optional) 3.11

    Deploying

    Deploying hila involves the following main steps:

    Create a cluster on your provider

    These instructions describe how to create a cloud cluster on the following cloud providers for you to run hila.

    OnPrem

    Follow these steps to install the platform in a local Kubernetes cluster.

    Prerequisites

    1. The following list shows what must already be configured before starting with the platform configuration.

      • It is necessary to previously configure a shared storage that is supported by Kubernetes, for example, configuring it through Glusterfs, CephFS, among others. To verify the configuration, the following link can be used as a reference. Storage Classes

      • The following node characteristics are recommended for small clusters.

        Node Total nodes CPU RAM Disk Required
        Default node 3 4 16 GB 200 GB Yes
        Job Pool 0 - 3 4 16 GB 200 GB Yes

      • In the values-files folder, there is the main-nfs-pvc.yaml file, it must be updated to the required space, at least 500 GB.

      • The nodes must have taints and labels configured as follows:

        Configuration Key Value Node
        Label job pool-1 Job Pool
        Configuration Effect Key Value Node
        Taint NoSchedule job pool-1 Job Pool
      • You must have an A record and a CNAME record <*.dns.record.site>, this should redirect to record A.
      • Install a software load balancer that provides an ingress to access those services. That entry needs an IP range or subnet. It also requires strictArp network. In this guide we will use MetalLB for this purpose.

      • To access the platform, you need a DNS record point to the address given to MetalLB load balancer.

      • The platform can only be accessed securely through https protocol. You’ll need to create a certificate (public/private TLS key). Wildcard Certificate is recommended

    Previous configurations

    Install MetalLB

    1. Enable strict ARP mode.

      kubectl edit configmap -n kube-system kube-proxy

      and set:

      apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
mode: "ipvs"
ipvs:
   strictARP: true

    2. Install MetalLB by manifest

      kubectl apply -f
https://raw.githubusercontent.com/metallb/metallb/v0.13.4/config/manifests/metallb-native.yaml

    3. Configure the MetalLB to use the IP address that you already have on the server following this guide.

    Platform installation

    1. You must enter in the Kubernetes context that you want to install the platform.

      kubectl config current-context

    2. Go to the k8s folder and locate the values-files/customer-stack-values-withoutGPU.yaml file and necessarily change the hostname to the previously created record. If you want to use GPU on your configuration use the file called customer-stack-values-with-GPU.yaml.

      hostname: <dns.record.site>

    3. In the same file, it is highly recommended to change the administrator password.

      vianaiRootUserPassword:
database_user: postgres
database_pass: Change4Security
root_user: vianai
root_pass: Change4Security

    4. If you change the password, you must also change the password hash used by Elasticsearch.

      es:
  hash_password:
$2a$12$Agrv6M2Jfg5G1mj4jZNsVOxFwnrLUyfZAgwRaEsBRBCcoHlp0u5hC
#Change4Security

      To create a new hash you can use this options:

      • You can use the script that it’s located on the k8s folder called hash_password.py and run it like this.

        python hash_password.py NewPassword

      • Visit the follow link to create a new for your password. https://bcrypt-generator.com

    5. If you have changed the administrator password, you must do the same in the values-files/postgresql-chart-values.yaml file, otherwise, you can skip this step.

      postgresqlPassword: Change4Security
postgresqlPostgresPassword: Change4Security

    6. Locate the file install-stack-on-k8s.sh and execute the following command with the following parameters.If you want to use GPU on your configuration use the file called customer-stack-values-withGPU.yaml.

      ./install-stack-on-k8s.sh <Your-DNS> values-files/customer-stack-valueswithoutGPU.yaml my-context

    7. Minutes after the script is executed, you will notice a message that tells you that you must update your DNS, the IP that you must place is the ingress IP that was configured on the load balancer.

    8. Once the record has updated and also responds to the ingress IP, press enter to continue with the installation.

    9. The platform can take a couple of minutes to be up and running, to monitor the progress it is recommended to execute the following command.

      $ watch -n2 kubectl get pods --all-namespaces

    10. Once all the pods are in the running state, you can verify the platform by accessing the established route.

      "https://ui.$domain_name/"

    AWS

    Create a cloud cluster on the AWS platform.

    Requirements

    • You must have received from your Vianai contact the script called aws-cluster.sh.

    Steps

    1. At the top of the aws-cluster.sh script, edit the following values. An example is given in the following image.

      CLUSTER_NAME Enter your cluster name.
      ZONE Enter your zone.

      aws-1

    2. Run the aws-cluster.sh script. The terminal shows the logs as it creates the resources. The entire process takes up to 20 minutes, and the script ends automatically when the all the resources have been created.

    Azure

    Create a cloud cluster on the Azure platform.

    Requirements

    • You must have received from your Vianai contact the script called azure-cluster.sh.

    Steps

    1. At the top of the azure-cluster.sh script, edit the following values. An example is given in the following image.

      TYPE internal
      PREFIX Cluster name
      LOCATION Cloud provider region
      PASSWORD Password of the bastion host (only required on internal clusters)

      azure-1

    2. Scroll to the bottom of the script and set your node pool details in the lines that begin with “create_pool”. An example of the format appears in the following image.

      azure-2

    3. Authenticate to Azure with the AZ login command and follow the prompts as directed.

      azure-3

    4. Run the azure-cluster.sh script. As the script runs, it confirms the creation of each resource, as shown in the following example.

      azure-4

    5. When the script finishes, navigate to the Azure console, select your cluster, then click “Connect”. Two commands appear for you to enter: the first sets your subscription, and the second gets your cluster credentials. You will use these two scripts to configure the environment in which the installer runs.

      azure-5

    GCP

    Create a cloud cluster on the GCP platform.

    Requirements

    • You must have received from your Vianai contact the script called gcp-public-cluster.sh.

    Steps

    1. At the top of the gcp-public-cluster.sh script, edit the following values. An example is given in the following image.

      PROJECT_ID Enter your project ID.
      CLUSTER_NAME Enter your cluster name.
      ZONE Enter the region of your cluster.

      gcp-1

    2. Authenticate to Google Cloud using the gcloud auth login <email> command and follow prompts as directed.

    3. Run the gcp-public-cluster.sh script. As the script runs, it confirms the creation of each resource.

    4. When the script has completed, navigate to the Google Cloud console, select your cluster, then click “Connect”. Copy and run the given command (see example in the following image) to configure the environment where the installer will run.

      gcp-2

    OCI

    Create a cloud cluster on the OCI platform.

    Requirements

    • You must have received from your Vianai contact the script called oci-cluster.sh.

    Steps

    1. At the top of the oci-cluster.sh script, edit the following values. An example is given in the following image.

      COMPARTMENT_ID Enter your project ID.
      CLUSTER_NAME Enter your cluster name.

      oci-1

    2. Scroll to the bottom of the script and set your node pool details in the lines that begin with “create_pool”. An example of the format appears in the following image.

      oci-2

    3. Run the oci-cluster.sh script. As the script runs, it confirms the creation of each resource.

    4. Authenticate to OCI using the oci-setup config command and follow the prompts as directed.

    Install the tarball you receive from Vianai

    This section describes how to install the hila tarball on your local system.

    Requirements

    • Get the tarball from your Vianai sales contact.
    • You need access to the Kubernetes control plane.
    • You need a Linux host with a bash shell.
    • Your Linux host needs kubectl and helm applications installed.

    Steps

    1. Set the current kubectl context with your cloud provider.

    2. Unzip and install the tar file as follows:

      1. Navigate to the /platform/directory.

      2. Run tar zxvf vianai-platform-<#.#.#>.tar.gz, which unzips the tar file.

      3. Navigate to the vianai-platform folder and type ls -ltr to ensure all files unzipped correctly. There should be three items: charts, install.sh, and kustomize.

      4. Run the install script with the following series of commands:

        tar xzvf vianai-platform-<#.#.#>.tar.gz
        cd vianai-platform
        ./install.sh

      The platform is now installed on the cluster.

    3. Connect to the new platform as follows:

      1. Run kubectl get gateway -o yaml to view the platform URL. For example, monitoring.azure-base.vianai.site

      2. Run kubectl get svc -n istio-system to print out the Load Balancer external IP.

      3. Create a new DNS “A” record in your cloud provider. For example, for Azure:

        • azure-base.vianai.site
        • Copy the load Balancer IP and add to Routing

      4. Create a new CNAME record using the DNS name above.

      5. Allow for about 10 minutes for the DNS records to propagate and then connect to the Monitoring URL from the first step in this process.

      The following web page appears for you to log in to hila.

      lp

    Clone images to your private registry

    This section describes how to install and deploy Vianai container images into a private registry. The intended audience is customers with air-gapped, private cloud, or on-premise deployments.

    To perform these following steps your computer needs to be configured with python, the Docker engine, and Google SDK.

    Requirements

    Vianai provides:

    • Service account—A file containing credentials with read-only access for the Vianai container images in GCR (Google Cloud Registry).

    • Image map—A JSON-formatted file with a list of Vianai images.

    • Clone script—Python script to pull Vianai container images and transfer them to the target registry.

    You provide:

    • Google SDK—Google Cloud binaries allowing authentication to Google Cloud services. See list of required software and versions.

    • Storage—Recommend 1TB of temporary storage for Docker container to be stored until the process completes.

    Steps

    Use the following steps to clone the Vianai container repository.

    1. Extract the list of containers:

       python generate-image-map.py --version <VERSION> --output-file vianai-<VERSION>.json

      where VERSION should match the Vianai platform For example, for v3.1r1 the command may be:

       python generate-image-map.py --version 3.1r1 --output-file vianai-v3.1r1.json

      Note that you may not want or need all images provided in the image. Work with your Vianai Sales or Support representative if you want to remove unneeded images.

    2. Make sure the private registry is set up and Docker is authenticated. See the section “Registry Authentication” (below) for instructions to create the private registry and set up authentication specific to the target cloud provider.

    3. Create a docker secret so you can pull the image to your private registry.

      1. Create a file called secret.yaml with the following content, and replace the placeholder SECRET with your secret:

        apiVersion: v1
data:
   .dockerconfigjson: SECRET
metadata:
   name: secret-registry 
kind: Secret

      2. Add the secret to the default namespace with:

        kubectl apply -f secret.yaml -n default

      3. Add the secret to the knative namespace with:

        kubectl apply -f secret.yaml -n knative-serving

      4. When you run a job to pull the image, you must add the secret metadata name defined in the secret file as a value to the image_pull_secrets keyword as follows:

        [
   {
      "name": "string",
      "description": "string",
      "status": "active",
      "image_url": "string",
      "default_params": {
         "nodepool_label": "",
         "memory": 0.5,
         "memory_scale": "Gi",
         "cpu": 250,
         "cpu_scale": "m",
         "gpu": 0,
         "autoscaling_class": "kpa.autoscaling.knative.dev",
         "autoscaling_metric": "concurrency",
         "autoscaling_target": 200,
         "min_scale": 0,
         "max_scale": 1
         "image_pull_secrets": [
            "secret-registry"
         ]
      },
      "volume_mounts": {},
      "environment_variables": {},
      "port": 8080,
      "runtime_object": "knative"
   }
]

    4. Tag and push the containers to the new private registry:

       python import-images.py --map-file vianai-<VERSION>.json --dest-repo <DEST-REPO>

      where:

      • VERSION should match the Vianai platform
      • DEST_REPO must match the address for the target private registry

      For example, for v3.1r1 the command for a test repo may be:

       python import-images.py --map-file vianai-3.1r1.json --dest-repo testprivaterepo.azurecr.io

      While the command for a production AWS repo may be:

       python import-images.py --map-file vianai-3.1r1.json --dest-repo <AWS ACCT ID>.dkr.ecr.<REGION>.amazonaws.com

    5. Authorize access to the Vianai container repository:

      gcloud auth activate-service-account <ACCOUNT-NAME> --key-file=<YOUR-SERVICE-ACCOUNT-CREDS>.json

gcloud auth configure-docker us.gcr.io

      where:

      • ACCOUNT-NAME is the value provided in the client_email field of your service account file
      • YOUR-SERVICE-ACCOUNT-CREDS is provided in your service account file

    6. Set up WRITE access authorization for the private container registry.

    7. Transfer Vianai images using the clone script:

      python import-images.py --map-file <VIANAI-PROVIDED-IMAGE-MAP-FILE> --dest-repo <PARTNER-CONTAINER-REGISTRY>

      where:

      • VIANAI-PROVIDED-IMAGE-MAP-FILE is the location of the Vianai-provided image map file
      • PARTNER-CONTAINER-REGISTRY is provided in your service account file

    Repository Authentication

    Azure

    • See instructions for creating a container registry in Azure.
    • Authenticate via command line: 
        az login --use-device-code
  az acr login -n TESTPRIVATEREPO --expose-token

      where TESTPRIVATEREPO is the name for your Azure container registry (replace with actual registry name)

    AWS

    • See instructions for creating a container registry in create ECS.

    • Authenticate via command line:

        export AWS_ACCESS_KEY_ID=xxxxxx
  export AWS_SECRET_ACCESS_KEY=yyyyy

  aws ecr get-login-password --region REGION | docker login --username AWS --password-stdin AWS_ACCT_ID.dkr.ecr.REGION.amazonaws.com

      where:

      • REGION matches your ECS region
      • AWS_ACCT_ID identifies your AWS account

    GCP

    • See instructions for creating a container registry in create GCP.

    • Authenticate via command line:

        gcloud auth activate-service-account <ACCOUNT-NAME> --key-file=<YOUR-SERVICE-ACCOUNT-CREDS>.JSON
  gcloud auth configure-docker us.gcr.io

      where:

      • ACCOUNT-NAME matches your GCP registry account name region
      • YOUR-SERVICE-ACCOUNT-CREDS identifies your GCP service account

    Standard hila install

    Standard install pulls hila containers from hila’s cloud package registry and includes everything you need to install an instance of hila, including an SSH certificate, DNS registration. If you want to install with your own certificate, click the Custom Cert button. If you want to install with a custom certificate and install hila from a local registry, click Custom Cert & Repo.

    Install hila with a custom certificate

    You can install hila with your own custom certificate. As with standard install, this pulls hila packages from hila’s cloud package registry but it applies your custom certificate to the process. If you want to install with a custom certificate and install hila from a local registry, click Custom Cert & Repo.

    Install hila with a custom certificate and repo

    You can install hila with you own custom certificate and download hila’s packages to install them from a local machine.

    Install hila in an on-prem, air-gapped environment

    If you need to install hila in an air-gapped environment, you can install hila with your own custom certificate and download hila’s packages to install them from a local registry.

    Whitelist URLs

    In an air-gapped environment, the following URLs need to be whitelisted for hila to function.

    For install

    • us-central1-docker.pkg.dev
    • launchpad.vianai.site

    For configuraiton

    • goldensql-service.wonderfulcliff-ce61ff72.eastus.azurecontainerapps.io

    For OpanAI or Azure Open AI LLMs

    If you will be using OpenAI or Azure OpenAI LLMs in your air-gapped environment, you must whitelist the following URLs:

    • OpenAI
      • https://api.openai.com/v1/chat/completions
    • Azure OpenAI
      • https://hila-gpt.openai.azure.com
      • https://hila-benchmarking.openai.azure.com

    Create ssh keys to access the VM

    1. In a terminal on your local machine, run ssh-keygen to create a new key pair.

    2. Press enter to accept the default location for the key pair, or enter a filename.

    3. Press enter to accept the default passphrase, or enter a passphrase.

    4. Press enter to confirm the passphrase.

    5. The public key is saved in the ~/.ssh directory with the default name or the name you provided.

    6. Open the public key file and copy the contents to the ssh public key field when you create the VM.

    Create a VM

    Create a VM with the follow minimum requirements:

    CPUs 16
    RAM 64 GB
    Disk 500 MB
    OS Ubuntu 22.04 LTS
    Networking • HTTPS (for end user access)
    • SSH enabled (or similar method so you can upload the script to the VM)
    • Note the IP address for use in the installation process.
    • For convenience and consistency, create the VM with the username ubuntu. If you use a different username, replace ubuntu with your username in the following steps.

    Install hila

    1. From a terminal on your local machine, ssh into the VM, making sure to edit YOUR_PRIVATE_KEY_FILE to your private key file and IP_ADDRESS to your VM’s IP address:

      ssh -i "~/.ssh/<YOUR_PRIVATE_KEY_FILE>.key" -o StrictHostKeyChecking=no ubuntu@<IP_ADDRESS> -t bash

    2. Run the following export commands to set up the variables for the install, updating the values with UPPERCASE letters to match your environment.

      export api_key=YOUR_API_KEY
export version=HILA_BUILD_TO_INSTALL (ex: 3.2.0-r.2)
export domain=YOUR_DNS_DOMAIN
export datadir=/home/ubuntu/data
export cloud_provider=CLOUD_PROVIDER [ aws|azure|gcp|oci ]
export admin_email=YOUR_EMAIL
      • Important: The email is important because it is used to send a one-time login email to the admin user. The admin then sets up a password as then has access to hila.

    3. Pull the latest install scripts from launchpad with the following command:

      wget --header "x-api-key:$api_key" -q -O - 'https://webservices.launchpad.vianai.site/v1/stacks-installers' | tar -xzv

    4. Install webfsd, which functions as a server for your VM.

      sudo apt update && sudo apt install webfs

      Note: If you don’t install this server, you will get an error later when you verify the web server.

    5. Run the pre-check script to gather the VM details necessary to verify it is suitable to install hila.

      sudo ./cluster-creation-scripts/k3s_vm_precheck.sh api_key=$api_key

      output1.png

      • The recommended values are in the column on the right.

      • If you don’t run with sudo, you will get a permissions denied error.

    6. The pre-check script starts the webfsd server, so it holds the prompt. To test the web server, open a new terminal window, ssh into the VM, and run the following command:

      curl --insecure https://localhost:443

      • If you did not install webfsd, you will see an error instead of this output.

      • If the web server is working, you will get output similar to the following:

        curl-443.png

    7. In the terminal with the webfsd server running, press Ctrl+C to stop the webfsd server.

    8. Run the install command.

      ./cluster-creation-scripts/k3s-microstack.sh vm_setup_only=run cloud_provider=$cloud_provider custom_cert=no custom_repo=no cluster_name=$HOSTNAME admin_email=$admin_email datadir=$datadir dns_domain=$domain api_key=$api_key image_branch=$version

      • If you are prompted for values, press Enter to accept defaults.

      • After this command finishes, it can take up to 30 minutes for you to get the one-time login email.

      • To monitor the progress of the pod install, open a new terminal window to the VM and enter the following command:

        watch -n 2 kubectl get pods

      • You can also monitor when the certificate goes true in another terminal window with this command:

        watch -n 2 kubectl get certificates -A

    9. When the install is complete, you will receive an email with a one-time login link.

    10. Click the link in the email to set up your password and log in to hila.

    Configure LLMs

    You must configure LLMs with your own API tokens. For more information, see LLM configuration.

    Install hila

    1. Create your certificate and register the A and CNAME DNS records, making sure the records point to the VMs IP address. To verify, ping the VM:
      • ping <VM_IP_ADDRESS> to verify the A record.
      • ping monitoring.<VM_IP_ADDRESS> to verify the CNAME record.

    2. Copy your new certificate and key files to VM in /home/ubuntu:

      scp -i ~/.ssh/<YOUR_PRIVATE_KEY_FILE>.key <CERTIFICATE_FILE> ubuntu@<VM_IP_ADDRESS>:/home/ubuntu/

    3. From a terminal on your local machine, ssh into the VM, making sure to edit YOUR_PRIVATE_KEY_FILE to your private key file and IP_ADDRESS to your VM’s IP address:

      ssh -i "~/.ssh/<YOUR_PRIVATE_KEY_FILE>.key" -o StrictHostKeyChecking=no ubuntu@<IP_ADDRESS> -t bash

    4. Run the following export commands to set up the variables for the install, updating the values with UPPERCASE letters to match your environment.

      export api_key=YOUR_API_KEY
export version=HILA_BUILD_TO_INSTALL (ex: 3.2.0-r.2)
export domain=YOUR_DNS_DOMAIN
export datadir=/home/ubuntu/data 
export cert_file_path=CERTIFICATE_FILE
export key_file_path=KEY_FILE
export cloud_provider=CLOUD_PROVIDER [ aws|azure|gcp|oci ]
export admin_email=YOUR_EMAIL

    5. Pull the latest install script from launchpad with the following command:

      wget --header "x-api-key:$api_key" -q -O - 'https://webservices.launchpad.vianai.site/v1/stacks-installers' | tar -xzv

    6. Install webfsd, which functions as a server for your VM.

      sudo apt update && sudo apt install webfs

      Note: If you don’t install this server, you will get an error later when you verify the web server.

    7. Run the pre-check script to gather the VM details necessary to verify it is suitable to install hila.

      sudo ./cluster-creation-scripts/k3s_vm_precheck.sh api_key=$api_key domain=$domain cert_file=$cert_file_path key_file=$key_file_path

      • The recommended values are in the column on the right.

      • If you don’t run with sudo, you will get a permissions denied error.

    8. The pre-check script starts the webfsd server, so it holds the prompt. To test the web server, open a new terminal window, ssh into the VM, and run the following command:

      curl --insecure https://localhost:443

      • If you did not install webfsd, you will see an error instead of this output.

      • If the web server is working, you will get output similar to the following:

        curl-443.png

    9. Run the install command.

      ./cluster-creation-scripts/k3s-microstack.sh vm_setup_only=run cloud_provider=$cloud_provider custom_cert=yes cert_file=$cert_file_path cert_key_file=$key_file_path custom_repo=no cluster_name=$HOSTNAME admin_email=$admin_email datadir=$datadir dns_domain=$domain api_key=$api_key image_branch=$version

      • If you are prompted for values, press Enter to accept defaults.

      • After this command finishes, it can take up to 30 minutes for you to get the one-time login email.

      • To monitor the progress of the pod install, open a new terminal window to the VM and enter the following command:

        watch -n 2 kubectl get pods

      • You can also monitor when the certificate goes true in another terminal window with this command:

        watch -n 2 kubectl get certificates -A

    10. When the install is complete, you will receive an email with a one-time login link.

    11. Click the link in the email to set up your password and log in to hila.

    Configure LLMs

    You must configure LLMs with your own API tokens. For more information, see LLM configuration.

    Install hila

    1. Create your certificate and register the A and CNAME DNS records, making sure the records point to the VMs IP address. To verify, ping the VM:
      • ping <VM_IP_ADDRESS> to verify the A record.
      • ping monitoring.<VM_IP_ADDRESS> to verify the CNAME record.

    2. Copy your new certificate and key files to VM in /home/ubuntu:

      scp -i ~/.ssh/<YOUR_PRIVATE_KEY_FILE>.key <CERTIFICATE_FILE> ubuntu@<VM_IP_ADDRESS>:/home/ubuntu/

    3. From a terminal on your local machine, ssh into the VM, making sure to edit YOUR_PRIVATE_KEY_FILE to your private key file and IP_ADDRESS to your VM’s IP address:

      ssh -i "~/.ssh/<YOUR_PRIVATE_KEY_FILE>.key" -o StrictHostKeyChecking=no ubuntu@<IP_ADDRESS> -t bash

    4. Run the following export commands to set up the variables for the install, updating the values with UPPERCASE letters to match your environment.

      export api_key=YOUR_API_KEY
export version=HILA_BUILD_TO_INSTALL (ex: 3.2.0-r.2)
export domain=YOUR_DNS_DOMAIN
export datadir=/home/ubuntu/data 
export azure_repo=customerrepo.azurecr.io
export cert_file_path=CERTIFICATE_FILE
export key_file_path=KEY_FILE
export cloud_provider=CLOUD_PROVIDER [ aws|azure|gcp|oci ]
export admin_email=YOUR_EMAIL

    5. Pull the latest install script from launchpad with the following command:

      wget --header "x-api-key:$api_key" -q -O - 'https://webservices.launchpad.vianai.site/v1/stacks-installers' | tar -xzv

    6. Install webfsd, which functions as a server for your VM.

      sudo apt update && sudo apt install webfs

      Note: If you don’t install this server, you will get an error later when you verify the web server.

    7. Run the pre-check script to gather the VM details necessary to verify it is suitable to install hila.

      sudo ./cluster-creation-scripts/k3s_vm_precheck.sh api_key=$api_key domain=$domain cert_file=$cert_file_path key_file=$key_file_path

      • The recommended values are in the column on the right.

      • If you don’t run with sudo, you will get a permissions denied error.

    8. The pre-check script starts the webfsd server, so it holds the prompt. To test the web server, open a new terminal window, ssh into the VM, and run the following command:

      curl --insecure https://localhost:443

      • If you did not install webfsd, you will see an error instead of this output.

      • If the web server is working, you will get output similar to the following:

        curl-443.png

    9. Download and install the Azure CLI as described in Install other tools.

    10. Download and install gcloud as described in Install other tools.

    11. Install Docker as described in Install other tools.

    12. Get the transfer scripts by running each of the following commands:
      • wget --header "x-api-key:$api_key" -q -O - "https://webservices.launchpad.vianai.site/v1/generate-transfer?image_branch=$version&cloud_provider=azure&dest_repo=$azure_repo" | tar -xzv
      • ./transfer.sh

    13. Run the install command.

      ./cluster-creation-scripts/k3s-microstack.sh vm_setup_only=run cloud_provider=$cloud_provider custom_cert=yes cert_file=$cert_file_path cert_key_file=$key_file_path custom_repo=no cluster_name=$HOSTNAME admin_email=$admin_email datadir=$datadir dns_domain=$domain api_key=$api_key image_branch=$version

      • If you are prompted for values, press Enter to accept defaults.

      • After this command finishes, it can take up to 30 minutes for you to get the one-time login email.

      • To monitor the progress of the pod install, open a new terminal window to the VM and enter the following command:

        watch -n 2 kubectl get pods

      • You can also monitor when the certificate goes true in another terminal window with this command:

        watch -n 2 kubectl get certificates -A

    14. When the install is complete, you will receive an email with a one-time login link.

    15. Click the link in the email to set up your password and log in to hila.

      1. Run Install (will ask a few questions press enter to skip since not creating VM) a. ./cluster-creation-scripts/k3s-microstack.sh vm_setup_only=run cloud_provider=azure custom_cert=yes cert_file=$cert_file_path cert_key_file=$key_file_path custom_repo=yes dest_repo=$azure_repo cluster_name=$HOSTNAME admin_email=admin_email datadir=$datadir dns_domain=$domain api_key=$api_key image_branch=$version

    Configure LLMs

    You must configure LLMs with your own API tokens. For more information, see LLM configuration.

    Install hila

    1. Create your certificate and register the A and CNAME DNS records, making sure the records point to the VMs IP address. To verify, ping the VM:
      • ping <VM_IP_ADDRESS> to verify the A record.
      • ping monitoring.<VM_IP_ADDRESS> to verify the CNAME record.

    2. Copy your new certificate and key files to VM in /home/ubuntu:

      scp -i ~/.ssh/<YOUR_PRIVATE_KEY_FILE>.key <CERTIFICATE_FILE> ubuntu@<VM_IP_ADDRESS>:/home/ubuntu/

    3. From a terminal on your local machine, ssh into the VM, making sure to edit YOUR_PRIVATE_KEY_FILE to your private key file and IP_ADDRESS to your VM’s IP address:

      ssh -i "~/.ssh/<YOUR_PRIVATE_KEY_FILE>.key" -o StrictHostKeyChecking=no ubuntu@<IP_ADDRESS> -t bash

    4. Run the following export commands to set up the variables for the install, updating the values with UPPERCASE letters to match your environment.

      export api_key=YOUR_API_KEY
export version=HILA_BUILD_TO_INSTALL (ex: 3.2.0-r.2)
export domain=YOUR_DNS_DOMAIN
export datadir=/home/ubuntu/data 
export cust_repo=localhost:5000
export cert_file_path=CERTIFICATE_FILE
export key_file_path=KEY_FILE
export cloud_provider=CLOUD_PROVIDER [ aws|azure|gcp|oci ]
export admin_email=YOUR_EMAIL

    5. Pull the latest install script from launchpad with the following command:

      wget --header "x-api-key:$api_key" -q -O - 'https://webservices.launchpad.vianai.site/v1/stacks-installers' | tar -xzv

    6. Install webfsd, which functions as a server for your VM.

      sudo apt update && sudo apt install webfs

      Note: If you don’t install this server, you will get an error later when you verify the web server.

    7. Run the pre-check script to gather the VM details necessary to verify it is suitable to install hila.

      sudo ./cluster-creation-scripts/k3s_vm_precheck.sh api_key=$api_key domain=$domain cert_file=$cert_file_path key_file=$key_file_path

      • The recommended values are in the column on the right.

      • If you don’t run with sudo, you will get a permissions denied error.

    8. The pre-check script starts the webfsd server, so it holds the prompt. To test the web server, open a new terminal window, ssh into the VM, and run the following command:

      curl --insecure https://localhost:443

      • If you did not install webfsd, you will see an error instead of this output.

      • If the web server is working, you will get output similar to the following:

        curl-443.png

    9. Download and install gcloud as described in Install other tools.

    10. Install Docker as described in Install other tools.

    11. Get the transfer scripts by running each of the following commands:
      • wget --header "x-api-key:$api_key" -q -O - "https://webservices.launchpad.vianai.site/v1/generate-transfer?image_branch=$version&cloud_provider=azure&dest_repo=$azure_repo" | tar -xzv
      • ./cluster-creation-scripts/local-registry.sh install_podman=yes datadir=$datadir
      • ./transfer.sh

    12. Run the install command.

      ./cluster-creation-scripts/k3s-microstack.sh vm_setup_only=run cloud_provider=$cloud_provider custom_cert=yes cert_file=$cert_file_path cert_key_file=$key_file_path custom_repo=yes dest_repo=$cust_repo cluster_name=$HOSTNAME admin_email=$admin_email dns_domain=$domain api_key=$api_key image_branch=$version

      • If you are prompted for values, press Enter to accept defaults.

      • After this command finishes, it can take up to 30 minutes for you to get the one-time login email.

      • To monitor the progress of the pod install, open a new terminal window to the VM and enter the following command:

        watch -n 2 kubectl get pods

      • You can also monitor when the certificate goes true in another terminal window with this command:

        watch -n 2 kubectl get certificates -A

    13. When the install is complete, you will receive an email with a one-time login link.

    14. Click the link in the email to set up your password and log in to hila.

    Configure LLMs

    You must configure LLMs with your own API tokens. For more information, see LLM configuration.

    Install other tools

    You only need to install these one time for your VM.

    • Download and install the Azure CLI. 
      curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
az login --use-device-code
az acr login --name customerrepo
    • Download and install the Google Cloud CLI 
      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor \
     -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] \
     https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee \
     -a /etc/apt/sources.list.d/google-cloud-sdk.list
sudo apt-get update && sudo apt-get -y install google-cloud-cli
gcloud auth login
    • Install Docker 
      sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo \
    "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \ 
    https://download.docker.com/linux/ubuntu \
    $(. /etc/os-release && echo "$VERSION_CODENAME") 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-buildx-plugin docker-compose-plugin
sudo usermod -aG docker ${USER}
groups ### make sure the user has this in docker group. If not, try rebooting the VM.

    Upgrade to a new hila release

    You can upgrade to a new hila release by following these steps. They are the same for all install methods.

    1. SSH into the VM where hila is installed.

    2. Create a directory to store the existing files. For example,

      sudo mkdir /usr/local/old_release

    3. In the /home/ubuntu directory, move all the files to the directory you created in the previous step. For example,

      sudo mv * /usr/local/old_release

    4. Re-run the install process as described above as you originally installed hila, but update the version number to the new release.

    TABLE OF CONTENTS
    Copyright © 2025
    Vianai Systems, Inc.
    All rights reserved.