iText pdf2Data 4.* deployment

About

These instruction describe how to deploy the pdf2Data Manager application to any local environment.

The iText pdf2Data Manager consists of four main technical components/Docker containers: frontend, backend, database, and the editor application. 

The application is run using Docker Compose. The Docker Compose configuration is specified in the docker-compose.yml file. The environment variables for configuring the application are specified in the .env  file and are consumed by Docker Compose. 

Deploying the application using a helper script

How to Use the Helper Script

Prerequisites

The helper deployment script requires Kotlin version 1.4 or higher to be installed. Installation instructions can be obtained from the kotlinlang website. You can verify your Kotlin installation with kotlinc -version command that should print the version of Kotlin that is installed:

Download the Script

For your convenience, there is a helper script that automatically pulls the necessary images from Docker Hub and deploys the iText pdf2Data Manager and Editor.

Download the deployment helper script and save it in an otherwise empty folder.

You need to download the script version matching the version of the application that you want to roll out or update to. E.g. if you want to deploy pdf2data version x.y.z, you have to download the script with version x.y.z. If you want to update your application from version a.b.c to version x.y.z, you have to download version x.y.z of the deployment script. Save the downloaded script in an otherwise empty folder.

Application Directory

The deployment script requires a dedicated (and initially empty) folder to operate. Put your script into that folder. During execution of some of the operations, the script will create the files needed to run the application (application files, config files, backup files, temp files) in that directory. The directory needs to be writable and it's an irreplaceable part of the application deployment.

List of Available Commands and Their Parameters

To view available commands provided by the script and their parameters, call: 

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- help

and follow further help instructions.

Run the Helper Script to Deploy the Application

When the correct version of the script is stored in a folder and you have installed Kotlin , you can run the script from the command line. In the first step, the script will create a Docker compose file, a config file and will then deploy the application. Navigate to the folder where your script has been saved and enter the command below. 

Create Docker Compose File

In the first step, you create a Docker compose file.

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- create-app-file --mode=editor-standalone|full-application

--mode specifies which type of pdf2Data instance will be deployed by the created docker-compose file: Editor Standalone, or the full application (Editor + Manager (FE + BE) + database). 

You can set values for several parameters in the script or update the Docker compose file after it has been created. These parameters include the host and the port where the application will run. By default, the application will be deployed on localhost port 80. You will be able to see an overview of the available parameters by adding --help to the command.

Deprecation warning

Please note that the editor standalone deployment mode is discontinued and is going to be removed soon.

Create an Environment Configuration File

In the second step, you create an environment configuration file (.env). 

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- create-config-file --mode=editor-standalone|full-application --manager-admin-password [--multi-workspace-mode]

Parameters

--mode - specifies for which type of pdf2data deploying instance the environment configuration file will be created: Editor Standalone, or the full application (Editor + Manager (FE + BE) + database). Please note that editor standalone deployment mode is discontinued and is going to be removed soon.

--multi-workspace-mode - (Optional: only use this parameter if you need more than one workspace) pdf2Data manager workspace mode flag. If true, then the instance will be deployed in multi workspace mode (otherwise, the instance will be deployed in single workspace mode).  Works only in full application mode.

--manager-admin-password - will show prompt to type global admin manager password in secure mode. Password must have a length between 12 and 64 characters. It is highly recommended to log in and manually change the password after creating an instance.

Once the environment configuration file has been created, you can update the parameters in the file or rerun the create-config-file command.

Deploy the Application

With all the parameters set, you can now run the deploy command to deploy the application.

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- deploy

The execution of the deploy command may take a while. The script will pull the necessary Docker images: Manager's front-end, back-end, database, and pdf2Data Editor.

Stop, Update or Remove the Manager and Editor Applications 

Stopping the Application 

To temporarily stop the application, run the following command:

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- stop

Starting the Application After it Has Been Stopped

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- start

Updating the Application Version

Please make sure to back up your data (as well as data of the SDK/API instances that you set up) before performing an update.

Note! The containers will be recreated during the application update. The data that is not persisted to Docker volumes will be lost.

Note! The application will be stopped and restarted during the update process.

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- update

Undeploying/Removing the Application 

these operations are irreversible and might cause data loss! Data in containers that are not persisted by any volumes will be lost

To undeploy the application (stop it, remove the created Docker containers and networks), use the following operation. 

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- undeploy

To completely remove the application, including all the Docker volumes and all the data, use the following operation and remove your application directory after executing that command.

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- remove

Manual Deployment Instructions

We don't recommend using manual deployment instructions because it requires more effort compared to the script-based approach. Additionally, performing an application update sometimes requires modifying the application file or configuration file. This will be done automatically by the deployment script, whilst in manual case you need to perform those steps yourself.

Only use manual deployment instructions in case you have very strong reasons against using the script-based approach.

