Skip to main content

Set up the service in your Docker container

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

License key​

You pass the license key using one of the following environment variables:

LICENSEKEY: The value is the license key.

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

LICENSEKEY_FILE: The value is the 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

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