Set up the service in your Docker container

Use the Conversion Service either with Docker Compose or using your custom Docker configuration.

Docker Compose configuration
Custom Docker configuration

Prerequisite

Install Docker to enable use of the Conversion Service with both the Docker Compose or with your custom configuration.

Docker Compose configuration

Docker Compose lets you define and manage multi-container applications using a YAML file. This section illustrates the use of the Docker Compose with the Conversion Service. Using the Docker Compose with multiple interconnected services, specifically the Connector Service, Conversion Service, and Configuration Updater is recommended.

The Docker Compose encapsulates the configuration of each service, its dependencies, and networking requirements within the docker-compose.yaml file. Docker Compose provides orchestration capabilities, automating the startup, shutdown, and scaling of containers, which is helpful for maintaining the integrity and availability of the Conversion Service system managed through Docker.

Configure containers using Docker Compose

The following code block includes an example of the docker-compose.yaml file you can copy and use. Specific details are explained in code comments:

volumes:
  vol-connector-srv: {}
  vol-conversion-srv: {}
services:
    connector-service:
        # Connector Service image:
        # - Enables Watched Folders by monitoring a specified directory for incoming files. 
        # - Enables REST Input connectors, both Plain HTTP and JSON.
        image: pdftoolsag/connector-service:${IMAGE_VERSION} 
        ports:
            # Expose port 13034 for external communication.
            - "13034:13034"
        volumes:
            # Mount the host directory specified by `BASE_HOST_WATCHED_FOLDER` to /app/watched-folders/
            # within the container used for Watched Folders.
            - ${BASE_HOST_WATCHED_FOLDER}:/app/watched-folders/
            # Utilizes vol-connector-srv for configuration files.
            - vol-connector-srv:/app/config
        depends_on:
            # Dependent on configuration-updater. The service starts
            # only after the update was completed successfully.
            configuration-updater:
                condition: service_completed_successfully

    conversion-service:
        # Conversion Service image - Converts files to PDF format.
        image: pdftoolsag/conversion-service:${IMAGE_VERSION}
        volumes:
            # Utilizes vol-conversion-srv for configuration files.
            - vol-conversion-srv:/var/www/convsrv/bin/config
        environment:
          # Optional: To convert files without a watermark, pass the value of your full license key.
          # Without a license key, the container registers the built-in trial license.
          LICENSEKEY: ${LICENSE_KEY_VALUE}
        ports:
            # Exposes port 13033 for external communication.
            - "13033:13033"
        depends_on:
            # Dependent on configuration-updater. The service starts only after the update was completed successfully.
            configuration-updater:
                condition: service_completed_successfully
    
    configuration-updater:
        # Configuration Updater - Updates configuration files for both connector-service and conversion-service.
        image: pdftoolsag/configuration-updater:${IMAGE_VERSION}
        volumes:
            # Utilizes vol-conversion-srv for updating Conversion Service configurations.
            - vol-conversion-srv:/app/conversion-config
            # Utilizes vol-connector-srv for updating Connector Service configurations.
            - vol-connector-srv:/app/connector-config

macOS on Apple Silicon

Conversion Service images are published for linux/amd64 only. On a Mac with Apple Silicon, add platform: linux/amd64 to each service in docker-compose.yaml so they run under emulation.

As of version 6.12.0, Conversion Service validates the license key directly against the Pdftools Licensing Service at https://licensing.pdf-tools.com, so no Licensing Gateway Service (LGS) container is required.

To route licensing through the LGS instead, for example, to share one license key across multiple Conversion Service instances or to use offline licensing, set LICENSE__USELGS to true and add a license-gateway service:

    conversion-service:
        # ... same configuration as in the previous example, plus:
        environment:
          LICENSEKEY: ${LICENSE_KEY_VALUE}
          # Route licensing through the Licensing Gateway Service.
          LICENSE__USELGS: "true"
          # Pass the URL of the Licensing Gateway Service endpoint.
          LICENSINGSERVICE: http://license-gateway:9999
        depends_on:
            # Dependent on license-gateway. The service starts only after license-gateway healthcheck pass.
            license-gateway:
                condition: service_healthy

    license-gateway:
        image: pdftoolsag/license-gateway:${LICENSE_IMAGE_VERSION}
        ports:
            - "9999:9999"
        environment:
            - LICENSE_KEYS=${LICENSE_KEY_VALUE}
        healthcheck:
            test: ["CMD", "curl", "-f", "http://localhost:9999/healthz/ready"]
            interval: 5s
            timeout: 3s
            retries: 3

