DOCGILITY - ENTERPRISE EDITION

# Installation

Docgility is delivered with a script to easily install into your environment. In the example below, the instructions to install into an Azure Kubernetes environment are provided. The same script can be modified as needed for your existing environments.

# Installation Script for Docgility on Azure Kubernetes

This page is intended to describe Docgility and the process for installing Docgility into a client Azure private cloud environment. This script is intended to quickly install Docgility as well as for the cloud engineer to use as a basis for deploying in the client environment.

# Configurations Needed

In the configuration file, the user may choose to turn on the different settings to enable single sign-on and outbound email generation. These settings below can be included in the config.yml file to enable the service.

1 - SAML/SSO - Single Sign-on Services enable the application to trust authentication services to verify the identity of the user and automatically log in the user. If the user is not logged in, SSO will automatically redirect the user to the client environment's login page. The following values are required:

SAML_IDP_ENTITYID, SAML_IDP_SINGLESIGNONSERVICE_URL, SAML_SP_X509CERT

2 - SMTP - SMTP is used to generate outbound emails for user registration (if client is not using SAML/SSO) for user authentication of email identity and for product alerts.

NOTIFICATIONORIGEMAIL, NOTIFICATIONORIGFROMEMAIL, NOTIFICATIONORIGPW, EMAILSMTPHOST, EMAILSMTPPORT

# Instructions for Product Deployment

The following values are required for the script execution:

Azure Kubernetes Cluster Name (from step 1, creation of the Azure Kubernetes Cluster) Azure Kubernetes Resource Group (from step 1, creation of the Azure Kubernetes Cluster) Docker User Name (provided by Docgility) Docker Password (provided by Docgility)

1 - From Docgility, you should receive the installation script (installapp.sh) and the associated files. In the files, you should also see the embedded helm chart in the format of docbe-4.1.1.tgz (this is a helm chart for application installation and contains the detailed information for Docgility configuration). The rest of the installation script is to configure the necessary networking for the Azure Gateway to access the above services.

In addition, you should receive the Docker User Name and Password for docgimages (the image repository for Docgility images).

TIP

If you want to bring the images into your local environment, you would need to pull the docker images for the Docgility components (indicated in the helm script) and the bitnami images for mysql, mongodb, and minio into your environment. The commands for pulling Docgility images are indicated below:

  • docker pull docgimages.azurecr.io/docgility/docbe:4.1.1
  • docker pull docgimages.azurecr.io/docgility/docinit:4.1.1
  • docker pull docgimages.azurecr.io/docgility/docux:4.1.1

2 - Create an Azure Kubernetes Cluster with the following requirements.

For System and User pools, select VMs with at least 4CPUs and 16GB Memory (32 GB is preferred - example: Standard D8ds v5). For more scalability, we recommend 64GB memory.

Select Azure CNI Node Subset as the networking option.

Note the cluster name and resource group to enter into the script. Also, for this script, select Azure CNI Node Subnet for networking.

3 - Run ./installapp.sh and enter the information above in the following format:

./installapp.sh KubernetesClusterName KubernetesResourceName config.yml DockerUserName DockerPassword yes yes yes yes no

The options at end of the script are described in the script in the following order:

  • Delete previous gateway (specify yes if you want to remove the previous gateway from a previous install)
  • Get new IP Address (specify yes if you want the script to generate a new IP address, otherwise, it will use the previously allocated IP for the cluster)
  • Install Helm Chart (specify yes if you want it to reinstall the helm chart) - Note that this will delete the previous installation.
  • Create Application Gateway (specify yes if you want it to create a new Azure Application Gateway for the service.)
  • Output Log Files (specify yes if you want it to create log files to troubleshoot installation, otherwise it will output to terminal.)

4 - As the script executes, it should do the following:

  • Delete previous Azure Gateway
  • Connect to the Cluster
  • Connect Cluster to Docgility Image Repository
  • Create credentials to access Image Repository
  • Define storage classes in cluster.
  • Create IP address
  • Install helm script with container images
  • Wait until script completes and containers are up and running.
  • Configure network environment
  • Configure Application Gateway

5 - If the install fails, you can try delete the install by running ./installapp.sh again. This script will attempt to delete the previously allocated resources and reinstall the environment from scratch. If there's any issues with deleting previous resources, the script will give errors. You should then try to start a new kubernetes cluster and try again with this script. You may also want to try running each command separately and waiting for azure to return when the resource is available.

# Instructions for Product Upgrades

To get minio password: kubectl get secret minio -o jsonpath='{.data.root-password}' | base64 --decode

To get mysql root password: kubectl get secret mysql -o jsonpath='{.data.mysql-root-password}' | base64 --decode

To get mongodb root password: kubectl get secret mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 --decode

Run the following script to store the values in bash environment.

  • export MINIO_PASSWORD=$(kubectl get secret minio -o jsonpath='{.data.root-password}' | base64 --decode)
  • export MYSQL_PASSWORD=$(kubectl get secret mysql -o jsonpath='{.data.mysql-root-password}' | base64 --decode)
  • export MONGODB_PASSWORD=$(kubectl get secret mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 --decode)

Then run the helm upgrade script with the above settings to enable connectivity to the backend data services with the above passwords into the helm script and reinstall with new images.

# Known Installation Issues

1 - MySQL vs. BE/BEAI initial installation racing condition - When the application script is first run, there may be a racing condition in which MySQL takes much longer to initialize and the BE and BEAI components start but are not able to connect to MySQL. Checking the logs of BE will confirm if this condition is present. Remedy - Restart the BE and BEAI components after MySQL is available. Only applicable for the initial install.

2 - Redeployment requires removing the MySQL pvc component - When making changes, it's often common to install and uninstall as you make changes. When MySQL is installed, a pvc is created that is persistent. When a helm install is performed, it will try to regenerate a new random MySQL admin password and connect to the MySQL instance. With a MySQL pvc already present, the MySQL redeployment will fail and backend services will not be able to access MySQL. Remedy - Delete the pvc for MySQL before reinstalling the helm chart. The installation script automatically tries to delete the previous pvc when reinstalling.