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

URI Methods Notes
/api/pdf-producer POST - creates PDFs from one of the template package's templates and data and writes it to work directory.
Acceptable request types:
  • application/json - production work directory request descriptor
Response type:
  • application/json - production response descriptor
Response codes:
    200 OK - PDF successfully created; 400 Bad Request - one of the descriptor parameters is invalid
Default one.
Isn't available if work directory is read only.
Report returned in the request is not cached
POST - creates PDFs from one of the template package's templates and data.
Acceptable request types:
  • application/json - production request descriptor
Response type:
  • application/pdf - created PDF
Response codes:
    200 OK - PDF successfully created; 400 Bad Request - one of the descriptor parameters is invalid
application/pdf should be specified in request Accept header to use this method.
Can still return application/json on bad requests.
Is available even if work directory is read only.
Response contains X-DITO-Producer-Report-ID header, which can be used to access cached production report.
Response can contain X-DITO-Producer-Highest-Severity header with highest severity level if report is not empty

Production request descriptor

Name Type Description
templateProjectPath string (path) Path to the template project (relative to shared work directory)
templateName string Name of the template inside the template project
templateAlias
Since 1.5.7
string Alias of the deployed template. Must be used instead of `templateProjectPath` and `templateName` for deployed templates.
data json
optional
Data used for production. If specified as string than it is treated as path to data file (relative to shared work directory), otherwise is treated as direct template data. If not specified then empty data is is sent:
  
        {}
    
properties production properties descriptor
optional
The PDF production properties

Production work directory request descriptor

Name Type Description
...same as production request descriptor... ...same as production request descriptor... ...same as production request descriptor...
path string (path)
optional
The suggested path to the resulting PDF file, relative to the work directory. If a file already exists than a new path will be generated. All intermediate directories are created. If not specified, then file names are generated automatically from defaultVersion UTC data in the format:
    
            yyyy-MM-dd-HH.mm.ss.nnnnnnnnn.pdf
        

Production response descriptor

Name Type Description
path string(path) Path to the produced PDF relative to work directory.
report
Since 1.4.1
production report descriptor Contains some meta information about created PDF

Production properties descriptor

Name Type Description
pdfVersion string (enum)
optional
Target PDF version. Valid values are:
  • 1.7 (default)
  • 2.0
encryption encryption properties descriptor
optional
If present specifies PDF encryption. No encryption by default:
bookmarks bookmarks properties descriptor
optional
If present specifies properties for bookmarks generation. By default bookmark generation settings are fetched from template settings

Encryption properties descriptor

Name Type Description
ownerPassword string (password)
String used as owner password. Must be not empty
userPassword string (password)
optional
String used as user password. Treated as absent if empty.
printingAllowed boolean
optional
Allow printing when PDF is opened in user mode:
  • true (default)
  • false
contentCopyingAllowed boolean
optional
Allow copying content when PDF is opened in user mode:
  • true (default)
  • false
editingAllowed boolean
optional
Allow editing content (including editing annotations) when PDF is opened in user mode:
  • true
  • false (default)
screenReaderAccessAllowed boolean
optional
Allow screen reader access when PDF is opened in user mode:
  • true (default)
  • false

Bookmarks properties descriptor

Name Type Description
enabled boolean
Flag that determine whether bookmarks should be generated, must be "true" or "false"

Production report descriptor

Name Type Description
id string (uuid)
autogenerated
The ID of report
pageCount integer (64 bit) Number of pages in produced PDF
templateRepairReport processing report descriptor Object containing information regarding fixed problems in template used for production
pdfProductionReport processing report descriptor Object containing information regarding raised DITO related log messages during PDF production
highestSeverity string (enum)
optional
The highest severity level from both repair and production reports.
Is
null
if both reports are empty.
Possible values (from lowest to highest):
  • trace
  • debug
  • info
  • warn
  • error
timestamp (Since 1.5.5) ISO-8601 formatted string Represents time when report was put in cache

Processing report descriptor

Name Type Description
entries list List of report entry descriptors

Report entry descriptor

Name Type Description
message string Description of this entry
severity string (enum) String describing entry's severity.
Possible values (from lowest to highest):
  • trace
  • debug
  • info
  • warn
  • error

Pdf producer report resource

Actions

URI Methods
/api/pdf-producer/report/{id} GET- gets cached report with specified as path parameter id
Response type:
application/json - production report descriptor
Response codes:
200 OK
404 Not Found
Since 1.5.5
URI Methods
/api/pdf-producer/reports/{id} GET- gets cached report with specified as path parameter id
Response type:
application/json - production report descriptor
Response codes:
200 OK
404 Not Found
URI Methods
/api/pdf-producer/reports GET- gets cached reports within specified timestamp
Query params:
  • startTimestamp - date to start from
  • endTimestamp - end date (exclusive), can be optional (current date is a default value)
Timestamps are ISO-8601 formatted dates (e.g. 2020-01-01T00:00:00Z)

Response type:
application/json - production report descriptors
Response codes:
200 OK
400 Bad request

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.

