Installation - ABBYY Documentation

Vantage 3.0 replaces this deployment model. Vantage 2.7 and earlier required ABBYY’s specified infrastructure, created by ABBYY-provided Ansible and Azure CLI scripts. That model is not supported in 3.0: you provision your own infrastructure, and ABBYY does not provide provisioning scripts or other infrastructure automation. This page applies to Vantage 2.7 only. See the Vantage 3.0 overview and Migrate from Vantage 2.7.

Installation Overview

To install Vantage, follow these steps:

Prepare resources.
Specify resource credentials.
Run the installation scripts.

Preparing Resources

Virtual Machines
Azure AKS

Before you begin, make sure all requirements listed in the System Requirements section are met.

Specifying Resource Credentials

Prior to running the installer:

Set up configuration files.
Prepare certificates.
Download container images.

Setting Up Configuration Files

1. Create the installation directory: Create an installation directory and its subdirectories (ssh, kube, ssl), from which the installation will be carried out. Navigate to the installation directory.

mkdir -p /opt/vantage-install/{ssh,kube,ssl} && cd /opt/vantage-install

Virtual Machines
Azure AKS

2. Create the SSH key file:Create a file in the ssh folder named ansible and place the private SSH key for the ansible user in this file.3. Create the inventory file:Create an inventory file in the installation directory. Replace X.X.X.X with your VM IP addresses:

[localhost]
127.0.0.1

###########################################
[kube_control_plane]
ub01master01 ansible_host=X.X.X.X

[abbyy_services]
ub01worker12-48-s01 ansible_host=X.X.X.X

[abbyy_workers]
ub01worker12-48-w01 ansible_host=X.X.X.X
ub01worker12-48-w02 ansible_host=X.X.X.X
ub01worker12-48-w03 ansible_host=X.X.X.X

###########################################
[kube_workers:children]
abbyy_services
abbyy_workers

[kube_cluster:children]
kube_control_plane
kube_workers

If you only need 1 or 2 machines for workers instead of 3, delete the extra lines in section [abbyy_workers].

4. Create the env_specific.yml file: Specify your own values.

Virtual Machines
Azure AKS

env: null
poc: true

domain: null
product_host: "{{ env }}.{{ domain }}"

logging:
  enabled: true
  elasticsearch:
    enabled: false
    host: null
    port: 9200
    username: null
    password: null
    scheme: https
  file:
    enabled: true

loadbalancer:
  external_ip: X.X.X.X

k8s:
  api:
    ip: X.X.X.X

techcore:
  use_gpu_workers: false
  use_nn_extraction_training_workers: false

platform_admin_email: admin@yourdomain.tld

source_container_registry_host: abyvtgonprm27.azurecr.io
source_container_registry_user: null      # replace with credentials obtained during procurement
source_container_registry_password: null  # replace with credentials obtained during procurement
source_container_registry_name: "{{ source_container_registry_host }}"

container_registry_host: registry.yourdomain.tld
container_registry_user: null
container_registry_password: null
container_registry_name: "{{ container_registry_host }}/vantage"

smtp:
  host: null
  login: null
  password: null
  port: 587
  useSSL: false
  secureSocketOptions: null

database:
  host: X.X.X.X
  port: 1433
  username: null
  password: null

reporting:
  enabled: false

id_reading:
  enabled: false

env: vantage
poc: false  # Set to true for Without high availability configuration

domain: yourdomain.tld
product_host: "vantage.{{ domain }}"

loadbalancer:
  external_ip: X.X.X.X  # Azure Public IP address

container_registry_host: "registry.yourdomain.tld"
container_registry_user: "service"
container_registry_password: "password"
container_registry_name: "{{ container_registry_host }}/vantage"

techcore:
  use_gpu_workers: false
  use_nn_extraction_training_workers: false

logging:
  enabled: true
  elasticsearch:
    enabled: false
    host: null
    port: 9200
    username: null
    password: null
    scheme: https
    ilm:
      create: false
  file:
    enabled: true

