Containerized mode

Use a Docker image to run the Licensing Gateway Service (LGS) in a containerized environment. This setup lets you run the LGS in a Docker container with internet access, introducing Connected mode to Docker containers. For fully offline deployments, review Full offline mode in Docker.

Conversion Service in Docker

If you use the Conversion Service in Docker, use the example file provided in Configure containers using Docker compose documentation to set up containerized mode.

Pdftools OCR Service

The Pdftools OCR Service isn’t supported in Docker environments, which also means you can’t use it with the containerized mode.

Run the LGS in Docker

Prerequisites

• Install Docker or Docker Compose on the machine intended for the LGS. For more details, review Docker documentation.
• The Linux host operating system of the Docker container requires glibc 2.34+.

Run the Docker container

To run the LGS in a Docker container:

1. Find the official Pdftools LGS Docker image in the Docker Hub: pdftoolsag/license-gateway
2. Start the LGS container with the necessary configurations:

   docker run -p 9999:9999 \
       -e LICENSE_KEYS="YOUR_LICENSE_KEY" \
       pdftoolsag/license-gateway:latest

   Replace YOUR_LICENSE_KEY with your actual license key. Separate multiple keys with a semicolon (;):

   -e LICENSE_KEYS="LICENSE_KEY_1;LICENSE_KEY_2"

note

This container requires an active internet connection to synchronize license data. During shutdown, an internet connection is also required to prevent data inconsistencies and blocked licenses.

Port mapping

By default, the LGS runs on port 9999.

• Port mapping, default set to: -p 9999:9999
  • This configuration maps the LGS internal API port to port 9999 on the host machine.
  • To change the host port, update the configuration in the product or command-line tool accordingly.

Docker Compose

If you prefer to use Docker Compose, create a docker-compose.yml file with the following content:

services:
  license-gateway:
    image: pdftoolsag/license-gateway:latest
    ports:
      - "9999:9999"
    environment:
      - LICENSE_KEYS=YOUR_LICENSE_KEY

You can also use multiple license keys separated by a semicolon (;):

services:
  license-gateway:
    image: pdftoolsag/license-gateway:latest
    ports:
      - "9999:9999"
    environment:
      - LICENSE_KEYS=LICENSE_KEY_1;LICENSE_KEY_2

Configure a forward proxy

If the LGS container connects to the Pdftools Licensing Server through a forward proxy, pass the proxy configuration as environment variables. For a description of each property, review Configure a forward proxy in the connected mode documentation.

To configure a forward proxy with docker run:

docker run -p 9999:9999 \
    -e LICENSE_KEYS="YOUR_LICENSE_KEY" \
    -e FORWARDPROXY__ADDRESS="PROXY_ADDRESS" \
    -e FORWARDPROXY__USERNAME="PROXY_USERNAME" \
    -e FORWARDPROXY__PASSWORD="PROXY_PASSWORD" \
    -e FORWARDPROXY__BYPASSONLOCAL="true" \
    pdftoolsag/license-gateway:latest

Replace the following:

• YOUR_LICENSE_KEY: Your license key.
• PROXY_ADDRESS: The forward proxy URL including port, for example http://proxy.example.com:8080.
• PROXY_USERNAME: The username for proxy authentication. Omit this variable for non-authenticated proxies.
• PROXY_PASSWORD: The password for proxy authentication. Omit this variable for non-authenticated proxies.

To configure a forward proxy with Docker Compose, add the environment variables to your docker-compose.yml file:

services:
  license-gateway:
    image: pdftoolsag/license-gateway:latest
    ports:
      - "9999:9999"
    environment:
      - LICENSE_KEYS=YOUR_LICENSE_KEY
      - FORWARDPROXY__ADDRESS=PROXY_ADDRESS
      - FORWARDPROXY__USERNAME=PROXY_USERNAME
      - FORWARDPROXY__PASSWORD=PROXY_PASSWORD
      - FORWARDPROXY__BYPASSONLOCAL=true

For non-authenticated proxies, omit FORWARDPROXY__USERNAME and FORWARDPROXY__PASSWORD or set them to empty strings.

Automatic LGS deactivation

Each license can have a maximum number of LGS instances connected to it, and certain licenses allow unlimited numbers of LGS instances.

When you exceed the maximum number of instances, the license becomes blocked. To prevent the license from being blocked, the LGS automatically deactivates itself from the pool of LGS instances associated with the license key when the Docker container shuts down.

Deactivation of the LGS for a given license key occurs automatically when the Docker container shuts down. To ensure this process works correctly, always gracefully shut down the container:

docker stop CONTAINER_ID

If the container can’t connect to the internet during shutdown, it may fail to transfer data properly, potentially blocking the licenses. In such cases, contact Pdftools support to resolve the issue.

Full offline mode in Docker

Full offline mode lets you run the LGS in Docker containers without an internet connection. Each LGS instance requires its own persistent volume to store licensing data. Define each instance as a separate Docker Compose service rather than using replicas, because replicas share a single volume definition.

Configure offline LGS containers

To set up full offline mode, set the ISOFFLINEMODE environment variable to true and mount a named volume to /usr/share/Pdftools/Data on each LGS container.

In offline mode, the LICENSE_KEYS environment variable isn’t required at container startup. License keys are activated after the containers are running through the activation procedures.

The following docker-compose.yml example configures two offline LGS instances:

services:
  lgs-1:
    image: pdftoolsag/license-gateway:latest
    ports:
      - "9991:9999"
    environment:
      - ISOFFLINEMODE=true
    volumes:
      - lgs-1-data:/usr/share/Pdftools/Data

  lgs-2:
    image: pdftoolsag/license-gateway:latest
    ports:
      - "9992:9999"
    environment:
      - ISOFFLINEMODE=true
    volumes:
      - lgs-2-data:/usr/share/Pdftools/Data

volumes:
  lgs-1-data:
  lgs-2-data:

Each service maps a different host port (for example, 9991 and 9992) to the internal LGS port 9999.

Activate and deactivate licenses

After the containers are running, activate and deactivate license keys using the same procedures described in the Full offline mode documentation. To manage multiple LGS instances at once, use the batch activation and deactivation commands.