Skip to main content

​
Installation Overview

To install Vantage, follow these steps:
  1. Prepare resources.
  2. Specify resource credentials.
  3. Run the installation scripts.

​
Preparing Resources

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

​
Specifying Resource Credentials

Prior to running the installer:
  1. Set up configuration files.
  2. Prepare certificates.
  3. 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
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. 
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: [email protected]

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

​
Configuration Parameters

ParameterDescription
envInstallation prefix, used as subdomain name by default.
poctrue for Without high availability, false for Highly available.
domainThe primary domain.
product_hostDNS name for product access (default: env.domain).
logging.enabledEnable/disable logging (true/false).
logging.elasticsearch.enabledSpecifies 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.hostThe server IP address.
logging.elasticsearch.portThe port used to connect to Elasticsearch.
logging.elasticsearch.usernameThe username used to connect to Elasticsearch.
logging.elasticsearch.passwordThe password used to connect to Elasticsearch.
logging.elasticsearch.schemeThe protocol scheme used to connect to Elasticsearch.
logging.file.enabledSpecifies whether logs should be written as files. This parameter can be set to either true or false.
loadbalancer.external_ipFloating IP address for the balancer.
k8s.api.ipIP address for Kubernetes API endpoint.
securityContext.global.runAsUserSpecifies 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.runAsGroupSpecifies 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.fsGroupSpecifies 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.gpuSpecifies 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.enabledSpecifies 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_versionSpecifies 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_emailSystem administrator’s email.
container_registry_hostDomain name of the container registry.
container_registry_userThe 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_passwordPassword/token for downloading images from the container registry. This parameter is left blank if there is no container registry.
container_registry_nameThe directory of the container registry where the images are hosted.
smtp.hostIP address or hostname of SMTP server.
smtp.loginThe username used to connect to the SMTP server.
smtp.passwordThe password used to connect to the SMTP server.
smtp.portThe port of the SMTP server.
smtp.useSSLSpecifies whether an encrypted connection should be used. This parameter can be set to either true or false.
smtp.secureSocketOptionsSpecifies the SSL and/or TLS encryption that should be used for a connection.
database.enabledSpecifies whether the database server should be enabled.
database.hostIP address of the SQL Server.
database.portThe port of the database server.
database.usernameThe username used to connect to the database (the user must have the privileges required to create databases).
database.passwordThe password used to access the database.
reporting.enabledSpecifies whether the Warehouse reporting service should be deployed. This parameter can be set to either true or false.
id_reading.enabledSpecifies 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.
ParameterDescription
redis.ipsThe 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.portThe port used to connect to the Redis cluster.
redis.passwordThe password used to connect to the Redis.
redis.sslSpecifies 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

  1. 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-----
  1. 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.

​
Downloading 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"
Important! Ensure that you add the necessary source and target container registry properties to your env_specific.yml under the installation type, whether that is AKS or VM.
For /ansible/inventories/azure/group_vars/all/env_specific.yml, run: 
ansible-playbook -i inventories/azure playbooks/validate-artifact-manifest.yml
ansible-playbook -i inventories/azure playbooks/oci-migration.yml
For /ansible/inventories/k8s/group_vars/all/env_specific.yml, run: 
ansible-playbook -i inventories/k8s playbooks/validate-artifact-manifest.yml
ansible-playbook -i inventories/k8s playbooks/oci-migration.yml

​
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. Run the installer from a Docker image if you have not run it yet: 
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 \
registry.local/vantage-installer:2.7.1
ParameterDescription
-v \$PWD/kube:/root/.kubeThe path to the Kubernetes directory where the kube/config file is stored.
-v \$PWD/ssh/ansible:/root/ansibleThe 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/inventoryThe path to the inventory file.
-v \$PWD/env_specific.yml:/ansible/inventories/k8s/group_vars/all/env_specific.y mlThe path to the env_specific.yml file.
-v \$PWD/ssl:/ansible/files/ssl:roThe path to the folder with SSL certificates that should contain the following files:cert.pem ,key.pem ,adfsroot.pem .
3. Set SSH key permissions: 
chmod 600 /root/.ssh/ansible
4. Run the following command to install and set up the Kubernetes cluster on virtual machines defined in the inventory file: 
ansible-playbook -i inventories/k8s -v playbooks/4-Kubernetes-k8s.yml
5. Run pre-deploy check and accept legal documents: 
ansible-playbook -i inventories/k8s -v playbooks/0-PreflightCheck-k8s.yml
ansible-playbook -i inventories/k8s -v 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.
6. Install the product: 
ansible-playbook -i inventories/k8s -v playbooks/site-k8s-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:
  1. Log out of the Docker container.
  2. Run the following command to get the list of containers:
docker ps -a
Find the name of the container with the installer.
  1. 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: 
ansible-playbook -i inventories/k8s playbooks/6-DeployMonitoring-k8s.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: 
ansible-playbook -i inventories/k8s -v playbooks/deploy-reporting.yml

​
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: ansible-playbook -i inventories/k8s -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