KLapper Deployment Guide

KLapper Deployment Guide





KLapper Deployment Guide

v2.0








Introduction

This document details the deployment process for our KLapper virtual assistant builder.

Prerequisites

The deployment process is on Azure Cloud, we need the following prerequisites:

  1. Azure Cloud Subscription.
  2. Azure Subscription with following Resource Providers enabled:
    1. Microsoft.BotService
    2. Microsoft.CognitiveServices
    3. Microsoft.DocumentDB
    4. Microsoft.Web
  3. Azure Cloud Admin account with Subscription level privileges.
  4. Understanding Azure Cloud Network.
  5. Windows PowerShell 7.4.7 - https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.5
  6. Azure PowerShell Module (13.4.0)
  7. Minimum permission required:
    1. Azure subscription access
    2. Resource creation – Contributor/Owner at the subscription level or resource group level
    3. Azure OpenAI service – Cognitive Services Contributor
    4. Key management – Cognitive Services User
    5. Resource deletion – Contributor/Owner at the resource group level
  8. PowerShell execution policy to run unsigned script files
  9. Whitelist following domains – This is required for downloading installation files and licensing check:
    1. https://admin.klapper.ai
    2. *.klapper.ai
    3. https://${BuilderServiceName}.azurewebsites.net/builderapi/*
    4. https://${BuilderServiceName}.scm.azurewebsites.net
    5. https://${FMApiServiceName}.scm.azurewebsites.net
    6. https://${FrameworkServiceName}.scm.azurewebsites.net
    7. https://klapperv2.azurecr.io

Azure Requirements

These requirements will get provisioned by the PowerShell script

  1. App Service Plan
    1. Tier – PremiumMV3
    2. OS - Windows
  1. App Service Plan
    1. Tier – PremiumMV3
    2. OS - Linux
  1. Builder
    1. Azure App Service 
  1. File Manager
    1. Azure App Service
  1. Framework
    1. Azure App Service
  1. Document Conversion
    1. Azure App Service
  1. Azure Open AI Service
    1. Model GPT-4o
    2. 125K token quota is required
  1. Database
    1. Azure Cosmos Mongo DB
    2. Azure Cosmos NoSQL DB
    3. Pricing model – Provisioned throughput
    4. Performance tier - Standard
  1. Azure Entra App
  2. Azure Translation Service
    1. Blob Storage

KLapper Connector Requirements

NetDocuments

  1. NetDocuments Administrator
  2. Repository Service Account

iManage (On-Premises)

  1. iManage Administrator
  2. iManage Application

iManage (Online)

  1. iManage Administrator
  2. Request an iManage Application from iManage Support
SharePoint
  1. SharePoint Administrator
  2. Azure Global Administrator
  3. Azure App Registration
  4. SharePoint Application

KLapper Connecting to On Premise Systems

To fully leverage the capabilities of KLapper, we should be ready with the connectivity requirements to below platforms

  1. SQL Server – This can be residing in on premise network
  2. SharePoint – This can be on premise SharePoint instance or online
  3. iManage – This can be on premise instance or cloud
  4. NetDocuments

Connecting to On-Premises SQL Server/SharePoint/iManage

KLapper is deployed in Azure App Services. To connect an app service deployed in Azure to on-premises systems like SQL/SharePoint/iManage you can follow one of the approaches outlined below


Hybrid Connection

  1. Uses Azure Relay service
  2. Doesn't require changes to network configuration
  3. Doesn't expose on-premises systems to the internet
  4. Suitable for simple, single-connection scenarios

Azure Virtual Network Integration

  1. Connect App Service to an Azure VNet
  2. Use VNet-to-VNet connection or ExpressRoute to connect Azure VNet to on-premises network
  3. Provides more comprehensive network integration

Requirements

  1. App Service Plan: Standard, Premium, or Isolated tier
  2. Azure VNet Gateway
  3. On-premises VPN device or ExpressRoute circuit

Azure ExpressRoute


  1. Private connection between Azure datacenter and on-premises infrastructure
  2. Doesn't go over the public internet
  3. Higher bandwidth and lower latency than typical VPN connections

Requirements

  1. ExpressRoute circuit
  2. ExpressRoute Gateway in Azure VNet
  3. Compatible network equipment or partnership with an ExpressRoute connectivity provider

Site-to-Site VPN

  1. IPsec VPN tunnel between Azure VNet and on-premises network
  2. Goes over the public internet, but traffic is encrypted

Requirements

  1. VPN Gateway in Azure VNet
  2. On-premises VPN device with a public IP address

Azure SQL Managed Instance with Azure Arc

  1. Deploy Azure SQL Managed Instance to on-premises environment
  2. Manage through Azure portal, but data remains on-premises

