Set up the service in your Docker container

Use the Conversion Service either with Docker Compose or using your 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:
            # Dependant 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:
          # To activate the license, pass the value of the license key.
          LICENSEKEY: ${LICENSE_KEY_VALUE}
          # Pass the URL of the Licensing Gateway Service endpoint
          LICENSINGSERVICE: ${LICENSING_SERVICE_ENDPOINT}
        ports:
            # Exposes port 13033 for external communication.
            - "13033:13033"
        depends_on:
            # Dependant on configuration-updater. The service starts only after the update was completed successfully.
            configuration-updater:
                condition: service_completed_successfully
    
    configuration-updater:
        # Configuraiton 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

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 .env file in the same directory.
Update the .env file to define three 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 the Conversion Service.
- IMAGE_VERSION: Version of the Conversion Service you want to use.
- LICENSING_SERVICE_ENDPOINT: Endpoint where the Licensing Gateway Service is running. The port is 9999.
Open the terminal and navigate to the directory where the docker-compose.yaml and .env files were saved.
Run Docker Compose:
```
docker compose 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

To activate the Conversion Service license, pass the license key 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

Pass the LGS endpoint URL using the LICENSINGSERVICE parameter. The value is the URL of the LGS.

docker run -dp 13033:13033 \
-e LICENSEKEY=4H-VX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX \
-e LICENSINGSERVICE=http://<your-lgs-ip-address>:9999 \
pdftoolsag/conversion-service

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.

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

If you want to convert Word, Excel, and PowerPoint documents to PDF, you need to set up the Office configuration. See Convert Office Documents

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​