platform_admin_email: admin@yourdomain.tld

# Email configuration - use either SendGrid OR SMTP
sendgrid:
  enabled: false
  apiKey: ""

smtp:
  host: X.X.X.X
  login: null
  password: ""
  port: 587
  useSSL: false

mailFrom: noreply@yourdomain.tld

# Azure SQL Database configuration
database:
  type: sqlserver
  host: X.X.X.X  # Azure SQL Server hostname
  username: login
  password: password
  encrypt: false

# Azure Storage Accounts - replace with your storage account credentials
s3storage:
  skills:
    accessKey: skills_storage_account_name
    secretKey: skills_storage_account_key
  processing:
    accessKey: processing_storage_account_name
    secretKey: processing_storage_account_key
  temporary:
    accessKey: temporary_storage_account_name
    secretKey: temporary_storage_account_key
  sharedfolder:
    accessKey: sharedfolder_storage_account_name
    secretKey: sharedfolder_storage_account_key
    resourcegroup: your_resource_group
  archive:
    accessKey: archive_storage_account_name
    secretKey: archive_storage_account_key

# Redis cluster configuration (required for Highly Available only)
# Leave empty arrays for Without high availability configuration
redis:
  ips: ['172.16.10.101', '172.16.10.102', '172.16.10.103', '172.16.10.104', '172.16.10.105', '172.16.10.106']
  port: 6379
  password: redispassword
  ssl: false

reporting:
  enabled: false

id_reading:
  enabled: false

k8s_fips_enabled: false

For the s3storage section, the accessKey is the Azure Storage Account name and the secretKey is the Storage Account access key. You can retrieve these from the Azure portal or using the Azure CLI.

Configuration Parameters

Parameter	Description
`env`	Installation prefix, used as subdomain name by default.
`poc`	`true` for Without high availability, `false` for Highly available.
`domain`	The primary domain.
`product_host`	DNS name for product access (default: `env.domain`).
`logging.enabled`	Enable/disable logging (`true`/`false`).
`logging.elasticsearch.enabled`	Specifies whether Elasticsearch should be enabled. This parameter can be set to either true or false. Note: Set the value of the parameter to true only if you already have Elasticsearch and want to connect Vantage logs to it. If you don’t have existing Elasticsearch and Kibana instances, you can deploy them in a cluster using instructions in Elasticsearch and Kibana. This must be done before installing the product.
`logging.elasticsearch.host`	The server IP address.
`logging.elasticsearch.port`	The port used to connect to Elasticsearch.
`logging.elasticsearch.username`	The username used to connect to Elasticsearch.
`logging.elasticsearch.password`	The password used to connect to Elasticsearch.
`logging.elasticsearch.scheme`	The protocol scheme used to connect to Elasticsearch.
`logging.file.enabled`	Specifies whether logs should be written as files. This parameter can be set to either true or false.
`loadbalancer.external_ip`	Floating IP address for the balancer.
`k8s.api.ip`	IP address for Kubernetes API endpoint.
`securityContext.global.runAsUser`	Specifies the identifier of the user that the container process should run as. This setting only applies to pods that work with external rwx stores (such as NFS). By default, the parameter is set to 65532.
`securityContext.global.runAsGroup`	Specifies the identifier of the group that the container process should run as. This setting only applies to pods that work with external rwx stores (such as NFS). By default, the parameter is set to 65532.
`securityContext.global.fsGroup`	Specifies the identifier of the group that will own the volumes attached to the pod. This setting only applies to pods that work with external rwx stores (such as NFS). By default, the parameter is set to 65532.
`techcore.nn_training_workers.gpu`	Specifies whether the GPU workers should be deployed. GPU workers are used for training skills with the Deep Learning activity to extract data from semi-structured documents. This parameter can be set to either true or false. If the parameter is set to true, the `techcore.nn_training_workers.enabled` parameter must also be set to true. You can deploy this option and set the `techcore.nn_training_workers.gpu` and `techcore.nn_training_workers.enabled` parameters to true before or after installing Vantage. For more information, see Setting up GPU.
`techcore.nn_training_workers.enabled`	Specifies whether the nn-extraction-training and nlp-model-train workers should be deployed. These workers are usedfor training skills with the Deep Learning activity to extract data from semi-structured documents using the CPU. This parameter can be set to either true or false.
`techcore.keep_previous_version`	Specifies whether the technology core version 2 must remain when updating Vantage. By default, the `techcore.keep_previous_version` parameter is not specified and the technology core version 2 is deleted. To keep it, set the value of the parameter to true.
`platform_admin_email`	System administrator’s email.
`container_registry_host`	Domain name of the container registry.
`container_registry_user`	The name of the user with the permissions to download images from the container registry. This parameter is left blank if there is no container registry.
`container_registry_password`	Password/token for downloading images from the container registry. This parameter is left blank if there is no container registry.
`container_registry_name`	The directory of the container registry where the images are hosted.
`smtp.host`	IP address or hostname of SMTP server.
`smtp.login`	The username used to connect to the SMTP server.
`smtp.password`	The password used to connect to the SMTP server.
`smtp.port`	The port of the SMTP server.
`smtp.useSSL`	Specifies whether an encrypted connection should be used. This parameter can be set to either true or false.
`smtp.secureSocketOptions`	Specifies the SSL and/or TLS encryption that should be used for a connection.
`database.enabled`	Specifies whether the database server should be enabled.
`database.host`	IP address of the SQL Server.
`database.port`	The port of the database server.
`database.username`	The username used to connect to the database (the user must have the privileges required to create databases).
`database.password`	The password used to access the database.
`reporting.enabled`	Specifies whether the Warehouse reporting service should be deployed. This parameter can be set to either true or false.
`id_reading.enabled`	Specifies whether the Identity Documents add-on should be deployed. This parameter can be set to either true or false.

