iText DITO Docker API (iText_DITO 2.1)

The iText DITO SDK for Docker image allows you to use iText DITO conveniently from various environments. It enables you to produce PDFs from your output templates.

How to use the iText DITO SDK for Docker image

First, you'll need to pull the image. Note: you need to specify the version explicitly when using the pull command, e.g.:

docker pull itext/dito-sdk:{version}

For the full list of available versions go to Tags tab.

Start the SDK

To start the docker image run the following command:

docker run -it --name dito-sdk-instance
         -v {path to config directory}:/etc/opt/dito/shared
         -v {path to work directory}:/var/opt/dito
         -p {port on host}:8080
         itext/dito-sdk:{version}

config directory - the directory that contains iText DITO license and application configuration file.

iText DITO License file

License file provided by iText. Must be present in config directory. Expected default name is license.xml, but it can be overridden by setting the DITO_LICENSE_FILE environment variable during run, for example:

docker run {other options} -e DITO_LICENSE_FILE=dito.xml itext/dito-sdk:{version}

Note: If you're using Azure, you may get an error message that the license key cannot be found. To resolve this, you will need to enable volume mounting using the WEBSITES_ENABLE_APP_SERVICE_STORAGE=true environment variable.

Application configuration file

YML file with application configuration, in form of:

logAppenders:
- type: file
- type: stdout
pdfProducerReportCache:
  maxSize: 1000
  expireAfterWrite: P1D
templateDeploymentFeature:
  enabled: true
  timeout:
    eachOperationRetryMillis: 500
    eachOperationRetryCount: 10
    allBlockWaitMillis: 5000

logAppenders - list of log appenders that is used to configure where to output the log messages. Log appender is an object with a defined type. Available log appender types:

• stdout - log messages will be sent to stdout;

• file - log messages will be placed in files in a log directory.

You can specify the log appenders one at a time (stdout or file) or several at once (stdout and file simultaneously). If the list is null or empty, default appenders (stdout and file simultaneously) will be used.

pdfProducerReportCache - configures how many and how long cached production reports are stored in memory.

• maxSize - integer (64 bit) specifying how many reports can be stored simultaneously.

• expireAfterWrite - string in ISO-8601 subset (Days, Hours, Minutes, Seconds, e.g. P1DT2H3M4S) specifying for how long the reports can be stored

templateDeploymentFeature - configures the template deployment feature with registering/unregistering and template deployment/undeployment.

• enabled - enables the feature, is false by default.
• timeout - configures template operation wait timeouts.
  • eachOperationRetryMillis - configures how much time we wait before next retry to do such operations as deploy, undeploy and PDF produce
  • eachOperationRetryCount - configures how many times we do retry before timeout for such operations as deploy, undeploy and PDF produce
  • allBlockWaitMillis - configures how much time we wait before timeout for such operations as register and unregister

File can be optionally present in config directory. If not present the default one will be used. Expected default name for YML file is user.config.yml, but it can be overridden by setting the DITO_USER_CONFIG environment variable during run, for example:

docker run {other options} -e DITO_USER_CONFIG=config.yml itext/dito-sdk:{version}

Stop the SDK

To stop SDK service gracefully, run the standard command:

docker kill --signal=SIGTERM {containerId}

You can also use another standard command:

docker stop -t 30 {containerId}

This command sends the SIGTERM signal to the SDK process inside the Docker container, then waits for the specified time in seconds (10 by default). If the SDK doesn't manage to finish its shutdown within that time period, SIGKILL is sent to the kernel and the SDK process is killed.

Configuring Docker SDK for optimal performance

A Java application is run under the hood of the Docker SDK which allows you to fine-tune the JVM for optimal performance in your circumstances.

For example, to extend the default memory allocation to JVM you can tune -Xmx parameter.

To configure the Java Virtual Machine options you can pass the JAVA_TOOL_OPTIONS environment variable to the Docker container.

Example: docker run {other options} -e JAVA_TOOL_OPTIONS="-Xmx5G" itext/dito-sdk:{version}

If you have configured the environment variable and correctly passed it to the iText DITO Docker SDK container you should see the following message in the logs:

Picked up JAVA_TOOL_OPTIONS: -Xmx5G

Web API reference

Note: For consistency in API behaviour when updating to a newer version of the SDK it is strongly recommended specifying the desired API version in X-DITO-API-Version header for all requests. For more info see API versions descriptor documentation.

PDF Producer Resource

Actions

Production request descriptor

  
        {}
    

Production work directory request descriptor

    
            yyyy-MM-dd-HH.mm.ss.nnnnnnnnn.pdf
        

