Skip to main content

Conversion Service in Docker

Learn how to run the Conversion Service in Docker to automate document processes.

Request trial or full license​

It's necessary to have a license key to try or fully use the Conversion Service. To get the Conversion Service license key:

  1. Reach out to the sales team through the Contact page and mark the Conversion Service as the product of your interest for a trial license.

Prerequisites​

The following sections use examples running with Docker Compose:

  • Install Docker Compose to run the Conversion Service in Docker.

To configure and run the Conversion Service, you need Conversion Service installed at least on one Windows Server or Windows machine to export configuration files. The Windows Server installation requires the following .NET runtimes from the Download .NET website:

  • .NET Framework 4.7
  • .NET Desktop Runtime 8.0 (x64)
  • ASP.NET Core Runtime 8.0 (x64)
note

The indicated versions are the minimal versions that are supported. You can use a newer version also.

info

Installing Conversion Service on Windows 10 or 11 is possible, although we recommend using it only to export the configuration files, as demonstrated further in this documentation. Pdftools provides official support for the Conversion Service for the Windows Server or Docker containers listed in the Compatible operating systems. If you use Windows 10 or Windows 11 for regular use of the Conversion Service, you may not receive the full support.

Install Conversion Service on Windows​

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 My PDF Tools Portal, and then click Licenses & Kits.

  2. Click Conversion Service.

  3. In ACTIVE LICENSES or EVALUATIONS sections, find the Conversion Service MSI, and then click DOWNLOAD. The filename can be for example ConversionService-5.3.3.4801.msi.

  4. Optional: For installation on Windows 10 or 11, disable the following variable of the MSI package using a command line interface:

    msiexec /i ConversionService-{specify-version-number}.msi PDF_TOOLS_DISABLE_OS_CHECK=1

    Replace {specify-version-number} with the exact numbers in the name of the downloaded MSI package.

  5. Run the MSI installation package and follow the instructions on the screen.

  6. In the My PDF Tools Portal, go to Licenses & Kits, and then click Conversion Service.

  7. In the License section, click the LICENSE button to reveal the license key, and then click COPY.

  8. Open Conversion Service Configurator, and then click the License tab.

    License tab in the Configurator.

  9. Paste the license key into the Key field and click Add.

The MSI installs the following components:
  • PDF Client for Conversion Service with the following interfaces:
    • Graphical user interface (GUI) client
    • Shell client
  • Conversion Service Configurator
  • 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
            environment:
                # To activate the Conversion Service, pass the value of the license key.
                LICENSEKEY: YOUR-LICENSE-KEY-VALUE
                LICENSINGSERVICE: http://IP-ADDRESS-OF-THE-LICENSING-GATEWAY-SERVICE:9999
            ports:
                # Exposes port 13033 for external communication.
                - "13033:13033"
    • Replace YOUR-LICENSE-KEY-VALUE with your actual license key. Use the same license key as the one you copied and activated in the previous section.
    • Replace IP-ADDRESS-OF-THE-LICENSING-GATEWAY-SERVICE with the IP address of the machine where you installed the Conversion Service on Windows. The 9999 port is recommended for this operation.
  2. Optional: If you run the Conversion Service on the same machine where you want to run the Docker instance, 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 differently

The LICENSINGSERVICE parameter configures the Licensing Gateway Service (LGS) endpoint. The LGS sends your hostname and the number of processed pages (license usage data). No other data about the documents you processed is sent. In the demonstrated configuration, the Windows machine sends usage data of your Docker container.

You can install and configure the LGS in a Docker container or any other machine and let it send license usage data for an unlimited number of Conversion Service instances with just one license key.