The following four parameters are optional and are required only if the Highly available configuration is being installed and if installing Redis is required by the Vantage installer.

Parameter	Description
`redis.ips`	The Redis cluster IP address in the following format: [‘192.168.0.1”192.168.0.2’,,‘192.168.0.3’]. If the parameter is defined as [], an in-cluster Redis instance will be deployed.
redis.port	The port used to connect to the Redis cluster.
`redis.password`	The password used to connect to the Redis.
`redis.ssl`	Specifies whether an encrypted connection to the Redis cluster should be used. This parameter can be set to either true or false.

All other parameters are unchanged.

Preparing Certificates

Go to the ssl directory. Place the wildcard certificate (along with the intermediate certificate) corresponding to the primary domain name inside that directory and the key (in PEM format) into the following files respectively:./ssl/cert.pem ,./ssl/key.pem. You should convert your CRT file to PEM by changing the contents of the file to the following format:

-----BEGIN CERTIFICATE-----
[your certificate]
-----END CERTIFICATE-----

If using an external authentication provider (ADFS) with a certificate signed by an internal CA, place the root certificate into ./ssl/adfs-root.pem.

If accessing third-party endpoints from Vantage (Custom activity scripts or external authentication), the external endpoint must have a certificate from a public authority.

Running the Installation Scripts

The installation of ABBYY Vantage is automatic. It is executed using the Ansible tool which is installed and set up inside the container used for the installation. Ansible interacts with the machines using various configuration scenarios (YAML playbooks). To install ABBYY Vantage, follow these steps: 1. Navigate to the installation directory. 2. Login to the installer distribution registry

# replace <username> and <password> with credentials obtained during procurement
docker login abyvtgonprm27.azurecr.io -u <username> -p <password>

3. Run the installer from a Docker image if you have not run it yet:

Virtual Machines
Azure AKS

docker run -it \
-v $PWD/kube:/home/ansible/.kube \
-v $PWD/ssh/ansible:/home/ansible/.ssh/ansible \
-v "//var/run/docker.sock:/var/run/docker.sock" \
-v $PWD/inventory:/ansible/inventories/k8s/inventory \
-v $PWD/env_specific.yml:/ansible/inventories/k8s/group_vars/all/env_specific.yml \
-v $PWD/ssl:/ansible/files/ssl:ro \
--privileged \
abyvtgonprm27.azurecr.io/vantage-installer:2.7.1