URI Methods
/api/deployments POST- Deploy the template project with specified template and save it under the specified alias
Query params:
  • forceReplace - true/false(default) - if true will replace template deployment with same alias if present.
Request types:
multipart/form-data Parts:
  • descriptor - application/json - template alias deployment request descriptor
  • templateProject - application/octet-stream - the content of template project
Response type:
application/json - added alias as template deployment response descriptor
Response codes:
200 OK
401 Unauthorized
400 Bad request
400 Bad request
/api/deployments GET- Returns list of all currently deployed templates with aliases
Response type:
application/json - list of template deployment response descriptors
Response codes:
200 OK
401 Unauthorized
/api/deployments/{alias} GET- Returns detailed information about deployed template with specified alias
Response type:
application/json - template deployment response descriptor
Response codes:
200 OK
401 Unauthorized
404 Not found
/api/deployments/{alias} DELETE- Undeploy current template alias
Response type:
application/json - removed alias as template deployment response descriptor
Response codes:
200 OK
401 Unauthorized
404 Not found

Template deployment request descriptor

Name Type Description
templateName string Name of the template inside template project
alias string Alias of the template deployment which can be later used during production
meta json An additional JSON filed that is stored and can be retrieved when requesting template deployment.
Can be an array, obejct, or leaf element.

Template deployment response descriptor

Name Type Description
alias string Alias of the template deployment which can be later used during production
meta json An additional JSON filed that is stored and can be retrieved when requesting template deployment.
Can be an array, object, or leaf element.

Registration resource

Actions

Only single user can be registered at ones.

URI Methods
/api/admin/register POST - Registers new user and returns authorization token.
Only single user can be registered at one specific moment.
Unable to register new user if there are any deployed templates with alias.
Request type:
application/json - the token request descriptor
Response type:
application/json - the token response descriptor
Response codes:
200 OK
400 Bad request
/api/admin/unregister POST - Unregisters user and returns authorization token.
Unable to unregister user if there are any deployed templates with alias. They must be undeployed first.
Request type:
none
Response type:
application/json - the token response descriptor
Request headers:
Authorization: Bearer {token}
Response codes:
204 No Content
400 Bad request
401 Unauthorized
/api/admin/status GET - Verify passed authorization token and returns it.
Request type:
none
Response type:
application/json - the token response descriptor
Request headers:
Authorization: Bearer {token}
Response codes:
204 No Content
400 Bad request
401 Unauthorized

Token request descriptor

Name Type Description
subject string Something identifying the future user of Docker SDK.

Token response descriptor

Name Type Description
token string The token that should be used for authorization.

License resource

Actions

URI Methods
/api/license GET- gets loaded license info
Response type:
application/json - license descriptor
Response codes:
200 OK

License descriptor

Name Type Description
expirationDate date Expiration UTC date in format:
yyyy-MM-dd
remaining dictionary Dictionary from limit type to long number of remaining events. Possible limit types:
  • document
  • page

Status resource

Actions

URI Methods
/api/status GET- gets server status
Response type:
application/json - status descriptor
Response codes:
200 OK

Status descriptor

Name Type Description
sdkVersion string Version of the iText DITO SDK in the format:
major.minor.build
apiVersions API versions descriptor Information about API versions.
health dictionary The dictionary with server health checks
features
Since 2.0.1
object Stores information about different features which are enabled. Present if at least one feature information is present.
userConfiguration
Since 1.4.1
object Stores information about user configuration used. Is in same format as application configuration file mentioned in the beginning of this ReadMe

Features

Description of different features which features section can be contained of

templateDeployment
Field Type Description
instanceRegistered boolean Determines whether instance has registered user
hasDeployments boolean Determines whether instance has deployed templates

API versions descriptor

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

Name Type Description
default string The default API version that will be used if the X-DITO-API-Version header is not specified.
maximumSupported string The maximum supported API version. If the version specified in X-DITO-API-Version header is newer than the maximum supported version the request will fail.
minimumSupported string The minimum supported API version. If the version specified in X-DITO-API-Version header is older than the minimum supported version the request will fail.

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

Request Response
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

Request Response
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

Request Response
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

Request Response
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

Request Response
GET localhost:42/api/license
200 OK
Content-Type application/json
Body
{
    "expirationDate": "2020-09-23",
    "remaining": {
        "page": 999980
    }
}

User registration

Request Response
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

Request Response
POST localhost:42/api/deployments
Content-Type multipart/form-data
Authorization Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0In0.1DI6IZUGvCx_K_oxZ8lFuFBTHe-7shhqz77jSw18xkc
Body
Content-Type: multipart/form-data

Content-Disposition: form-data; name="descriptor" Content-Type: application/json {"alias":"best template", "templateName":"output", "meta":{"version":"for tests"}}

Content-Disposition: form-data; name="template_project" bytes of template project

200 OK
Content-Type application/json
Body
{
"alias": "best template",
"meta": {
"version": "for tests"
}
}

Produce PDF as stream from alias

Request Response
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.