Skip to main content

Conversion Service in Docker

Learn how to run the Conversion Service in Docker.

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​

The following sections use examples running with Docker Compose:

  • You have Docker Compose installed to run the Conversion Service in Docker.
  • You have a Windows Server or Windows machine to export configuration files.
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 the Conversion Service for the Windows Server or Docker containers listed in the Compatible operating systems. If you run the Conversion Service on Windows 10 or Windows 11 for production purposes, you may not receive our full support.

Install Conversion Service on Windows​

Windows installation prerequisites

For the Conversion Service on Windows or Windows Server machine, you need the following dependencies installed:

Install the Conversion Service on Windows Server or Windows 10 or 11 so you can export configuration files to your Docker instance with the following steps:

  1. Log in to the Pdftools Portal.
  2. On the Products page, next to the Conversion Service, click Get started or See product.
    Screenshot of the Pdftools Portal's product page.
  3. In the Product builds section, find the conversion-service-VERSION_NUMBER.msi package, and then click Download . The exact filename, for example, conversion-service-6.12.0.msi, depends on the version you are installing.
    Screenshot of the Pdftools Portal's Conversion Service product page. The screenshot is focused on the Product builds section detail.
    Ensure to download conversion-service-VERSION_NUMBER.msi not conversion-service-client-VERSION_NUMBER.msi due to the focus of this guide.
  4. Open the conversion-service-VERSION_NUMBER.msi installer and proceed with the guided installation.1

The installation automatically registers the built-in trial license, so you don’t need to add a license key. To replace the trial license with a full license key, review Add or remove a license key.

Installation details​

The conversion-service-VERSION_NUMBER.msi installs the Conversion Service itself and provides the following applications that let you configure workflow profiles and more:

  • Conversion Service Configurator
  • PDF Client for Conversion Service
  • Conversion Service shell client (CLI)
  • Licensing Gateway Service

Run Conversion Service in Docker​

To run the Conversion Service in a Docker container, follow these steps:

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

    services:
        conversion-service:
            # Conversion Service image. Converts files to PDF format.
            image: pdftoolsag/conversion-service:IMAGE_VERSION
            ports:
                # Exposes port 13033 for external communication.
                - "13033:13033"

    Replace IMAGE_VERSION with the Conversion Service version number. For example: 6.12.0, 6.12, 6

    When you don’t pass 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:

    services:
        conversion-service:
            # Conversion Service image. Converts files to PDF format.
            image: pdftoolsag/conversion-service:IMAGE_VERSION
            environment:
                # To activate the Conversion Service, pass the value of the license key.
                LICENSEKEY: LICENSE_KEY_VALUE
            ports:
                # Exposes port 13033 for external communication.
                - "13033:13033"

    Replace LICENSE_KEY_VALUE with your license key.

  2. Optional: If you run the Conversion Service Docker instance within a machine where you also run the Conversion Service (for Windows or Windows Server), you need to free up one of the used ports. Go to the Conversion Service Configurator, open the Conversion Service tab and then click Stop. This action frees port 13033 for the Docker instance.

  3. In the directory where you created the docker-compose.yaml, run the following command:

    docker compose up -d

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.

Convert file​

Learn how to convert files using the Conversion Service Docker instance through the PDF Client for Conversion Service. Convert a PDF file to PDF/A using the default configuration:

  1. In the PDF Client for Conversion Service, drag a PDF file to the Input box.
    Screenshot of the PDF Client for Conversion Service.
  2. Optional: If you are running the Docker instance on a machine other than the one where you installed Conversion Service on Windows, click the vertical three-dot menu, click Settings, add the IP address of your Docker instance, and then click Apply.
  3. In the Profile drop-down list, select the Default profile.
  4. Click Convert.
info

In the PDF Client for Conversion Service, you can select various workflows and profiles to choose specific conversion types. You can also change the filename of the output file.

Configure and export a profile​