Parameter	Description
`-v $PWD/kube:/home/ansible/.kube`	The path to the Kubernetes directory where the kube/config file is stored.
`-v $PWD/ssh/ansible:/home/ansible/.ssh/ansible`	The path to the private SSH key required to install and configure the Kubernetes cluster and some prerequisites.
`-v "//var/run/docker.sock:/var/run/docker.sock"`	Required to sync images to your container registry.
`-v $PWD/inventory:/ansible/inventories/k8s/inventory`	The path to the inventory file.
`-v $PWD/env_specific.yml:/ansible/inventories/k8s/group_vars/all/env_specific.yml`	The path to the env_specific.yml file.
`-v $PWD/ssl:/ansible/files/ssl:ro`	The path to the folder with SSL certificates that should contain the following files: cert.pem, key.pem, adfsroot.pem.

docker run -it \
-v $PWD/env_specific.yml:/ansible/inventories/azure/group_vars/all/env_specific.yml \
-v $PWD/ssl:/ansible/files/ssl:ro \
abyvtgonprm27.azurecr.io/vantage-installer:2.7.1

Parameter	Description
`-v $PWD/env_specific.yml:/ansible/inventories/azure/group_vars/all/env_specific.yml`	The path to the env_specific.yml file.
`-v $PWD/ssl:/ansible/files/ssl:ro`	The path to the folder with SSL certificates that should contain the following files: cert.pem, key.pem, adfsroot.pem.

4. Connect to Azure AKS cluster:

Virtual Machines
Azure AKS

Skip this step for Virtual Machine deployments - cluster credentials are configured automatically during Kubernetes installation in step 7.

After the Docker container starts, authenticate to Azure and connect to your AKS cluster:

# Login to Azure
az login

# Set the subscription (replace with your subscription ID)
az account set --subscription <subscription_id>

# Get AKS cluster credentials (replace with your resource group and cluster name)
az aks get-credentials --resource-group <resource_group_name> --name <cluster_name>

# Verify cluster connectivity
kubectl cluster-info

5. Download the Container Images Migration scripts rely on the following properties in env_specific.yml

source_container_registry_host: sourcerepo.azurecr.io
source_container_registry_user: user
source_container_registry_password: pass
source_container_registry_name: "{{ source_container_registry_host }}/optional/subpath"

container_registry_host: destinationrepo.azurecr.io
container_registry_user: user
container_registry_password: pass
container_registry_name: "{{ container_registry_host }}/optional/subpath"

Virtual Machines
Azure AKS

ansible-playbook -i inventories/k8s playbooks/validate-artifact-manifest.yml
ansible-playbook -i inventories/k8s playbooks/oci-migration.yml

ansible-playbook -i inventories/azure playbooks/validate-artifact-manifest.yml
ansible-playbook -i inventories/azure playbooks/oci-migration.yml

Virtual Machines
Azure AKS

6. Set SSH key permissions:

chmod 600 /home/ansible/.ssh/ansible

7. Install and set up the Kubernetes cluster:

ansible-playbook -i inventories/k8s -v playbooks/4-Kubernetes-k8s.yml

8. Run pre-deploy check and accept legal documents:

Virtual Machines
Azure AKS

ansible-playbook -i inventories/k8s -v playbooks/0-PreflightCheck-k8s.yml
ansible-playbook -i inventories/k8s -v playbooks/legal.yml

ansible-playbook -i inventories/azure playbooks/0-PreflightCheck-azure.yml
ansible-playbook -i inventories/azure playbooks/legal.yml

The playbook will:

Perform a preliminary check for the resources whose parameters are specified in the env_specific.yml file of the playbook (such as database and SMTP connection).
Ask the system administrator to accept the terms of the EULA and ABBYY Privacy Policy.

9. Install the product:

Virtual Machines
Azure AKS