For more details about the LGS, review the following pages:

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 Stamping toggle.

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

    Screenshot of the Stamping 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 upper right 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
            environment:
                # To activate the Conversion Service, pass the value of the license key.
                LICENSEKEY: YOUR-LICENSE-KEY-VALUE
                LICENSINGSERVICE: http://IP-ADDRESS-OF-THE-LICENSING-GATEWAY-SERVICE:9999
                IMPORT_PROFILES: /etc/convsrv/ProfileExport-5.5.1.export
            ports:
                # Exposes port 13033 for external communication.
                - "13033:13033"
            volumes:
                - C:/Users/john-doe/Desktop/ProfileExport-5.5.1.export:/etc/convsrv/ProfileExport-5.5.1.export
    • Replace ProfileExport-5.5.1.export filename with the name of your export file.
    • Replace C:/Users/john-doe/Desktop/ProfileExport-5.5.1.export with the file path and the name of the exported profile on your Windows machine.
    • Replace YOUR-LICENSE-KEY-VALUE with your actual license key. Use the same license key as the one you copied and activated in the previous section.
    • Replace IP-ADDRESS-OF-THE-LICENSING-GATEWAY-SERVICE with the IP address of the machine where you installed the Conversion Service on Windows. The 9999 port is recommended for this operation.

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

    docker compose up
info

If you use text stamps rather than demonstrated QR code, ensure to install Calibri fonts in your Docker container to use the custom stamp.

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.

Configure Microsoft Office file conversion​

Learn how to configure Microsoft Office file conversion in Docker with the Microsoft Office for Web.

Prerequisites

To enable Microsoft Office file conversion in Docker, you need:

  • Account for Microsoft Office for Web.
  • Conversion Service profile with Microsoft Office conversion enabled. Most profiles have this conversion enabled, review Configure and export a profile.

  1. Edit the docker-compose.yaml as follows:

    volumes:
        vol-conversion-srv-app-data: {}
    services:
        conversion-service:
            # Conversion Service image - Converts files to PDF format.
            image: pdftoolsag/conversion-service
            environment:
                # To activate the license, pass the value of the license key.
                LICENSEKEY: YOUR-LICENSE-KEY-VALUE
                LICENSINGSERVICE: http://IP-ADDRESS-OF-THE-LICENSING-GATEWAY-SERVICE:9999
                IMPORT_PROFILES: /etc/convsrv/ProfileExport-5.5.1.export
                SERVICE__OFFICE__TYPE: OfficeWebService
                SERVICE__OFFICE__USERNAME: YOUR-OFFICE-USERNAME
            ports:
                # Exposes port 13033 for external communication.
                - "13033:13033"
            volumes:
                - vol-conversion-srv-app-data:/etc/convsrv
                - C:/Users/john-doe/Desktop/ProfileExport-5.5.1.export:/etc/convsrv/ProfileExport-5.5.1.export
    • Replace YOUR-OFFICE-USERNAME with username of the account you want to use for Microsoft Office conversion.
    • Replace C:/Users/john-doe/Desktop/ProfileExport-5.5.1.export with the file path and the name of the exported profile on your Windows machine.

  2. In the directory where the docker-compose.yaml is located, run the following command:

    docker compose up -d

  3. In the same directory, run:

    docker ps

  4. Copy the container ID where you run the Conversion Service. This ID can have a form similar to: 09d8dcaiel23

    note

    The docker ps also displays the container name. Every time you run the docker compose up -d, a new ID is generated, and you need to copy this ID again.

  5. Grant the Conversion Service user access to the volume data inside the container by running the following command:

    docker exec -u root CONTAINER_ID_OR_NAME chown convsrv:convsrv /etc/convsrv/
    • Replace CONTAINER_ID_OR_NAME with your container's name or ID.

  6. Run the following command to configure the Microsoft Office user:

    docker exec CONTAINER_ID_OR_NAME ./bin/csconfig office webinit
    • Replace CONTAINER_ID_OR_NAME with your container's name or ID.

    The output is a message with the next steps specified. Review the example below:

    Office webinit output

  7. Open the provided link, and then enter the code.

  8. Log in with the username that you added as the value of the SERVICE__OFFICE__USERNAME environment variable in the first step of this configuration.

  9. In the PDF Client for Conversion Service, drag a Microsoft Office file to the Input box.

  10. In the Profile drop-down list, select a profile with Microsoft Office enabled. For example: awesome-test-profile

  11. 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.

  12. Click Convert.

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 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.