Production response descriptor

Production properties descriptor

Encryption properties descriptor

Bookmarks properties descriptor

Production report descriptor

null

Processing report descriptor

Report entry descriptor

Pdf producer report resource

Actions

Since 1.5.5

Template deployment resource

Actions

Only registered user can perform actions in this resource.
The Authorization HTTP header with Bearer type and token from registration endpoint must be used.

Template deployment request descriptor

Template deployment response descriptor

Registration resource

Actions

Only single user can be registered at ones.

Token request descriptor

Token response descriptor

License resource

Actions

License descriptor

Status resource

Actions

Status descriptor

Features

Description of different features which features section can be contained of

templateDeployment

API versions descriptor

Each request can specify the desired API version in the X-DITO-API-Version header.

Examples

Running SDK

On Windows

docker run -it --name dito-sdk-example
         -v D:\docker\dito\config:/etc/opt/dito/shared
         -v D:\docker\dito\work:/var/opt/dito
         -p 42:8080
         itext/dito-sdk:1.1.8

D:\docker\dito\config - a folder with license.xml file.

D:\docker\dito\work - a working folder where all project files and data samples should be placed.

On Linux

docker run -it --name dito-sdk-example
         -v /home/docker/dito/config:/etc/opt/dito/shared
         -v /home/docker/dito/work:/var/opt/dito
         -p 42:8080
         itext/dito-sdk:1.1.8

/home/docker/dito/config - a folder with license.xml file.

/home/docker/dito/work - a working folder where all project files and data samples should be placed.

Requests

For next requests all paths are relative to working directory (/home/docker/dito/work on Linux or D:\docker\dito\work on Windows assuming service is run with commands above) The dummy.dito is an example iText DITO project that is placed in the working directory. The sample.json is a data sample for it that is placed in the same working directory.

Produce PDF from project file and data in working directory

POST localhost:42/api/pdf-producer

Content-Type application/json

Body
{
    "templateProjectPath": "dummy.dito",
    "templateName": "output",
    "data": "sample.json"
}

200 OK

Content-Type application/json

Body
{
    "path": "2019-09-23-13.00.44.472000000.pdf",
    "report": {
        "pageCount": 1,
        "templateRepairReport": {
            "entries": []
        },
        "pdfProductionReport": {
            "entries": []
        },
        "id": "65fff9f3-db63-4c6d-ad0f-81418b4376b7",
        "highestSeverity": null
    }
}

Produce PDF with 2.0 version and custom output path from project file in working directory and data embedded in the request

POST localhost:42/api/pdf-producer

Content-Type application/json

Body
{
    "templateProjectPath": "dummy.dito",
    "templateName": "output",
    "data": {
        "bind": "from request"
    },
    "path": "custom/path/to/file.pdf",
    "properties": {
        "pdfVersion": "2.0"
    }
}

200 OK

Content-Type application/json

Body
{
    "path": "custom/path/to/file.pdf",
    "report": {
        "pageCount": 1,
        "templateRepairReport": {
            "entries": [
                {
                    "message": "Encountered unexpected empty attribute: \"data-dito-bind\"",
                    "severity": "warn"
                }            
            ]
        },
        "pdfProductionReport": {
            "entries": []
        },
        "id": "65fff9f3-db63-4c6d-ad0f-81418b4376b7",
        "highestSeverity": "warn"
    }    
}

Produce PDF as stream

POST localhost:42/api/pdf-producer

Content-Type application/json

Accept application/pdf

Body
{
    "templateProjectPath": "dummy.dito",
    "templateName": "output",
    "data": {
        "bind": "from request"
    }
}

200 OK

Content-Type application/pdf

X-DITO-Producer-Report-ID 65fff9f3-db63-4c6d-ad0f-81418b4376b7

X-DITO-Producer-Highest-Severity warn

Body
bytes of generated PDF

Get cached PDF producer report

GET localhost:42/api/pdf-producer/report/65fff9f3-db63-4c6d-ad0f-81418b4376b7

Content-Type application/json

200 OK

Content-Type application/json

Body
{
    "pageCount": 1,
    "templateRepairReport": {
        "entries": [
            {
                "message": "Encountered unexpected empty attribute: \"data-dito-bind\"",
                "severity": "warn"
            }            
        ]
    },
    "pdfProductionReport": {
        "entries": []
    },
    "id": "65fff9f3-db63-4c6d-ad0f-81418b4376b7",
    "highestSeverity": "warn"
}

Get loaded license info

GET localhost:42/api/license

200 OK

Content-Type application/json

