mirror of
https://github.com/Stirling-Tools/Stirling-PDF.git
synced 2025-06-21 23:15:03 +00:00
250 lines
8.2 KiB
Markdown
250 lines
8.2 KiB
Markdown
# 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 |