ansible-playbook -i inventories/k8s -v playbooks/site-k8s-deploy.yml

ansible-playbook -i inventories/azure playbooks/site-azure-deploy.yml

The playbook will deploy the metric and log collection system and will deploy ABBYY Vantage. The time required to complete the installation process will depend on the performance of the selected machines. On average, the process will take about 10 minutes. You can monitor the pods and the job execution in a cluster using any tool for working with Kubernetes, for example the Lens utility. To do so, use the kubeconfig file that will be created in the kube folder after installing Kubernetes on the virtual machines. You can also download the Ansible installation log files to your local machine by following the steps below:

Log out of the Docker container.
Run the following command to get the list of containers:

docker ps -a

Find the name of the container with the installer.

Run the following command with container_name replaced by the container’s name to get the logs:

docker cp container_name:/ansible/ansible.log ansible.log

Once the deployment is finished, you will be provided with the following:

URL for the provided domain name.
System Administrator login and password that can be used to log in, create tenants, and process documents.

Getting Installation Logs

# Exit the Docker container, then:
docker ps -a
# Find the container name, then:
docker cp container_name:/ansible/ansible.log ansible.log

Optional Deployments

Deploying the Logging System

If the logging system wasn’t enabled in Vantage (the value of the logging.enabled parameter in the env_specific.yml file was false) during its installation, you can enable it after installing Vantage. For this, set the value of the logging.enabled parameter in the env_specific.yml file to true and run the following command:

Virtual Machines
Azure AKS

ansible-playbook -i inventories/k8s playbooks/6-DeployMonitoring-k8s.yml

ansible-playbook -i inventories/azure playbooks/6-DeployMonitoring-azure.yml

Deploying Business Processing Reporting Warehouse

The Business Processing Reporting Warehouse is used for analyzing the business process and tracking data for specific periods of time. During the Vantage installation, the Business Processing Reporting Warehouse will also be installed if the value of the reporting.enabled parameter in the env_specific.yml file was set to true. If the value of the reporting.enabled parameter was set to false, you can install the Business Processing Reporting Warehouse after installing Vantage by running the following command:

Virtual Machines
Azure AKS

ansible-playbook -i inventories/k8s -v playbooks/deploy-reporting.yml

ansible-playbook -i inventories/azure -v playbooks/deploy-reporting.yml

After installation, you must restart the Public API pods so the correct reporting URL is loaded.

Deploying the Identity Documents Add-on

The Identity Documents add-on requires Vantage to have internet access to https://lic.regulaforensics.com and https://lic2.regulaforensics.com.

The Identity Documents add-on service enables running the Identity Documents skill that is used to extract data from identity documents issued in various countries. During the Vantage installation, the Identity Documents add-on will also be installed if the value of the id_reading.enabled parameter in the env_specific.yml file was set to true. If the value of the id_reading.enabled parameter was set to false, you can install the Identity Documents add-on after installing Vantage by running the following command:

Virtual Machines
Azure AKS

ansible-playbook -i inventories/k8s -v playbooks/12-DeployDocumentReader.yml

ansible-playbook -i inventories/azure -v playbooks/12-DeployDocumentReader.yml

It’s necessary that access to the following addresses be provided from the cluster containing the Vantage installation: https://lic.regulaforensics.com https://lic2.regulaforensics.com

​Installation Overview

​Preparing Resources

​Specifying Resource Credentials

​Setting Up Configuration Files

​Configuration Parameters

​Preparing Certificates

​Running the Installation Scripts

​Getting Installation Logs

​Optional Deployments

​Deploying the Logging System

​Deploying Business Processing Reporting Warehouse

​Deploying the Identity Documents Add-on

Installation Overview

Preparing Resources

Specifying Resource Credentials

Setting Up Configuration Files

Configuration Parameters

Preparing Certificates

Running the Installation Scripts

Getting Installation Logs

Optional Deployments

Deploying the Logging System

Deploying Business Processing Reporting Warehouse

Deploying the Identity Documents Add-on