Configure a custom profile to add a QR code to converted documents and export the configuration to your Docker container:

  1. In your Windows machine, open the Conversion Service Configurator, go to Workflows & Profiles.

  2. Next to Archive PDF/A-2, click Add.

  3. Create a name for the new profile. For example: awesome-test-profile

    Screenshot of the Conversion Service Configurator Workflows & Profiles tab.

  4. In the Processing Steps section, enable the Stamp and Annotation toggle.

  5. Scroll down to the Stamp and Annotation section, and then click Add item.

    Screenshot of the Stamp and Annotation section in the Conversion Service Configurator Workflows & Profiles tab.

  6. Click Barcode Stamp, and then click Next.

  7. In the Type field, select QR.

  8. In the Value field, enter any text you like (it can be a website link). For example: Hello world

  9. Scroll down to the Layout section, and set the Width and Height. For example, set it to 3 cm.

  10. Optional: To display the stamp in the top left corner of the PDF file, edit other parameters in the Layout section as follows:

    Screenshot of the Stamping layout configuration.

    If you don’t specify any values in the Layout section, the QR code is displayed in the center of the page.

  11. Click Apply, then click Apply in the Configurator again.

  12. In the Changes detected dialog box, click Save & Restart Service.

  13. In the Workflows & Profiles page, click the vertical three dots menu, and then click Export Profiles.

    Screenshot of the Stamping layout configuration.

  14. Select the name of the profile you want to export, for example: awesome-test-profile, or click Select All to export all profiles.

    Screenshot of the Stamping layout configuration.

  15. Click Export, and then select the file destination.

  16. Edit the docker-compose.yaml to mount the configuration file from your Windows machine:

    services:
        conversion-service:
            # Conversion Service image. Converts files to PDF format.
            image: pdftoolsag/conversion-service:IMAGE_VERSION
            environment:
                # Optional: To convert files without a watermark, pass the value of your full license key.
                LICENSEKEY: LICENSE_KEY_VALUE
                IMPORT_PROFILES: /etc/convsrv/PROFILE_EXPORT_FILE
            ports:
                # Exposes port 13033 for external communication.
                - "13033:13033"
            volumes:
                - HOST_PROFILE_DIR/PROFILE_EXPORT_FILE:/etc/convsrv/PROFILE_EXPORT_FILE

    Replace the following:

    • IMAGE_VERSION: The Conversion Service version number (for example, 6.12.0, 6.12, or 6).
    • LICENSE_KEY_VALUE: The Conversion Service license key. To use the built-in trial license instead, remove the LICENSEKEY variable.
    • HOST_PROFILE_DIR: The directory on the host machine that contains the exported profile (for example, C:/Users/john-doe/Desktop).
    • PROFILE_EXPORT_FILE: The filename of the exported profile (for example, ProfileExport-6.12.0.export).

  17. In the directory where you created the docker-compose.yaml, run the following command:

    docker compose up
Available fonts

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

Convert file using custom profile​

Learn how to apply a profile created in the section Configure and export a profile. Convert a PDF file to PDF/A using your custom profile configuration:

  1. In the PDF Client for Conversion Service, drag a PDF file to the Input box.
  2. In the Profile drop-down list, select a created custom profile. For example: awesome-test-profile
  3. Optional: If you are running the Docker instance on a machine other than the one where you installed Conversion Service on Windows, click the vertical three-dot menu, click Settings, add the IP address of your Docker instance, and then click Apply.
  4. Click Convert.

Microsoft Office file conversion​

The Conversion Service converts Word (DOCX), Excel (XLSX), and PowerPoint (PPTX) files to PDF out of the box using the Standard Converter. No additional configuration is required for fresh installations, and the Docker image ships with metric-compatible fonts (Carlito, Caladea, Liberation, Noto, DejaVu, and Microsoft core fonts) so that documents retain their original layout.

To convert a Microsoft Office file:

  1. In the PDF Client for Conversion Service, drag a Microsoft Office file to the Input box.
  2. In the Profile drop-down list, select a profile with Office conversion enabled. Most profiles have this option enabled by default.
  3. Optional: If you are running the Docker instance on a machine other than the one where you installed Conversion Service on Windows, click the vertical three-dot menu, click Settings, add the IP address of your Docker instance, and then click Apply.
  4. Click Convert.

If you need pixel-perfect layout preservation, password-protected files, or the legacy binary formats DOC, PPT, and PPS, configure the Office for the web service or delegate Office jobs to a Conversion Service instance running on Windows with a local Microsoft Office installation. To add corporate or proprietary fonts to the container, see Add custom fonts.

note

If you experience any issues during configuration or conversion, refer to the Troubleshooting in the Convert Microsoft Office files documentation.

Next steps​

For more details about Docker configuration, see Set up the service in Docker page.

You learned how to run the Conversion Service in Docker, convert a file using default profile, create a custom profile, export it, and convert a file using custom profile. Review the following documentation for more details:

There are several ways you can integrate the Conversion Service into your system:

Use PDF/A-2 instead of PDF/A-1 in Docker​

The PDF/A-2 is based on a newer version of the PDF standard than PDF/A-1, more PDF features are allowed such as transparency, layers, embedded files, and a less restrictive internal file structure. For these reasons, achieve fewer conversion errors and better conversion quality with the Archive as PDF/A-2 workflow. Particularly, if you use the Conversion Service in a Docker container where document content rasterization is unavailable, use PDF/A-2 workflow instead to avoid visual differences, removed transparency, or other potential issues. For more information, review Features and limitations.

Footnotes​

  1. During the installation on the Windows Server or Windows machine, the installer automatically prompts you to install the following dependencies:

    ↩