x
Skip to main content

LibreOffice Parallel Processing

Stirling PDF uses LibreOffice for converting office documents (DOCX, XLSX, PPTX, etc.) to PDF and other formats. LibreOffice processes each conversion in a single thread, meaning one conversion uses one CPU core at 100% regardless of how many cores are available. To process multiple conversions at the same time, you need to run multiple LibreOffice instances.

Local UNO Server Pool​

By default, Stirling PDF manages a local pool of UNO (Universal Network Objects) server instances. The number of instances is controlled by the libreOfficeSessionLimit setting.

processExecutor:
  autoUnoServer: true
  sessionLimit:
    libreOfficeSessionLimit: 4  # Run 4 LibreOffice instances

Each additional instance consumes approximately 50 MB of RAM when idle and significantly more during active conversion. A reasonable starting point is one instance per 2 CPU cores, adjusted based on available RAM and expected workload.

info

The default libreOfficeSessionLimit is 1, meaning only one conversion runs at a time. If you see conversions queuing up or running slowly, increasing this is the first thing to try.

Remote UNO Server Endpoints​

For larger deployments or when you want to isolate LibreOffice from the main application, you can run UNO servers as separate containers and configure Stirling PDF to connect to them remotely.

Set autoUnoServer to false and define your remote endpoints:

processExecutor:
  autoUnoServer: false
  unoServerEndpoints:
    - host: "unoserver1"
      port: 2003
      hostLocation: "remote"
      protocol: "http"
    - host: "unoserver2"
      port: 2003
      hostLocation: "remote"
      protocol: "http"
    - host: "unoserver3"
      port: 2003
      hostLocation: "remote"
      protocol: "http"

To add more endpoints, add additional entries to the unoServerEndpoints list in settings.yml, or for environment variables, increment the index number (e.g. _0_ for the first, _1_ for the second, _2_ for the third, and so on).

Endpoint Configuration​

The host field accepts a Docker service name (e.g. unoserver1), a DNS hostname (e.g. uno.internal.example.com), or an IP address (e.g. 192.168.1.50). The default is 127.0.0.1.

The hostLocation setting controls how files are transferred between Stirling PDF and the UNO server:

ValueWhen to UseHow It Works
autoDefault, detects automaticallyChecks if the host is local or remote
localUNO server is on the same machineFiles are passed via filesystem paths (fastest)
remoteUNO server is a separate container or machineFiles are transferred over HTTP
caution

Use remote when running UNO servers in separate Docker containers, even if the containers are on the same host machine. The containers don't share a filesystem, so local will not work.

Running UNO Servers Without Docker​

If you are running Stirling PDF without Docker (bare metal or systemd), you can start additional UNO server instances manually using the unoserver Python package:

# Install unoserver (included in Docker images)
pip install unoserver

# Start instances on different ports
unoserver --port 2003 &
unoserver --port 2004 &
unoserver --port 2005 &

Then configure Stirling PDF to connect to these instances at 127.0.0.1 on the respective ports with hostLocation: "local".

Timeout Configuration​

LibreOffice conversion has a default timeout of 30 minutes. For very large or complex documents, you may need to increase this:

processExecutor:
  timeoutMinutes:
    libreOfficetimeoutMinutes: 60

If conversions are consistently timing out, this usually indicates the system is under-resourced rather than needing a longer timeout. Check CPU and memory usage first.