For your convenience there is a helper script that automatically pulls the necessary images from Dockerhub 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 Groovy version 3 to run. Installation instructions can be obtained from the official website. You can verify your Groovy installation with groovy - v  command that should print the version of Groovy 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 groovy Deploy.groovy 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 the correct version of Groovy, 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.

groovy Deploy.groovy 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). In the command 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.

groovy Deploy.groovy 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.

groovy Deploy.groovy 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

See more detailed Docker SDK documentation at Deploy iText DITO SDK .

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 in

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. 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 id 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:

extra_hosts:
- "host.docker.internal:host-gateway"

This will allow you to use http://host.docker.internal:8080  address in the same fashion.

Stop, Update or Remove the Manager and Editor Applications 

Stopping the Application 

To temporarily stop the application, run the following command:

groovy Deploy.groovy stop

Starting the Application After it Has Been Stopped

groovy Deploy.groovy 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.

groovy Deploy.groovy 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

groovy Deploy.groovy 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!

groovy Deploy.groovy remove