Preparation

To get the application deployed, it is required to create a docker-compose.yml file with the following content:

Full application mode (Editor + Manager (FE + BE) + database):

version: '3.9'
services:

#=========== FRONTEND ===============
  pdf2data-manager-frontend:
    container_name: pdf2data-manager-frontend
    restart: unless-stopped
    pull_policy: always
    image: quay.io/itext/pdf2data-manager-frontend:{version}
    ports: ['80:8080']
    env_file: .env
    depends_on: [pdf2data-manager-backend, pdf2data-editor]

#=========== BACKEND ===============  
  pdf2data-manager-backend:
    container_name: pdf2data-manager-backend
    restart: unless-stopped
    pull_policy: always
    image: quay.io/itext/pdf2data-manager-backend:{version}
    env_file: .env
    depends_on: [pdf2data-manager-db]

#=========== DATABASE =============== 
  pdf2data-manager-db:
    container_name: pdf2data-manager-db
    restart: unless-stopped
    pull_policy: always
    image: quay.io/itext/pdf2data-manager-db:{version}
    env_file: .env
    volumes: ['pdf2data-manager-db:/var/lib/postgresql/data']

#=========== EDITOR =================
  pdf2data-editor: 
    container_name: pdf2data-editor
    restart: unless-stopped
    pull_policy: always 
    image: 'quay.io/itext/pdf2data-editor:{version}'
    env_file: .env

#=========== GENERAL ================
volumes: 
  pdf2data-manager-db: null
networks:
  default: 
    name: pdf2data-manager-network

Editor Standalone mode:

version: '3.9'
services:
  pdf2data-editor:
    container_name: pdf2data-editor
    pull_policy: always
    restart: unless-stopped
    image: quay.io/itext/pdf2data-editor:{version}
    env_file: .env
    ports: ['80:8080']

The docker-compose.yml file has a bunch of variables that allows customizing application setup.

In common the variables are separated by purpose and have self-explained names with default values note.

All the variables need to be set in the extra file .env which has to be placed in the same place as the docker-compose.yml file.

The sample of the .env the file is the following:

Full application mode (Editor + Manager (FE + BE) + database):

PDF2DATA_EDITOR_MODE=MANAGER
PDF2DATA_EDITOR_TEMPLATE_REPOSITORY_MANAGER_HOST=http://pdf2data-manager-backend:8080/api
PDF2DATA_EDITOR_URL=pdf2data-editor:8080

PDF2DATA_MANAGER_BACKEND_URL=pdf2data-manager-backend:8080
PDF2DATA_MANAGER_MULTIPLE_WORKSPACES=false   # Set true, if the instance should be deployed in multiple workspaces mode
PDF2DATA_MANAGER_DEFAULT_ADMIN_PASSWORD=<SOME_SECURE_PASSWORD>
PDF2DATA_MANAGER_DEFAULT_TOKEN_PRIVATE_KEY=...   # ! Fill with Base64-encoded value of a random key. 256bit keys are recommended

PDF2DATA_MANAGER_DB_NAME=postgres
PDF2DATA_MANAGER_DB_PASSWORD=postgres
PDF2DATA_MANAGER_DB_SCHEMA=manager
PDF2DATA_MANAGER_DB_URL=pdf2data-manager-db:5432
PDF2DATA_MANAGER_DB_USERNAME=postgres
PDF2DATA_MANAGER_JPA_GENERATE_STATISTICS=false
PDF2DATA_MANAGER_JPA_SHOW_SQL=false

POSTGRES_DB=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_USER=postgres

PDF2DATA_EDITOR_CONTAINER_MEMORY_LIMIT=819M
PDF2DATA_EDITOR_JVM_MEMORY_LIMIT_MB=619
PDF2DATA_MANAGER_BACKEND_CONTAINER_MEMORY_LIMIT=819M
PDF2DATA_MANAGER_BACKEND_JVM_MEMORY_LIMIT_MB=619
PDF2DATA_MANAGER_DATABASE_CONTAINER_MEMORY_LIMIT=205M
PDF2DATA_MANAGER_FRONTEND_CONTAINER_MEMORY_LIMIT=205M

Editor Standalone mode:

PDF2DATA_EDITOR_MODE=STANDALONE
PDF2DATA_EDITOR_URL=pdf2data-editor:8080 
PDF2DATA_EDITOR_CONTAINER_MEMORY_LIMIT=2048M
PDF2DATA_EDITOR_JVM_MEMORY_LIMIT_MB=1848

For more information on available settings and their meaning see pdf2Data 4.0. Customizing application settings

Running the application

To run the application it is required to run the following command in the folder which contains the above described docker-compose.yml and .env files.

docker-compose up -d

To stop the application it is required to run the following command in the folder which contains the above described docker-compose.yml and .env files.

docker-compose down