> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Installation
> Install ABBYY Vantage Private Cloud on Virtual Machines or Azure AKS: prepare resources, set credentials, run installer scripts, and validate the deployment.
## 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](/vantage/private-cloud/system-requirements) section are met.
**Complete Azure Infrastructure Creation First!**
Before proceeding, you must create all required Azure resources (AKS cluster, storage accounts, SQL database). Complete the [Azure Infrastructure Creation](/vantage/private-cloud/azure-infrastructure) guide first.
For FIPS-compliant government deployments, see [FIPS Compliance](/vantage/private-cloud/fips-compliance).
## 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.
```bash theme={null}
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:
```ini theme={null}
[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]`.
Steps 2 and 3 are not required for Azure AKS deployments. Continue to step 4.
**4. Create the env\_specific.yml file:**
Specify your own values.
```yaml theme={null}
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
```
```yaml theme={null}
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](/vantage/private-cloud/configuration#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
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:
```text theme={null}
-----BEGIN CERTIFICATE-----
[your certificate]
-----END CERTIFICATE-----
```
2. 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**
```bash theme={null}
# replace and with credentials obtained during procurement
docker login abyvtgonprm27.azurecr.io -u -p
```
**3. Run the installer from a Docker image if you have not run it yet:**
```bash theme={null}
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**. |
```bash theme={null}
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:**
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:
```bash theme={null}
# Login to Azure
az login
# Set the subscription (replace with your subscription ID)
az account set --subscription
# Get AKS cluster credentials (replace with your resource group and cluster name)
az aks get-credentials --resource-group --name
# Verify cluster connectivity
kubectl cluster-info
```
**5. Download the Container Images**
Migration scripts rely on the following properties in `env_specific.yml`
```yaml theme={null}
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"
```
```bash theme={null}
ansible-playbook -i inventories/k8s playbooks/validate-artifact-manifest.yml
ansible-playbook -i inventories/k8s playbooks/oci-migration.yml
```
```bash theme={null}
ansible-playbook -i inventories/azure playbooks/validate-artifact-manifest.yml
ansible-playbook -i inventories/azure playbooks/oci-migration.yml
```
**6. Set SSH key permissions:**
```bash theme={null}
chmod 600 /home/ansible/.ssh/ansible
```
**7. Install and set up the Kubernetes cluster:**
```bash theme={null}
ansible-playbook -i inventories/k8s -v playbooks/4-Kubernetes-k8s.yml
```
Steps 6 and 7 are not required for Azure AKS deployments - the Kubernetes cluster is already provisioned via the Azure Infrastructure Creation guide. Continue to step 8.
**8. Run pre-deploy check and accept legal documents:**
```bash theme={null}
ansible-playbook -i inventories/k8s -v playbooks/0-PreflightCheck-k8s.yml
ansible-playbook -i inventories/k8s -v playbooks/legal.yml
```
```bash theme={null}
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:**
```bash theme={null}
ansible-playbook -i inventories/k8s -v playbooks/site-k8s-deploy.yml
```
```bash theme={null}
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:
1. Log out of the Docker container.
2. Run the following command to get the list of containers:
```bash theme={null}
docker ps -a
```
Find the name of the container with the installer.
3. Run the following command with **container\_name** replaced by the container’s name to get the logs:
```bash theme={null}
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
```bash theme={null}
# 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:
```bash theme={null}
ansible-playbook -i inventories/k8s playbooks/6-DeployMonitoring-k8s.yml
```
```bash theme={null}
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:
```bash theme={null}
ansible-playbook -i inventories/k8s -v playbooks/deploy-reporting.yml
```
```bash theme={null}
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:
```bash theme={null}
ansible-playbook -i inventories/k8s -v playbooks/12-DeployDocumentReader.yml
```
```bash theme={null}
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://lic.regulaforensics.com)
[https://lic2.regulaforensics.com](https://lic2.regulaforensics.com)