Deploy iText DITO Editor and Manager w/ Kotlin

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

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

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

The script can be downloaded from dito-deployment-scripts repository at iText Artifactory. 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 DITO 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, script will create 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 into 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 below command.

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

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.

Create an Environment Configuration File

In the second step, you create an environment configuration file (.env). To create this file you can pass parameters to set a username and password for the global administrator of the Manager application. Enter these values between double quotes.

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- create-config-file --admin-email=admin@email.com --admin-password=long_pa$$word

Once the environment configuration file has been created, you can update 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 for the Manager's front-end, back-end and database and for the Editor.

Connecting iText DITO SDK instances to Manager

Pull the iText DITO SDK Image

Pull the correct iText DITO SDK image from Docker hub. Make sure to specify the version that matches the version of the iText DITO Manager you have installed. That is also the version number of the deployment helper script.

Configure License

Your SDK instance must have a valid license configured. You can obtain a license from iText or an iText DITO implementation/reseller partner. Set up three folders:

config: load your license in this folder. You can also create the user config yml file in this folder;
log: this is where iText DITO will write logs;
work: this is where iText DITO Manager will deploy templates and optionally will write generated PDFs.

Enable templateDeploymentFeature

An important additional requirement is to enable the templateDeploymentFeature in your SDK instance. This is done via a user config file that is passed to SDK. Create such a file in the config folder of your SDK/API container and call it user.config.yml

`pdfProducerReportCache:` `maxSize:` `1000` `expireAfterWrite: P1D` `templateDeploymentFeature:` `enabled:` `true` `timeout:` `eachOperationRetryMillis:` `500` `eachOperationRetryCount:` `10` `allBlockWaitMillis:` `5000`

Mount SDK/API Directories to Volumes

One more important aspect is SDK/API work directory data persistence. When an SDK/API instance is connected to a Manager deployment, the work directory contains currently deployed templates as well as service information about the connection to the Manager. Losing that information will cause data inconsistency between the Manager installation and the connected SDK/API instance(s), so it is very important to make sure the work directory persists when you restart your SDK/API instance for some reason. We recommend using Docker's managed volumes to achieve that goal. The work directory that contains data we need to persist is located at the /var/opt/dito path within the container. Mounting the work directory to a volume makes sure the data is picked up when the container is restarted. To mount the work directory to a volume, use --mount source=dito-sdk-data,target=/var/opt/dito argument when running your containers as a reference.

Backups

When performing backups of your Template Manager installation, you might want to back up your SDK/API data as well. Learn more at https://docs.docker.com/storage/volumes/#backup-restore-or-migrate-data-volumes

Open the Manager Application for the First Time to Initialize it

Open up the application at http://localhost (default port is 80 but it's possible to override it with one of the parameters or at the host/port where you have deployed it.

Log into the application for the first time using the global administrator credentials you have passed in the environment configuration file (.env). After you have logged in, the workspace initialization will guide you through the process of setting up your workspace.

Choose a Name for Your Workspace

In the first step you choose a name for your workspace and select the time zone you are in. This time zone will be used for all creation and modification dates in the user interface. You can change these settings at any time in the settings are.

Upload License File

You will need a valid license file to use iText DITO Manager. Use the same license file you uploaded in the config folder of your SDK/API instance.

Specify the URL of the SDK/API Instance to Connect

In the instance connection wizard you have to specify the URL of the SDK/API instance you want to connect to the Manager.

In case this SDK/API instance is hosted outside of your local host environment, just type the normal domain name / IP address and (optionally) port number where the SDK/API is exposed, e.g. http://sdk.domain.com:8080 or http://10.20.30.40 . Note that if you host your SDK/API via secure HTTPS protocol, you have to provide https:// schema accordingly.

In case you host your SDK/API instance at the same local host environment where DITO Manager is hosted, you need to make sure that the DITO Manager Docker container resolves the host address and port of your SDK/API instance. Several options are available there:

