Skip to main content

Conversion Service in Docker

Learn how to run Conversion Service in Docker, configure it in your browser, and convert your first file. You configure the service in Configurator Web, so a Windows machine isn’t required.

Trial license​

Conversion Service 6.12 and later automatically registers a built-in trial license on every fresh installation, on Windows, in Docker, and on Linux. The service starts fully licensed, so you don’t need a license key to try Conversion Service. The trial license adds a watermark to converted files and doesn’t expire.

In the Conversion Service Configurator, the trial license appears as TRIAL-LICENSE in the Key field on the License tab.

Docker

In Docker, the container registers the trial license only when you don’t pass a license key with the LICENSEKEY or LICENSEKEY_FILE environment variable.

To convert files without a watermark, replace the trial license with a full license key.

Request full license​

tip

The built-in trial license lets you try Conversion Service at no cost. To convert files without a watermark, request a full license key.

To request a full license key, follow these steps:

  1. Sign up or log in to the Pdftools Portal.
  2. On the Products page, next to the Conversion Service, click Request license.
    Screenshot of the Pdftools Portal's product page.
  3. On the Contact us window, fill in the requested fields, and then click Submit.

After you receive your full license key, replace the trial license with it. For more details, review Add or remove a license key.

Prerequisites​

Before you start, install Docker Compose.

Run Conversion Service in Docker​

To start Conversion Service, follow these steps:

  1. Create a file named docker-compose.yaml and insert the following code:

    volumes:
        vol-conversion-srv: {}
        vol-connector-srv: {}
    services:
        conversion-service:
            # Conversion Service image. Converts files to PDF format.
            image: pdftoolsag/conversion-service:IMAGE_VERSION
            volumes:
                # Shared configuration: workflows, profiles, and service settings.
                - vol-conversion-srv:/var/www/convsrv/bin/config
            ports:
                # Exposes port 13033 for the REST API and the MCP endpoint.
                - "13033:13033"
        connector-service:
            # Connector Service image. Provides watched folders and REST input connectors,
            # and creates the connection configuration that Configurator Web reads.
            image: pdftoolsag/connector-service:IMAGE_VERSION
            volumes:
                - ./watched:/app/watched-folders/
                - vol-connector-srv:/app/config
            ports:
                # Exposes port 13034 for external communication.
                - "13034:13034"
        configurator-web:
            # Configurator Web image. Configures workflows, profiles, and connections
            # in the browser, and runs test conversions in the Playground.
            image: pdftoolsag/configurator-web:IMAGE_VERSION
            volumes:
                - vol-conversion-srv:/app/conversion-config
                - vol-connector-srv:/app/connector-config
                - ./watched:/app/watched-folders/:ro
            ports:
                # Exposes port 13035 on this machine only, because Configurator Web has no sign-in.
                - "127.0.0.1:13035:13035"

    Replace the following placeholder with a specific value:

    • IMAGE_VERSION: The Conversion Service version number, for example, 6.13.0, 6.13, or 6. The placeholder occurs once per service, and all three services must use the same version.
    macOS on Apple Silicon

    Pdftools publishes the Conversion Service images for linux/amd64 only, so on a Mac with Apple Silicon, docker compose up fails with no matching manifest for linux/arm64/v8 in the manifest list entries. To run the images under emulation, add platform: linux/amd64 to each of the three services in docker-compose.yaml.

    Without a license key, containers running version 6.12.0 or later register the built-in trial license at startup, and converted files have a watermark. To convert files without a watermark, pass your full license key with the LICENSEKEY environment variable:

        conversion-service:
            # ... same configuration as in the preceding example, plus:
            environment:
                # To activate Conversion Service, pass the value of the license key.
                LICENSEKEY: LICENSE_KEY_VALUE

    Replace the following placeholder with a specific value:

    • LICENSE_KEY_VALUE: Your Conversion Service license key.
    Replace the placeholder or leave the variable out

    LICENSEKEY must hold a real license key. A container that starts with the LICENSE_KEY_VALUE placeholder still in place stops immediately and logs the fatal error Invalid license key. Without the variable, the container falls back to the built-in trial license.

  2. In the directory that holds the docker-compose.yaml, create the watched-folder directory and start the containers:

    mkdir watched
    docker compose up -d

  3. Confirm that Conversion Service is running:

    curl http://localhost:13033/conversion/v1.0/rest

    The service reports its version and status:

    {"version":"6.13.0.34931","status":"running","startTime":"2026-09-21T11:40:18.1352985+00:00","isolation":{"processCount":2,"queueLength":0},"jobCounts":{"creating":0,"processing":0,"completed":0,"total":0}}

The three containers expose the following ports:

PortServicePurpose
13033Conversion ServiceAdvanced API and MCP endpoint
13034Connector ServiceSimple API (REST input connectors)
13035Configurator WebBrowser-based configuration and the Playground

Set up licensing​

By default, Conversion Service validates your license key directly, with no extra components to set up. Provide your key with the LICENSEKEY environment variable in your docker-compose.yaml. Without a key, the built-in trial license applies and converted files carry a watermark.

Optionally, route licensing through the Licensing Gateway Service (LGS) to share one license key across many Conversion Service instances or to license offline. For a Docker Compose example, review Configure containers using Docker Compose. For licensing concepts, review Conversion Service licensing.

Open Configurator Web​

Configurator Web is the browser-based configuration application for Conversion Service. In Docker deployments, it replaces the Windows-based Conversion Service Configurator.

To open Configurator Web, browse to http://localhost:13035. Health & Activity opens first and reports whether Conversion Service is reachable:

Health and Activity page of Configurator Web, reporting Conversion Service as running, with the page navigation on the left.

The navigation on the left leads to the configuration pages, such as Workflows and Integration, and to the Playground for test conversions. For a description of each page, refer to Configurator Web.

Configurator Web has no sign-in, so the Compose file publishes port 13035 only on the local machine. To open Configurator Web from another machine, refer to Restrict access.

Keep the service name conversion-service

Configurator Web edits the same configuration files that Conversion Service and the Connector Service read, through the vol-conversion-srv and vol-connector-srv volumes. It resolves Conversion Service under the Docker Compose service name conversion-service. If you rename that service, Configurator Web can’t report its health or run Playground conversions.

Convert your first file​

Convert a PDF file to PDF/A with the Archive as PDF/A-2 workflow and its default profile, either in the browser or from a terminal. The Advanced API identifies this workflow by its technical name, Archive PDF/A-2.

Use PDF/A-2 in Docker

Docker containers can’t rasterize document content, so the Archive as PDF/A-1 workflow can cause visual differences or remove transparency. PDF/A-2 allows transparency, layers, and embedded files, so the Archive as PDF/A-2 workflow produces fewer conversion errors. For details, review Features and limitations.

  1. In Configurator Web, select Playground.

  2. Drag a PDF file onto the Input area, or click it to select a file.

    Playground tab in Configurator Web with an empty drag-and-drop input area and conversion options.

  3. In Conversion Options, confirm that Service reports Conversion Service as reachable.

  4. In Workflow, select Archive as PDF/A-2, and in Profile, select default.

  5. Click Convert.

    Status reports the progress and lists the output file for download.

For the complete description of the conversion options, review Playground.

Create a custom profile​

Configure a custom profile that adds a QR code to converted documents. You create the profile in Configurator Web, and Conversion Service applies it after a restart.

Workflows and Profiles page of Configurator Web, showing each workflow with its toggle, its profiles, and the Add Profile button.

To create the profile, follow these steps:

  1. In Configurator Web, select Workflows.

  2. In Archive as PDF/A-2, click Add Profile.

  3. In New profile name, enter a name, for example, awesome-test-profile, and then click Create.

  4. Open the new profile, and then enable Stamps & Annotations.

  5. In Stamps, click Add Stamp, and then select Code.

  6. In Code Type, select QR, and in Value, enter the content of the QR code, for example, Hello world.

  7. In Layout, enter a value in Width and Height, for example, 3, and select a unit next to each value, for example, cm. Without a unit, Save Changes stays unavailable.

    With only Width and Height set, the QR code appears in the center of the page.

  8. Click Save Changes before you open another page. Configurator Web discards unsaved changes without a warning.

    Configurator Web displays a banner that asks you to restart the service.

  9. Restart the Conversion Service container:

    docker compose restart conversion-service

To convert a file with the new profile, repeat Convert your first file and select your profile instead of default. In the Advanced API, pass the profile name in the profile query parameter.

Available fonts

If you add a Text stamp or annotation rather than the demonstrated QR code, ensure that the selected font family is installed in the Docker container. For example, Configurator Web selects Calibri fonts for text stamps by default, but you must install the Calibri font family to finish the processing successfully.

Optional: Reuse a configuration from Windows​

If you already maintain profiles in the Conversion Service Configurator on Windows, export them and import them into your Docker deployment instead of recreating them in Configurator Web. The version of Conversion Service on Windows and the version of the container images must match.

To install Conversion Service on Windows first, refer to Conversion Service on Windows Server.

info

Installing Conversion Service on Windows 10 or 11 is possible, although we recommend using it only to export the configuration files. Pdftools provides official support for Conversion Service on the Windows Server versions and Docker containers listed in Compatible operating systems. If you run Conversion Service on Windows 10 or Windows 11 for production purposes, you may not receive our full support.

To reuse the profiles, follow these steps:

  1. Optional: If you run the Docker containers on the same machine, free ports 13033 and 13034 for the containers. In the Conversion Service Configurator, open Conversion Service, and then click Stop.

  2. In the Conversion Service Configurator, open Workflows & Profiles, click the vertical three dots menu, and then click Export Profiles.

    Export Profiles menu item in the Workflows and Profiles tab of the Conversion Service Configurator.

  3. Select the profiles to export or click Select All, and then click Export and select the file destination.

    Profile selection list in the Export Profiles dialog box of the Conversion Service Configurator.

  4. In Configurator Web, select Workflows.

  5. Click Import Profiles, and then select the exported file, for example, ProfileExport-6.13.0.export.

    Workflows and Profiles page of Configurator Web, with the Import Profiles icon highlighted to the left of the Export Profiles icon in the title row.

    The Import Profiles dialog box lists the profiles in the file by workflow, with every profile selected.

  6. Clear the profiles that you don’t want to import, and then click Import.

    If a selected profile has the same name as an existing one, choose whether to replace the original or keep both.

  7. Click Save Changes before you open another page. Configurator Web discards unsaved changes without a warning.

    Configurator Web displays a banner that asks you to restart the service.

  8. Restart the Conversion Service container:

    docker compose restart conversion-service

To import the profiles automatically when the container starts, for example, in an automated deployment, set the IMPORT_PROFILES environment variable instead. Refer to Set a profile when starting the Docker container.

Next steps​

You ran Conversion Service in Docker, configured it in Configurator Web, converted a file, and created a custom profile. Review the following documentation for more details:

Integrate Conversion Service into your system in several ways: