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
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.
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.
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.
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.
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.
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.
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
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.
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://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:
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:
Starting the Application After it Has Been Stopped
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.
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
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!
Back up and Restore the Database
It is highly recommended to regularly backup the database, especially before performing update operations. Use the following operation to backup the database
This operation will create a backup folder in the directory where it has been run. In the backup folder a backup file will be created with the following name pattern:
In order to restore a backup, use the following operation:
As part of the restore procedure, you will be requested to provide the name of the backup file which needs to be restored.