In case you are using Windows or Mac, starting from Docker 18.03 and above you can access your host using host.docker.internal DNS name, so that if your SDK/API instance is available at your host port number 8080, the address you will have to type into the wizard would be http://host.docker.internal:8080 .
The alternative way is to modify your application file (docker-compose.yml) to include the following definition for your DITO Manager Backend container:
CODE
```
extra_hosts:
- "host.docker.internal:host-gateway"
```
This will allow you to use http://host.docker.internal:8080 address in the same fashion.
In case the above versions don't work (which might be the case e.g. in Windows Server Environment) and your SDK instance is on the same host as other DITO containers, you can attach your SDK instance to the same network as the other containers share. The name of that network is normally dito-manager-network and can be additionally looked up in docker-compose.yml file. To attach the container to the network please consult Docker documentation. This can be done e.g. during container creation with docker run command (https://docs.docker.com/engine/reference/run/): docker run ... --network="dito-manager-network" --network-alias="sdk" itext/dito-sdk:{version }. After that you will be able to use http://sdk:8080 as the connection URL for your SDK in Manager.

Stop, Update or Remove the Manager and Editor Applications

Stopping the Application

To temporarily stop the application, run the following command:

CODE

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

Starting the Application After it Has Been Stopped

CODE

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

Updating the Application Version

Warning! 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 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.

CODE

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

Undeploying/Removing the Application

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

Note: this operation is irreversible and might cause data loss! Data in containers that is not persisted by any volumes will be lost

CODE

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.

Note: this operation is irreversible and will cause major data loss!

CODE

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 script-based approach. Additionally, performing application update sometimes requires modifying the application file or configuration file. This would be done automatically by the deployment script while in manual case you need to perform those steps yourselves.

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:

docker-compose.yml

YML

version: '3'
services:
  #=========== FRONTEND ===============
  frontend:
    container_name: dito-manager-frontend
    restart: always
    image: itext/dito-manager-frontend:{version}
    ports:
      - "8080:80"    # {hostPort}:{containerPort}, container port must be set to 80
    depends_on:
      - backend
      - editor
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "3"
 
  #=========== BACKEND ===============     
  backend:
    container_name: dito-manager-backend
    restart: always   
    image: itext/dito-manager-backend:{version}
    env_file: .env
    depends_on:
      - db
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "3"
 
  #=========== DATABASE ===============
  db:
    container_name: dito-manager-db
    restart: always
    image: itext/dito-manager-db:{version}
    volumes:
      - dito-manager-db:/var/lib/postgresql/data
    env_file: .env
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "3"
 
  #=========== EDITOR =================
  editor:
    container_name: dito-editor
    restart: always
    image: itext/dito-editor:{version}
    volumes:
      - dito-editor-data:/DITOWork
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "3"
         
  #=========== GENERAL ================
volumes:
  dito-manager-db:
    name: "dito-manager-db"
  dito-editor-data:
    name: "dito-editor-data"
 
networks:
  default:
    name: "dito-manager-network"

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:

CODE

