mirror of https://github.com/Stirling-Tools/Stirling-PDF.git synced 2025-06-21 23:15:03 +00:00

Anthony Stirling 2df943e110 init

2025-05-26 00:03:19 +01:00

8.2 KiB

Raw Blame History

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:

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

Install UnoServer using pip:
```
pip install unoserver
```

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:

Tracks conversion failures for each instance
After 3 consecutive failures, marks the instance as unavailable (circuit open)
Waits for a cooldown period (30 seconds) before attempting to use the instance again
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:

Set libreOfficeSessionLimit to a value greater than 1 (e.g., 4)
Start the application

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

Submit multiple file conversion requests simultaneously
Observe in logs that different server instances are being used in a round-robin manner
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:

A status indicator appears when a document is being converted
The indicator shows the current status, position in queue, and estimated wait time
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:

Check logs for any error messages related to UnoServer startup
Look for health check logs to identify problematic instances
Verify ports are not already in use by other applications
Ensure LibreOffice is correctly installed
Check that UnoServer is properly installed and in your PATH:
```
which unoserver
which unoconvert
```
Try running a single UnoServer instance manually to check if it works:
```
/opt/venv/bin/unoserver --port 2003 --interface 127.0.0.1
```
Use the queue status API to check the status of UnoServer instances:
```
curl http://localhost:8080/api/v1/queue/unoserver
```
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

8.2 KiB Raw Blame History