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`:

```yaml
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:

```yaml
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:

```bash
docker pull frooodle/s-pdf:latest-fat
```

### Manual Installation

If you want to install UnoServer manually:

1. Install LibreOffice:
   ```bash
   # 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:
   ```bash
   pip install unoserver
   ```

3. Verify installation:
   ```bash
   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`:

```json
{
  "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