Body
{
    "expirationDate": "2020-09-23",
    "remaining": {
        "page": 999980
    }
}

User registration

POST localhost:42/api/admin/register

Content-Type application/json

Body
{
    "subject": "best name"
}

200 OK

Content-Type application/json

Body
{
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0In0.1DI6IZUGvCx_K_oxZ8lFuFBTHe-7shhqz77jSw18xkc"
}

Template deployment

POST localhost:42/api/deployments

Content-Type multipart/form-data

Authorization Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0In0.1DI6IZUGvCx_K_oxZ8lFuFBTHe-7shhqz77jSw18xkc

Body
Content-Type: multipart/form-data

200 OK

Content-Type application/json

Body
{
"alias": "best template",
"meta": {
"version": "for tests"
}
}

Produce PDF as stream from alias

POST localhost:42/api/pdf-producer

Content-Type application/json

Accept application/pdf

Body
{
    "templateAlias": "best template",
    "data": {
        "bind": "from request"
    }
}

200 OK

Content-Type application/pdf

X-DITO-Producer-Report-ID 65fff9f3-db63-4c6d-ad0f-81418b4376b7

X-DITO-Producer-Highest-Severity warn

Body
bytes of generated PDF

Extending from DITO SDK Docker image

In some cases you may want to extend from DITO SDK Docker image. Here are some inner detail on base image that may help you do it. To extend from DITO SDK Docker image start your Dockerfile with FROM itext/dito-sdk:{version} e.g.

FROM itext/dito-sdk:1.4.2

What is needed to run base image

The main thing you need is license file in the config directory and DITO projects in the working directory.

License file

License file is expected to be stored at /etc/opt/dito/shared/$DITO_LICENSE_FILE where DITO_LICENSE_FILE is a predefined environment variable equal by default to license.xml.

So if you want to avoid providing volume mapping for folder with license file, it is possible to do so by extending base image and adding

COPY path/on/local/machine/to/license/file.xml /etc/opt/dito/shared/$DITO_LICENSE_FILE

NOTE: Be careful with sharing images that have license files in them.

Optional user config

Optional user configuration is expected at same folder as license config file at /etc/opt/dito/shared/$DITO_USER_CONFIG, where DITO_USER_CONFIG is a predefined environment variable equal by default to user.config.yml. So it can be provided similarly to license file

COPY path/on/local/machine/to/config/user.yml /etc/opt/dito/shared/$DITO_USER_CONFIG

Work directory

In order to produce PDF you'll need to have some .dito project files in working directory. There is a special predefined environment variable DITO_WORK_DIR equal by default to /var/opt/dito

So if you want to avoid providing volume mapping for work directory, you can copy all required .dito projects in your Dockerfile:

COPY path/on/local/machine/to/project1.dito path/on/local/machine/to/project2.dito $DITO_WORK_DIR/

NOTE: If at some point before running base entrypoint working directory was changed it should be restored to DITO work directory. This can be done in Dokerfile:

WORKDIR $DITO_WORK_DIR

Logs

If the file log appender is used then the logs are stored at /var/log/dito on the container and are kept for 30 days. To ease access to such logs you can provide log directory mapping after work directory mapping during docker run as follows: -v {path to log directory}:/var/log/dito If the log directory mapping is not provided the log files will be stored only on container and still can be accessed with e.g. docker cp command.

In the case when stdout log appender is used, all log messages will be sent directly to stdout. Any messages that the container sends to stdout can be viewed using the following command: docker logs {container_name_or_ID}

Running image

To prepare the dito application to work correctly, the script that is stored at /opt/dito/startup.prepare.main.kts is used. After that, the following command is called java -jar /opt/dito/$DITO_JAR_NAME server /etc/opt/dito/config.yml where DITO_JAR_NAME=dito-sdk-docker.jar. There is no need to write

ENTRYPOINT ["bash", "-c", "source $HOME/.sdkman/bin/sdkman-init.sh && kotlin /opt/dito/startup.prepare.main.kts && java -jar /opt/dito/$DITO_JAR_NAME server /etc/opt/dito/config.yml"]

Since the base one will be taken instead, but if you want to do something before running DITO application in container you may put it in your own script and call all commands in the entry point above in the end.

Full example of Dockerfile for image that doesn't require any volume mappings

FROM itext/dito-sdk:1.4.2
COPY license.xml /etc/opt/dito/shared/$DITO_LICENSE_FILE
COPY user.config.yml /etc/opt/dito/shared/$DITO_USER_CONFIG
COPY project1.dito project2.dito $DITO_WORK_DIR/

Note: When running such image you would still need to map 8080 container port.