License Gateway Service endpoint

If you are using a non-containerized version of the License Gateway Service (LGS), set LICENSINGSERVICE to the appropriate endpoint where LGS is accessible. The default port is 9999.

Links to the topics mentioned in the previous code sample:

Watched Folders
REST input connectors:
- REST input plain HTTP
- REST input JSON

Run Docker Compose

To run Docker Compose:

Save both docker-compose.yaml and docker-compose.env file in the same directory.
Update the docker-compose.env file to define the environment variables:
- BASE_HOST_WATCHED_FOLDER: Path to the directory on the host machine watched by the Connector Service.
- LICENSE_KEY_VALUE: Valid license key for Conversion Service. To use the built-in trial license instead, remove the LICENSEKEY variable from the docker-compose.yaml file.
- IMAGE_VERSION: The Conversion Service version number. For example: 6.12.0, 6.12, 6
- LICENSE_IMAGE_VERSION: The License Gateway Service version number. Only required when you route licensing through the LGS.
For example:
docker-compose.env
```
LICENSE_KEY_VALUE=YOUR_LICENSE_KEY
BASE_HOST_WATCHED_FOLDER=/path/to/watched-folder
IMAGE_VERSION=6.12.0
# Only when routing licensing through the LGS:
LICENSE_IMAGE_VERSION=1.3
```
Open the terminal and navigate to the directory where the docker-compose.yaml and docker-compose.env files were saved.

Run Docker Compose:

docker compose --env-file docker-compose.env up -d

Custom Docker configuration

You configure the service in your Docker container at startup by passing host address, and license key as environment variables. You can also set up a proxy or a load balancer as required.

Service host address

The port exposed by the container is 13033. When running the container, the port must be published, which defines the address of the container’s REST service as: http[s]://‹hostname›:‹port›/conversion/v1.0/rest.

This is the endpoint URL used by clients such as the shell client. You should map the exposed port to the same port of the host machine: http[s]://localhost:13033/conversion/v1.0/rest.

HTTPS

By default, the service endpoint uses HTTP. Activating HTTPS disables support for HTTP to prevent clients from accidentally sending sensitive information over HTTP.

You need to set service__serviceEndpoint to an URL with the format https://localhost:13033/conversion/v1.0/rest to activate HTTPS.

When activating HTTPS, a valid host certificate is required. The certificate must be provided as PKCS#12 file (.pfx or .p12), which includes the certificate’s private key and issuer certificates. You specify the certificate path in service__certificate__path.

If the private key is password protected, the password can be configured using service__certificate__password.

docker run -dp 13033:13033 \
   -e service__serviceEndpoint=https://localhost:13033/conversion/v1.0/rest \
   --secret source=service_certificate,target=service_certificate \
   -e service__certificate__path=/run/secrets/service_certificate \
   pdftoolsag/conversion-service

Manage license keys

When you start a container running version 6.12.0 or later without a license key, Conversion Service registers the built-in trial license, and converted files have a watermark. In earlier versions, the service requires a license key.

To activate a full license key, pass it using one of the following environment variables:

LICENSEKEY: The value of the parameter is the license key.

docker run -dp 13033:13033 \
-e LICENSEKEY=4H-VX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX \
pdftoolsag/conversion-service

LICENSEKEY_FILE: The value of the parameter value is a path to a text file that contains the license key.

docker run -dp 13033:13033 \
--secret source=service_licensekey,target=service_licensekey \
-e LICENSEKEY_FILE=/run/secrets/service_licensekey \
pdftoolsag/conversion-service

The service validates the license key directly against the Pdftools Licensing Service at https://licensing.pdf-tools.com. To route licensing through the Licensing Gateway Service (LGS) instead, set LICENSE__USELGS to true and pass the LGS endpoint URL using the LICENSINGSERVICE parameter:

docker run -dp 13033:13033 \
-e LICENSEKEY=4H-VX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX \
-e LICENSE__USELGS=true \
-e LICENSINGSERVICE=http://LGS_IP_ADDRESS:9999 \
pdftoolsag/conversion-service

Replace LGS_IP_ADDRESS with the IP address of the machine running the LGS. Use 9999 as the recommended port.

For more details about license key validation with and without the LGS, review Conversion Service licensing.

Update or delete the license key

To update the license key, remove the current Docker container where the Conversion Service is installed and start a new one. Then add and activate the license key as described in Manage license keys.
To delete the license key, remove the Docker container where you installed the Conversion Service.

Proxy

If you want to set a proxy, use the HTTP_PROXY environment variable. The proxy is used for both http and https. The proxy also applies to the direct communication with the Pdftools Licensing Service, including credentials embedded in the proxy URL, for example, http://USER:PASSWORD@PROXY_ADDRESS:PORT.

Cross-Origin Requests (CORS)

You can restrict cross-origin requests to a set of allowed origins. Use the CORS_ORIGINS environment variable.

The value is a comma-separated list of URLs. A wildcard * can be used to allow all origins or all subdomains of a specific domain. All parts of the URL must match, i.e. the scheme, host and port. The URLs must not specify a path, i.e. invalid URL: https://www.example.com/.

Examples:

Allow all origins (default): CORS_ORIGINS=*
Allow single origin: CORS_ORIGINS=https://www.example.com
Allow multiple domains: CORS_ORIGINS=https://www.example.com, https://www.domain.com
Allow all subdomains: CORS_ORIGINS=https://*.example.com
Allow single domain and port: CORS_ORIGINS=https://www.example.com:5000

Use forwarded HTTP headers from WAF

Set the USE_FORWARDED_HEADERS to True to activate the use of forwarded HTTP headers. The header X-Forwarded-For Contains the IP address of the client that initiated the request.

Load balancer

Load balancing is supported. In addition to configuring the load balancer, there are also requirements on the clients in order to ensure optimal operation.

The Conversion Service does not share resources among the backend servers, so each job is processed exclusively by the backend server where it has been created. Therefore, it is important to use sticky sessions in the load balancer so that all requests for a job are forwarded to the correct backend server.

Configure the load balancer

The load balancer must be configured to use sticky sessions. For this, it is recommended to use a cookie that is set upon the first request.

Kubernetes example 1. Annotations for NGINX Ingress Controller

nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/affinity-mode: "persistent"
nginx.ingress.kubernetes.io/session-cookie-name: "JOBSESSION"
nginx.ingress.kubernetes.io/session-cookie-max-age: 3600

Kubernetes example 2. Annotations for Traefik Ingress Controller

traefik.ingress.kubernetes.io/affinity: "true"
traefik.ingress.kubernetes.io/session-cookie-name: "JOBSESSION"

While the healthcheck could be implemented using the HTTP status codes of the responses, it is recommended to use the service status request of the REST API. This allows to detect issues quicker and more reliably.

Requirements on clients

It is important the clients support the load balancer’s job session cookie. After creating a job, the cookie must be stored and sent with subsequent requests.

You should use a dedicated cookie store for each job. This enables the load balancer to distribute the processing of multiple jobs to multiple backend servers.

The shell and GUI clients distributed with the Windows version of the Conversion Service adhere to these rules. Therefore, they are suitable to test the load balancer configurations.

Converting Office Documents

The Conversion Service converts Word, Excel, and PowerPoint files to PDF by default using the Standard Converter. No additional configuration is required. For highest visual fidelity, see Convert Microsoft Office files. To add custom fonts, see Fonts in Docker.

Prerequisite​

Docker Compose configuration​

Configure containers using Docker Compose​

Run Docker Compose​

Custom Docker configuration​

Service host address​

HTTPS​

Manage license keys​

Proxy​

Cross-Origin Requests (CORS)​

Use forwarded HTTP headers from WAF​

Load balancer​

Configure the load balancer​

Requirements on clients​