DITO_MANAGER_FRONTEND_APP_BASE_URL=http://yoursite.own
SPRING_PROFILES_ACTIVE=prod
DITO_MANAGER_JWT_PRIVATE_KEY=...   # ! Fill with Base64-encoded value of a random key. 256bit keys are recommended
DITO_MANAGER_ACCESS_TOKEN_TIME_TO_LIVE=1800
DITO_MANAGER_REFRESH_TOKEN_TIME_TO_LIVE=86400
DITO_MANAGER_MAXIMUM_FAILED_LOGIN_ATTEMPTS=5
DITO_MANAGER_CORS_ALLOWED_PATHS=/**
DITO_MANAGER_CORS_ALLOWED_ORIGINS=*
DITO_MANAGER_CORS_ALLOWED_METHODS=*
DITO_MANAGER_DATABASE_URL=db:5432
DITO_MANAGER_DATABASE_NAME=dito
DITO_MANAGER_DATABASE_USERNAME=postgres
DITO_MANAGER_DATABASE_PASSWORD=1111
DITO_MANAGER_MAILING_ENABLE=true
DITO_MANAGER_SMTP_HOST=smtp.gmail.com
DITO_MANAGER_SMTP_PORT=587
DITO_MANAGER_SMTP_USERNAME=admin@email.com
DITO_MANAGER_SMTP_PASSWORD=admin@email.com
DITO_MANAGER_SMTP_FROM=admin@email.com
DITO_MANAGER_SMTP_AUTH=true
DITO_MANAGER_SMTP_TLS_ENABLE=true
DITO_MANAGER_DEFAULT_ADMIN_EMAIL=admin@email.com
DITO_MANAGER_DEFAULT_ADMIN_PASSWORD=admin@email.com

# Sentry is an option
DITO_MANAGER_SENTRY_DSN=https://a5335d46dea34da7838e0e658daa1ba8@sentry.andersenlab.dev/40
DITO_MANAGER_SENTRY_ENVIRONMENT=dev

POSTGRES_USER=postgres
POSTGRES_PASSWORD=1111
POSTGRES_DB=dito

Customizing application settings

Initial User Credentials settings:

DITO_MANAGER_DEFAULT_ADMIN_EMAIL=admin@email.com - Initial user name
DITO_MANAGER_DEFAULT_ADMIN_PASSWORD=admin@email.com - Initial user password

General settings:

SPRING_PROFILES_ACTIVE - Used profile (Default=prod)

JWT access token settings:

DITO_MANAGER_JWT_PRIVATE_KEY - JWT private key

DITO_MANAGER_ACCESS_TOKEN_TIME_TO_LIVE - Access token time to live (Default=1800)

DITO_MANAGER_REFRESH_TOKEN_TIME_TO_LIVE - Refresh token time to live (Default=86400)

DITO_MANAGER_MAXIMUM_FAILED_LOGIN_ATTEMPTS - Maximum failed login attempts (Default=5)

CORS settings:

DITO_MANAGER_CORS_ALLOWED_PATHS - CORS allowed path (Default=/**)

DITO_MANAGER_CORS_ALLOWED_ORIGINS - CORS allowed origins (Default=*)

DITO_MANAGER_CORS_ALLOWED_METHODS - CORS allowed methods (Default=*)

Database settings:

DITO_MANAGER_DATABASE_URL=db:5432 - Used database URL and port (Default port=5432)

DITO_MANAGER_DATABASE_NAME - Database name

DITO_MANAGER_DATABASE_USERNAME - Database username

DITO_MANAGER_DATABASE_PASSWORD - Database password

Mailing system settings:

DITO_MANAGER_MAILING_ENABLE=true|false - Enable or disable mailing system (Default=true)

DITO_MANAGER_SMTP_HOST - SMTP server URL

DITO_MANAGER_SMTP_PORT - SMTP server port (Default=587)

DITO_MANAGER_SMTP_USERNAME - SMTP username

DITO_MANAGER_SMTP_PASSWORD - SMTP password

DITO_MANAGER_SMTP_AUTH - SMTP authentication requirement (Default=true)

DITO_MANAGER_SMTP_TLS_ENABLE - SMTP TLS requirement (Default=true)

DITO_MANAGER_SMTP_FROM - Sets custom FROM field for the outbound emails. Useful in case the DITO_MANAGER_SMTP_USERNAME parameter used for authentication is a technical/meaningless name, e.g. in case of AWS SES

Variables for the Sentry monitoring system (optional)

DITO_MANAGER_SENTRY_DSN - Sentry monitoring system SDK with client key configuration (DSN)

DITO_MANAGER_SENTRY_ENVIRONMENT - Variable to indicate current environment if this required.

Variables for the database application

POSTGRES_DB - Database name

POSTGRES_USER - Database username

POSTGRES_PASSWORD - Database password

Running the application

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

CODE

docker-compose up -d

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

CODE

docker-compose down