Stirling-PDF/docs/unoserver-configuration.md

UnoServer Configuration Guide

Overview

Stirling-PDF supports multiple UnoServer instances to improve concurrent document conversion performance. This document explains how to configure and use this feature.

The UnoServer component in Stirling-PDF is now conditional, meaning it will only be enabled if the required executables are available on your system. This allows Stirling-PDF to run in environments without LibreOffice/UnoServer while gracefully disabling office document conversion functionality.

Configuration Options

Multiple Local Instances

You can configure Stirling-PDF to start multiple UnoServer instances locally. Each instance will run on its own port starting from the base port.

In settings.yml:

processExecutor:
  sessionLimit:
    libreOfficeSessionLimit: 4  # Set to desired number of instances
  baseUnoconvPort: 2003  # Base port for UnoServer instances
  useExternalUnoconvServers: false  # Set to false to use local instances

External UnoServer Instances

For more advanced setups or when running in a clustered environment, you can configure Stirling-PDF to use external UnoServer instances running on different hosts:

processExecutor:
  useExternalUnoconvServers: true
  unoconvServers:
    - "192.168.1.100:2003"  # Format is host:port
    - "192.168.1.101:2003" 
    - "unoserver-host:2003"

Installation

Docker

The easiest way to use UnoServer with Stirling-PDF is to use the "fat" Docker image, which includes all required dependencies:

docker pull frooodle/s-pdf:latest-fat

Manual Installation

If you want to install UnoServer manually:

1. Install LibreOffice:

   # Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install -y libreoffice
   
   # CentOS/RHEL
   sudo yum install -y libreoffice
   
   # macOS
   brew install libreoffice
   

2. Install UnoServer using pip:

   pip install unoserver
   

3. Verify installation:

   unoserver --version
   unoconvert --version
   

Installation Location

Stirling-PDF will automatically detect UnoServer in these locations:

• In the same directory as the unoconvert executable
• At /opt/venv/bin/unoserver (Docker default)
• In standard system paths (/usr/bin/unoserver, /usr/local/bin/unoserver)
• In your PATH environment variable

Advanced Features

Health Checks

The system performs automatic health checks on all UnoServer instances every 60 seconds. These checks:

• Verify that each server is reachable and operational
• Automatically restart local instances that have failed
• Log the health status of all instances
• Update the circuit breaker status for each instance

Health checks are logged at INFO level and show the number of healthy and unhealthy instances.

Circuit Breaker

For fault tolerance, each UnoServer instance implements a circuit breaker pattern that:

1. Tracks conversion failures for each instance
2. After 3 consecutive failures, marks the instance as unavailable (circuit open)
3. Waits for a cooldown period (30 seconds) before attempting to use the instance again
4. Automatically routes requests to healthy instances

The circuit breaker helps prevent cascading failures and provides automatic recovery.

Performance Metrics

The UnoServerManager records and logs detailed metrics about UnoServer usage:

• Total number of conversions
• Success/failure rate
• Conversions per server instance
• Average conversion time per instance

These metrics are logged periodically and on application shutdown, helping you monitor and optimize performance.

Example metrics log:

UnoServer metrics - Total: 120, Failed: 5, Success Rate: 95.83%
Conversions per instance:
  [0] 127.0.0.1:2003 - Count: 32 (26.67%), Avg Time: 1250.45ms
  [1] 127.0.0.1:2004 - Count: 30 (25.00%), Avg Time: 1187.33ms
  [2] 127.0.0.1:2005 - Count: 29 (24.17%), Avg Time: 1345.78ms
  [3] 127.0.0.1:2006 - Count: 29 (24.17%), Avg Time: 1290.12ms

Testing Multiple Instances

To test that multiple UnoServer instances are working correctly:

1. Set libreOfficeSessionLimit to a value greater than 1 (e.g., 4)
2. Start the application
3. Check logs for messages like:

   Initializing UnoServerManager with maxInstances: 4, useExternal: false
   Starting UnoServer on 127.0.0.1:2003
   Starting UnoServer on 127.0.0.1:2004
   Starting UnoServer on 127.0.0.1:2005
   Starting UnoServer on 127.0.0.1:2006
   

4. Submit multiple file conversion requests simultaneously
5. Observe in logs that different server instances are being used in a round-robin manner
6. Check the metrics logs to verify the load distribution across instances

Performance Considerations

• Each UnoServer instance requires additional memory (typically 100-200 MB)
• Set the libreOfficeSessionLimit according to your server's available resources
• For most use cases, a value between 2-4 provides a good balance
• Larger values may improve concurrency but increase memory usage
• The circuit breaker pattern helps maintain system stability under high load

Queue Management

Stirling-PDF now includes a queue management system for office document conversions:

Queue Status API

The system exposes REST endpoints for checking conversion queue status:

• GET /api/v1/queue/status - Get status of all process queues
• GET /api/v1/queue/unoserver - Get detailed information about UnoServer instances and active tasks
• GET /api/v1/queue/task/{taskId} - Get status of a specific task by ID

Example response from /api/v1/queue/unoserver:

{
  "instanceCount": 4,
  "activeTaskCount": 2,
  "instances": [
    {
      "id": 0,
      "host": "127.0.0.1",
      "port": 2003,
      "managed": true,
      "running": true,
      "available": true,
      "failureCount": 0,
      "averageConversionTimeMs": 1523.45,
      "lastConversionTimeMs": 1498
    },
    ...
  ],
  "activeTasks": [
    {
      "id": "office-123",
      "name": "Convert document.docx to PDF",
      "status": "RUNNING",
      "queuePosition": 0,
      "queueTimeMs": 0,
      "processTimeMs": 542,
      "totalTimeMs": 542,
      "errorMessage": null
    },
    ...
  ]
}

UI Integration

The system includes a built-in UI for monitoring conversion status:

1. A status indicator appears when a document is being converted
2. The indicator shows the current status, position in queue, and estimated wait time
3. For pages that use office conversions, a "Check Office Conversion Status" button provides detailed information about server instances and active conversions

Troubleshooting

If you encounter issues with UnoServer:

1. Check logs for any error messages related to UnoServer startup
2. Look for health check logs to identify problematic instances
3. Verify ports are not already in use by other applications
4. Ensure LibreOffice is correctly installed
5. Check that UnoServer is properly installed and in your PATH:

   which unoserver
   which unoconvert
   

6. Try running a single UnoServer instance manually to check if it works:

   /opt/venv/bin/unoserver --port 2003 --interface 127.0.0.1
   

7. Use the queue status API to check the status of UnoServer instances:

   curl http://localhost:8080/api/v1/queue/unoserver
   

8. For external servers, verify network connectivity from the Stirling-PDF server

Common Error Messages

Error Message	Possible Cause	Solution
"UnoServer is not available"	UnoServer executable not found	Install UnoServer or use the fat Docker image
"Failed to start UnoServer instance"	Port in use or LibreOffice issues	Check ports, restart application, or verify LibreOffice installation
"Circuit breaker opened for UnoServer instance"	Multiple conversion failures	Check logs for specific errors, verify UnoServer is working correctly
"No UnoServer instances available"	All instances are down or in circuit-open state	Restart application or check for resource issues

Environment Variables

When using Docker, you can configure UnoServer instances using environment variables:

• LIBREOFFICE_SESSION_LIMIT: Number of UnoServer instances to start
• BASE_UNOCONV_PORT: Base port number for UnoServer instances
• USE_EXTERNAL_UNOCONVSERVERS: Set to "true" to use external servers