Requirements

  1. Azure Arc-enabled servers
  2. Suitable on-premises infrastructure to host SQL Managed Instance

Installation

PowerShell Setup

  1. Install PowerShell 7.4.7 from - https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.5
  2. Open PowerShell as an Administrator
  3. Verify the proper Windows PowerShell version is installed using this script (7.4.7)
    1. $PSVersionTable.PSVersion
  4. Run the script below
    1. Set-ExecutionPolicy Unrestricted -Force
  5. Run the script below and check the Azure PowerShell module version is 13.4.0
    1. Get-InstalledModule -Name Az -AllVersions | Select-Object Name, Version
      1. If the incorrect version is installed, use this to uninstall that version before downloading 13.4.0:
        1. Uninstall-Module -Name Az -Version {Version Number}
  6. To install the specific version use below command
    1. Install-Module Az -RequiredVersion 13.4.0 -Scope CurrentUser -Repository PSGallery
  7. Run the script below
    1. Connect-AzAccount

Installation Process

  1. Download the installation zip file shared. 

    1. Extract zip file to the folder in a Windows 10, 11 or 2019 server with PowerShell configured 

    1. Make sure the user performing installation has Provisioning privileges in Azure. 

    1. Open Inputs.ps1 and fill in the details. Use Only Lowercase Alphabets and Numbers for resource names. 

Variable Name

Description

$licenseKey

Please use the license key provided to you by the support team

  $adminFirstName
  First name of the Administrator who manages KLapper
  $adminLastName
  Last name of the Administrator who manages KLapper
  $adminEmail
  Email address of the Administrator who manages KLapper


$tenantId




Azure tenant id




$subscriptionId




Azure subscription id




$location




Azure location (Ex: eastus, eastus2 etc)




$resourceGroupName




Azure resource group under which KLapper services to be provisioned


  $cosmosMongoDBName
  This will be used to provision Azure Cosmos MongoDB account name
  $cosmosMongoDatabase
  This will be used to provision a new Database inside the Cosmos MongoDB account
  $cosmosNoSqlDBName
  This will be used to provision a new Azure Cosmos NoSql account name
  $cosmosNoSqlDatabase
  This will be used to provision a new Database inside of the Cosmos NoSql account
  $appServiceWindowsPlanName
  Windows app service plan name
  $appServiceLinuxPlanName
  Linux app service plan name


$fmApiAppServiceName




KLapper file manager app service name


  $frameworkAppServiceName
  KLapper framework app service name
  $docConversionAppServiceName
  KLapper document conversion service name
  $openAIServiceName
  Azure Open AI service name
  $entraAppName
 Azure Entra app name
  $builderUrl
  Azure Entra app name
  $containerName In case if you are planning to add a custom domain for the KLapper builder app service. Please fill in or it will be the builder app service name Ex: https://appService.azurewebsites.net
  $translatorName Translation service name


    1. Navigate to the extracted folder in PowerShell 

    1. Run Provisioning.ps1 

    • NOTE – During provisioning if there are any errors related to creating resource, the Press Ctrl + C and re run the script. 

    • NOTE – Errors related to Open AI Deployment or Entra App related you can ignore and we can follow the manual steps to provision those resources 

    1. Copy the ssh command from the window 

    1. Open Command window as administrator 

    1. Paste the ssh command 

    1. Enter password 

    1. Execute below commands 

    • sudo apt install unzip 

    • unzip deploy-klapper.zip -d deploy-klapper 

    • cd deploy-klapper 

    • chmod +x deploy-klapper.sh 

    • ./deploy-klapper.sh 

    • Enter Y 

    1. Script will stop 

    1. Type “exit” to exit ssh session 

    1. Paste the ssh command (copied from step 7) 

    1. Execute the commands below 

    • cd deploy-klapper 

    • ./deploy-klapper.sh 

    • Enter Y 

    • Enter a NEW mongo db admin password (Only alphanumeric characters) 

    • Enter a NEW mongo db user password (Only alphanumeric characters) 

    1. NVIDIA driver installed. Please reboot the system by pressing Restart from the Virtual Machine on Azure to continue. 

    1. Start another SSH session after the VM restarts 

    1. Paste the ssh command (copied from step 7) 

    1. Execute the commands below 

    • cd deploy-klapper 

    • ./deploy-klapper.sh 

    • Run MongoDB setup script (install-klapper-db-v1.2.sh)? [Y/N]: Enter N 

    • Do you want to create the ENV files? [Y/N]: Y 

    • Enter AZURE_COSMOS_DB_HOST: Copy from azure portal or from the script PowerShell 

    • Enter AZURE_COSMOS_DB_KEY: Copy from azure portal or from the script PowerShell 

    • Enter AZURE_COSMOS_DB_NAME: Copy from input file 

    • Enter CONTAINER_ENV [default: prod]: prod 

    • Enter MONGODB_HOST: <<Enter VM IP Address or HostName>>:20251 

    • Enter MONGODB_PASSWORD: <<Enter Password>> 

    • Login into docker using klapperv2.azurecr.io. 

    • Username – we will share during the meeting 

    • Password – we will share during the meeting 

    • Once installation is completed – enter below command to check the service status 

    • docker ps –a 

    1. Exit SSH session and go back to the folder where we have the PS1 script files 

    1. Open inputs.ps1 in notepad and fill in below details 

    • $mongoHostname – <<VM IP Address/HostName>> 

    • $mongoPassword <<Input the password>> 

    1. Run PostProvisioning.ps1 

    Post installation 

    Upgrade Docker in KLapper VM 

    1. Open the KLapper VM in PowerShell as an admin, using the SSH command from the installation 

    1. Type the following commands 

    • cd deploy-klapper 

    • docker compose -f docker-compose-fm.yaml down 

    • docker pull klapperv2.azurecr.io/klapper-fm-app:prod 

    • docker restart klapper-nginx 

    1. Finally restart the FM API Web Service from Azure 

    2. Verify that the docker services are running by using the command

      1. docker ps -a

    1. Once completed, the docker will be updated 

Enable NoSQL Features in CosmosDB

  1. Open Azure Portal
  2. Open the newly created resource group
  3. Open the Cosmos NoSQL DB
  4. From left pane - Expand "Settings" - Select Features
  5. Enable below features
    1. Full-Text & Hybrid Search for NoSQL API (preview)
    2. Vector Search for NoSQL API

Scale Up The BuilderAPI

  1. Open Azure Portal
  2. Open KLapper resource group
  3. Open the KLapper Builder App Service
  4. Click Settings, from the left-panel, then Scale up
  5. Change the plan to Premium v3 P1mv3

Grant Permission to Entra App

Grant “Contribute” access to Entra App on the resource group, so KLapper can dynamically provision Azure Bot Services as part of assistant creation process

  1. Open Azure portal
  2. Open “App Registrations”
  3. Search for the Entra App we created using PowerShell and open it
  4. From left menu, select “API Permissions”
  5. The following permissions should be requested, click “Grant admin consent”
    1. Select Microsoft Graph:
      1.  Application.ReadWrite.OwnedBy with type as “Application”
      2. User.ReadBasic.All with type as “Application”
    2.  Select SharePoint:
      1. AllSites.Read with type as “Delegated”
      2. Sites.Search.All with type as “Delegated”
    3. Select Azure SQL Database (only required for SQL connector skill)
      1. app_impersonation
  6. Go back to Azure portal home page
  7. Open “Resource Groups”
  8. Search for the Resource Group we created in Pre-Install step
  9. From left menu, select “Access control (IAM)
  10. Select “Role assignments”
  11. Click on “Add role assignment”
    1. Under Role tab -> Privileged administrator roles -> Select “Contributor”
    2. Under Members tab -> Assign access to “User, group or service principal”
    3. Click on “+ Select members”
    4. Search for the Entra App
    5. Click on “Select”
    6. Click on “Review + assign

Add SQL Permissions (Optional)

Log into the SQL using an AD account and execute the following script
  1. Create a contained database user for the Service Principal
    1. CREATE USER [AppRegistrationName] FROM EXTERNAL PROVIDER;
  2. Assign the desires roles to the Service Principal
    1. ALTER ROLE db_datareader ADD MEMBER [AppRegistrationName];
    2. ALTER ROLE db_datawriter ADD MEMBER [AppRegistrationName];
    3. ALTER ROLE db_owner ADD MEMBER [AppRegistrationName];

Configuring Builder Settings

  1. Open KLapper builder App Service URL
  2. Login using your email address
  3. Validate the settings

Troubleshooting

Azure Open AI Deployment Failed

In this case we must manually deploy gpt-4o model

  1. Open Azure portal
  2. Open the Resource Group
  3. Open the “Azure Open AI” service
  4. From left menu – Resource Management -> Open Model deployments
  5. Click on “Manage Deployments”
  6. Click on “Create new deployment”
  7. Enter name = “klapper-gpt-4o”
  8. Select model = “gpt-4o”
  9. Select Standard
  10. Select Content Filter = “Default”
  11. And create the deployment

Updating KLapper

  1. Go to global settings
  2.  Click update and proceed
    A screenshot of a software updateDescription automatically generated

How to add a custom domain for KLapper

  1. Head to the Azure portal, and navigate to the resource group that was created for KLapper
  2. Open the KLapper Builder App Service
  3. From the left column, select Custom domains

From the Add custom domain panel, select the following:

      Domain provider: All other domain services
      TLS/SSL certificate: App Service Managed Certificate      
      TSL/SSL type: SNI SSL      
      Then enter your desired domain name, validate all entries
      Finally press Validate then Add

Azure OpenAI Data Encryption

Azure OpenAI automatically encrypts your data when it's persisted to the cloud. Encryption protects your data and helps you meet your organizational security and compliance commitments. Azure OpenAI is part of Azure AI services. Azure AI services data is encrypted and decrypted using FIPS 140-2 compliant 256-bit AES encryption. Encryption and decryption are transparent, meaning encryption and access are managed for you. Your data is secure by default, and you don't need to modify your code or applications to take advantage of encryption.

Encryption Key Management

By default, your subscription uses Microsoft-managed encryption keys. There's also the option to manage your subscription with your own keys called customer-managed keys (CMK). CMK offers greater flexibility to create, rotate, disable, and revoke access controls. You can also audit the encryption keys used to protect your data.

Customer-managed keys with Azure Key Vault

Customer-managed keys (CMK), also known as Bring your own key (BYOK), offer greater flexibility to create, rotate, disable, and revoke access controls. You can also audit the encryption keys used to protect your data. You must use Azure Key Vault to store your customer-managed keys. You can either create your own keys and store them in a key vault, or you can use the Azure Key Vault APIs to generate keys. The Azure AI services resource and the key vault must be in the same region and in the same Microsoft Entra tenant, but they can be in different subscriptions.

Enable your Azure OpenAI resource's managed identity

  1. Go to your Azure AI services resource.
  2. On the left, under Resource Management, select Identity.
  3. Switch the system-assigned managed identity status to On.
  4. Save your changes and confirm that you want to enable the system-assigned managed identity.

Configure your key vault's access permissions

  1. In the Azure portal, go to your key vault.
  2. On the left, select Access policies.
    1. If you see a message advising you that access policies aren't available, reconfigure your key vault to use legacy access policies before continuing.
  3. Select Create.
  4. Under Key permissions, select Get, Wrap Key, and Unwrap Key. Leave the remaining checkboxes unselected.
  5. Select Next.
  6. Search for the name of your Azure OpenAI resource and select its managed identity.
  7. Select Next.
  8. Select Next to skip configuring any application settings.
  9. Select Create.

Enable customer-managed keys on your Azure OpenAI resource

  1. To enable customer-managed keys in the Azure portal, follow these steps:
  2. Go to your Azure AI services resource.
  3. On the left, under Resource Management, select Encryption.
  4. Under Encryption type, select Customer Managed Keys, as shown in the following screenshot.
After you enable customer-managed keys, you can specify a key to associate with the Azure AI services resource.
To specify a key as a URI, follow these steps:
  1. In the Azure portal, go to your key vault.
  2. Under Objects, select Keys.
  3. Select the desired key, and then select the key to view its versions. Select a key version to view the settings for that version.
  4. Copy the Key Identifier value, which provides the URI.
  5. Go back to your Azure AI services resource, and then select Encryption.
  6. Under Encryption key, select Enter key URI.
  7. Paste the URI that you copied into the Key URI box.
  8. Under Subscription, select the subscription that contains the key vault.
  9. Save your changes.
To select a key from a key vault, first make sure that you have a key vault that contains a key. Then follow these steps
  1. Go to your Azure AI services resource, and then select Encryption.
  2. Under Encryption key, select from Key Vault.
  3. Select the key vault that contains the key that you want to use.
  4. Select the key that you want to use.
  5. Save your changes.


    • Related Articles

    • KLapper v2.0 Upgrade Guide

      KLapper v2.0 Upgrade Guide Introduction This document details the upgrade process for our KLapper virtual assistant builder Prerequisites The deployment process is on Azure Cloud; we need the following prerequisites: Azure Cloud Subscription. Azure ...

    • KLapper Admin User Guide

      KLapper Admin User Guide v2.0 Introduction This guide details all features available to an Admin in KLapper, a comprehensive and advanced platform for building and managing intelligent assistants. KLapper is designed to be both intuitive and ...

    • KLapper End User Guide

      KLapper End User Guide v2.0 Introduction Your Virtual Assistant for Intelligent Counsel, Everywhere! KLapper is an advanced virtual legal assistant designed to enhance the efficiency and productivity of legal professionals. Built specifically for the ...

    • v1.1.9

      KLapper v1.1.9 Release Notes Features Fine-Tuning Questions and Answers: Builders can now add custom questions and answers for specific documents, allowing them to refine how the assistant responds. More details are available in the Admin User Guide. ...

    • v2.1.1

      KLapper 2.1.1 Release Notes Features and Updates [URGENT] Issue Resolved for Azure Multi-Tenant Bot Deprecation Skill Builder Update: New "Variable" Node Introduced Enhanced Agent Query Search Functionality Various Bug Fixes and Stability ...