diff --git a/docs/API.md b/docs/API.md index 9bdcea06..50f4a97b 100644 --- a/docs/API.md +++ b/docs/API.md @@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem'; Stirling PDF exposes a simple API for easy integration with external scripts. You can access the API documentation in two ways: -1. Local Swagger UI at `/swagger-ui/index.html` on your Stirling PDF instance +1. Local Swagger UI at `/swagger-ui.html` on your Stirling PDF instance 2. Online [Swagger Documentation](https://app.swaggerhub.com/apis-docs/Frooodle/Stirling-PDF/) You can also access the documentation through the settings menu (gear icon in the top-right corner). @@ -22,8 +22,8 @@ You can also access the documentation through the settings menu (gear icon in th ### Local Swagger UI Your Stirling PDF instance includes built-in API documentation: -1. Navigate to `http://your-instance:port/swagger-ui/index.html` -2. Or append `/swagger-ui/index.html` to your Stirling PDF URL +1. Navigate to `http://your-instance:port/swagger-ui.html` +2. Or append `/swagger-ui.html` to your Stirling PDF URL 3. This provides an interactive documentation interface where you can: - View all available endpoints - Test API calls directly @@ -106,4 +106,4 @@ Stirling PDF also has statistic and health endpoints to integrate with monitorin > "C:\Users\systo\Downloads\output.pdf" ``` - \ No newline at end of file + diff --git a/docs/Configuration/Configuration.md b/docs/Configuration/Configuration.md index aeb94f11..3312123d 100644 --- a/docs/Configuration/Configuration.md +++ b/docs/Configuration/Configuration.md @@ -231,6 +231,28 @@ For advanced features and specific use cases, see these detailed guides: --- +### Performance & Scaling + +**[Performance Optimization & Sizing](./Performance-Optimization.md)** +- Resource sizing, JVM tuning, memory model, and scaling guidance + +**[Process Limits](./Process-Limits.md)** +- Session limits and timeouts for external tools + +**[LibreOffice Parallel Processing](./LibreOffice-Parallel-Processing.md)** +- Configure multiple LibreOffice instances for faster document conversion +- Local UNO server pool and remote UNO server endpoints + +--- + +### Diagnostics & Support + +**[Diagnostics & Reporting Issues](./Diagnostics.md)** +- Built-in diagnostics tool for Docker containers +- How to report issues via GitHub, Discord, and email + +--- + ### Other Configuration **[Folder Scanning](./FolderScanning.md)** @@ -303,3 +325,4 @@ If missing: - **Production Deployment:** See [Production Deployment Guide](../Server-Admin-Onboarding.md) - **API Usage:** See [API Documentation](../API.md) - **Tool Reference:** See [Functionality](../Functionality/Functionality.md) +- **Troubleshooting:** See [Diagnostics & Reporting Issues](./Diagnostics.md) diff --git a/docs/Configuration/Diagnostics.md b/docs/Configuration/Diagnostics.md new file mode 100644 index 00000000..03c5d7ef --- /dev/null +++ b/docs/Configuration/Diagnostics.md @@ -0,0 +1,173 @@ +--- +sidebar_position: 21 +id: Diagnostics +title: Diagnostics & Reporting Issues +description: Use the built-in diagnostics tool and learn how to report issues effectively +tags: + - Diagnostics + - Troubleshooting + - Support +--- + +# Diagnostics & Reporting Issues + +Stirling PDF includes a built-in diagnostics tool inside Docker containers that collects logs, configuration, system information, and application metrics into a single archive. This is the fastest way to gather the information needed when troubleshooting or reporting issues. + +--- + +## Running the Diagnostics Tool + +Open an interactive shell inside the running container and invoke the tool: + +```bash +docker exec -it diag +``` + +The following aliases all work identically: `diag`, `debug`, `diagnostic`, `diagnostics`, `stirling-diagnostics`. + +:::caution Interactive Terminal Required +The diagnostics tool requires an interactive terminal (`-it` flag). It will not run in non-interactive or headless sessions. +::: + +--- + +## Collection Modes + +When you run the tool, you'll be prompted to choose a collection mode. + +### Auto Mode (Recommended) + +Select option **1** when prompted. Auto mode collects: + +- Application logs from the last 24 hours +- Configuration files from `/configs` +- System information (OS, CPU, memory, disk, Java version) +- Application metrics and health endpoints + +This is sufficient for most issue reports. + +### Custom Mode + +Select option **2** for granular control over what gets collected: + +| Prompt | Default | What It Collects | +|---|---|---| +| Output directory | `/configs` | Where to save the archive | +| Days of logs | 1 | How many days of logs to include | +| Include /configs | Yes | Configuration files | +| Include /customFiles | No | Custom files (excluding PDFs and images) | +| Include /pipeline | No | Pipeline working files (excluding PDFs) | +| Include /tmp/stirling-pdf | No | Temporary processing files | +| Include system information | Yes | OS, CPU, RAM, disk, Java/Python versions | +| Include environment variables | No | Full environment dump | +| Fetch metrics endpoints | Yes | Application status, health, and load data | +| Include UI data endpoints | No | Sign, pipeline, and OCR endpoint data | +| Redact sensitive information | Yes | Apply redaction filters (see below) | + +### Redaction Options + +When redaction is enabled, you can selectively mask: + +- **Secrets/tokens/passwords** - Redacts Authorization headers, API keys, passwords, and similar credentials +- **URL hosts/domains** - Masks hostnames in URLs +- **Email addresses** - Replaces email addresses with `[REDACTED_EMAIL]` +- **Host/Domain/Server fields** - Masks values in host-related configuration fields + +:::caution +Always enable redaction if you plan to share the diagnostics bundle publicly (for example, in a GitHub issue). However, redaction is not perfect and may miss some sensitive values - always review the output manually before sharing publicly. You can disable redaction for private support channels if full detail is needed. +::: + +--- + +## What Gets Collected + +The diagnostics bundle is a `.tar.gz` archive saved to the output directory (default: `/configs`). It contains: + +``` +stirling-diagnostics-YYYYMMDD-HHMMSS.tar.gz +├── summary.txt # Collection metadata and settings +├── bundle/ +│ ├── logs/ # Application log files +│ ├── configs/ # Configuration files (settings.yml, etc.) +│ ├── system/ # System information +│ │ ├── uname.txt # Kernel version +│ │ ├── os-release # OS distribution info +│ │ ├── meminfo.txt # Memory details +│ │ ├── cpuinfo.txt # CPU details +│ │ ├── df.txt # Disk usage +│ │ ├── free.txt # Memory summary +│ │ ├── ps.txt # Running processes +│ │ ├── java-version.txt # Java runtime version +│ │ └── python-version.txt # Python version +│ ├── metrics/ # Application metrics +│ │ ├── api/v1/info/status.json +│ │ ├── api/v1/info/uptime.json +│ │ ├── api/v1/info/health.json +│ │ ├── api/v1/info/requests.json +│ │ ├── api/v1/info/load.json +│ │ ├── actuator/health.json +│ │ └── actuator/prometheus.txt +│ ├── env/ # Environment variables (if requested) +│ └── tree/ # Directory listings +│ ├── logs.txt +│ ├── configs.txt +│ ├── customFiles.txt +│ ├── pipeline.txt +│ ├── tessdata.txt # Installed OCR language packs +│ └── tessdata-mount.txt +``` + +PDFs, images, and compressed archives are always excluded from collection. + +### Retrieving the Bundle + +After the tool finishes, copy the archive out of the container: + +```bash +docker cp :/configs/stirling-diagnostics-*.tar.gz ./ +``` + +--- + +## AOT Diagnostics + +If you are running with AOT (Ahead-of-Time) compilation enabled (`STIRLING_AOT_ENABLE=true`), an additional diagnostics tool is available: + +```bash +docker exec -it aot-diag +``` + +This tool diagnoses AOT cache generation failures, particularly on ARM64/aarch64 platforms. It checks cache integrity, JVM compatibility, and can run smoke tests. + +Aliases: `aot-diag`, `aot-diagnostics` + +--- + +## How to Report Issues + +When you encounter a problem with Stirling PDF, choose the right channel depending on the nature of your issue. + +### GitHub Issues - Bug Reports & Feature Requests + +For reproducible bugs and feature requests, open an issue at: +**https://github.com/Stirling-Tools/Stirling-PDF/issues** + +The repository includes issue templates for bug reports and feature requests that will guide you through providing the right information. + +When submitting a bug report, include as much detail as possible: the diagnostics bundle (run `diag` in your container first), steps to reproduce the issue, expected vs. actual behavior, your deployment method (Docker, bare metal, Kubernetes), Stirling PDF version (visible in the UI footer or in `summary.txt` from the diagnostics bundle), and any commands, API requests, or actions you were performing when the issue occurred. The more context you provide, the faster it can be resolved. + +### Discord Community - Questions & Discussion + +For quick questions, troubleshooting help, and community discussion: +**https://discord.gg/HYmhKj45pU** + +Discord is the best place for configuration help, setup questions, sharing workarounds with other users, general discussion about features and usage, and getting faster informal feedback before filing a formal issue. It's also great for following up on GitHub issues and having deeper conversations with the community. + +### Email Support + +For enterprise customers and licensing inquiries: +**support@stirlingpdf.com** + +For security vulnerabilities: +**security@stirlingpdf.com** or use the [GitHub Security Advisory](https://github.com/Stirling-Tools/Stirling-PDF/security) process. + diff --git a/docs/Configuration/LibreOffice-Parallel-Processing.md b/docs/Configuration/LibreOffice-Parallel-Processing.md new file mode 100644 index 00000000..653e282a --- /dev/null +++ b/docs/Configuration/LibreOffice-Parallel-Processing.md @@ -0,0 +1,191 @@ +--- +sidebar_position: 22 +id: LibreOffice-Parallel-Processing +title: LibreOffice Parallel Processing +description: Configure multiple LibreOffice instances for parallel document conversion +tags: + - LibreOffice + - Performance + - Scaling + - UNO Server +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 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. + + + + ```yaml + processExecutor: + autoUnoServer: true + sessionLimit: + libreOfficeSessionLimit: 4 # Run 4 LibreOffice instances + ``` + + + ```bash + PROCESS_EXECUTOR_SESSION_LIMIT_LIBRE_OFFICE_SESSION_LIMIT=4 + ``` + + + ```yaml + services: + stirling-pdf: + image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest + environment: + PROCESS_EXECUTOR_SESSION_LIMIT_LIBRE_OFFICE_SESSION_LIMIT: 4 + ``` + + + +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: + + + + ```yaml + 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" + ``` + + + ```bash + PROCESS_EXECUTOR_AUTO_UNO_SERVER=false + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_HOST=unoserver1 + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_PORT=2003 + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_HOST_LOCATION=remote + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_PROTOCOL=http + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_HOST=unoserver2 + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_PORT=2003 + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_HOST_LOCATION=remote + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_PROTOCOL=http + ``` + + + ```yaml + services: + stirling-pdf: + image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest + environment: + PROCESS_EXECUTOR_AUTO_UNO_SERVER: "false" + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_HOST: "unoserver1" + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_PORT: "2003" + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_HOST_LOCATION: "remote" + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_HOST: "unoserver2" + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_PORT: "2003" + PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_HOST_LOCATION: "remote" + ports: + - "8080:8080" + + unoserver1: + image: docker.stirlingpdf.com/stirlingtools/stirling-pdf-unoserver:latest + ports: + - "2003:2003" + + unoserver2: + image: docker.stirlingpdf.com/stirlingtools/stirling-pdf-unoserver:latest + ports: + - "2004:2003" + ``` + + + +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: + +| Value | When to Use | How It Works | +|---|---|---| +| `auto` | Default, detects automatically | Checks if the host is local or remote | +| `local` | UNO server is on the same machine | Files are passed via filesystem paths (fastest) | +| `remote` | UNO server is a separate container or machine | Files 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: + +```bash +# 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: + + + + ```yaml + processExecutor: + timeoutMinutes: + libreOfficetimeoutMinutes: 60 + ``` + + + ```bash + PROCESS_EXECUTOR_TIMEOUT_MINUTES_LIBRE_OFFICETIMEOUT_MINUTES=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. + +--- + +## Related + +- [Process Limits](./Process-Limits.md) — Configure session limits and timeouts for all external tools +- [Production Deployment Guide](../Server-Admin-Onboarding.md) — Sizing recommendations for different workloads +- [Diagnostics](./Diagnostics.md) — Collect system and application diagnostics for troubleshooting diff --git a/docs/Configuration/Performance-Optimization.md b/docs/Configuration/Performance-Optimization.md new file mode 100644 index 00000000..d3f5c473 --- /dev/null +++ b/docs/Configuration/Performance-Optimization.md @@ -0,0 +1,163 @@ +--- +sidebar_position: 24 +id: Performance-Optimization +title: Performance Optimization & Sizing +description: Resource sizing and scaling guidance for Stirling PDF deployments +tags: + - Performance + - Sizing + - Scaling +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Performance Optimization & Sizing + +PDF processing is memory-intensive - a single large PDF can expand to many times its file size in memory during processing. This guide helps you size your deployment correctly. + +--- + +## How Stirling PDF Uses Memory + +Stirling PDF loads PDFs into memory using a tiered strategy based on file size: + +| File Size | Strategy | Memory Impact | +|---|---|---| +| Up to 10 MB | Loaded entirely into memory | Fast, but consumes memory proportional to file size | +| 10 MB to 50 MB | Partially in memory, remainder stored on disk | Moderate memory usage with disk spillover | +| Over 50 MB | Fully stored on disk during processing | Minimal memory usage, but requires adequate disk space | + +The application also monitors memory pressure. If available memory drops too low, all operations are forced into disk-backed mode regardless of file size. + +:::caution Memory-Intensive Operations +A 50 MB PDF with complex vector graphics, embedded fonts, and many pages can expand to 200-500 MB in memory during processing. Operations that render pages (such as PDF-to-image conversion) and OCR are particularly memory-intensive. Plan for several times the maximum expected file size per concurrent operation. +::: + +--- + +## Resource Recommendations + + + + +**Recommended specifications:** +- **CPU:** 2 cores (4+ recommended) +- **RAM:** 4 GB +- **Disk:** 10 GB free space + +**Docker Compose:** +```yaml +services: + stirling-pdf: + image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest + deploy: + resources: + limits: + memory: 4G + cpus: '2.0' +``` + + + + +**Recommended specifications:** +- **CPU:** 4-8 cores +- **RAM:** 8-16 GB +- **Disk:** 50 GB (SSD recommended) + +**Docker Compose:** +```yaml +services: + stirling-pdf: + image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest + environment: + PROCESS_EXECUTOR_SESSION_LIMIT_LIBRE_OFFICE_SESSION_LIMIT: 2 + deploy: + resources: + limits: + memory: 8G + cpus: '4.0' +``` + +**Consider:** +- Increase LibreOffice session limit for faster document conversions - see [LibreOffice Parallel Processing](./LibreOffice-Parallel-Processing.md) +- External PostgreSQL database for reliability + + + + +**Recommended specifications:** +- **CPU:** 8+ cores +- **RAM:** 16-32 GB +- **Disk:** 100+ GB, SSD strongly recommended + +**Docker Compose:** +```yaml +services: + stirling-pdf: + image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest + environment: + PROCESS_EXECUTOR_SESSION_LIMIT_LIBRE_OFFICE_SESSION_LIMIT: 4 + PROCESS_EXECUTOR_SESSION_LIMIT_TESSERACT_SESSION_LIMIT: 2 + deploy: + resources: + limits: + memory: 16G + cpus: '8.0' +``` + +**Architecture considerations:** +- Multiple instances behind a load balancer with session affinity +- Remote UNO servers for LibreOffice scaling - see [LibreOffice Parallel Processing](./LibreOffice-Parallel-Processing.md) +- External PostgreSQL database (enterprise feature) +- Shared `/configs` volume across instances for consistent settings + +:::tip Server/Enterprise Recommended +For large organizations, **Server or Enterprise plans** provide SSO, external database support, advanced monitoring, and dedicated support. + +[Learn more](../Server-Admin-Onboarding.md#step-10-paid-plans-serverenterprise) +::: + + + + +--- + +## Fine Tuning + +For most deployments, Stirling PDF's defaults work well and no manual tuning is needed. If you are experiencing performance issues with large files or high concurrency, you can adjust the memory allocated to the application using the `JAVA_TOOL_OPTIONS` environment variable: + +```yaml +services: + stirling-pdf: + environment: + JAVA_TOOL_OPTIONS: "-Xms512m -Xmx4g" +``` + +`-Xms` sets the initial memory allocation and `-Xmx` sets the maximum. If running in Docker or Kubernetes with memory limits, set the container limit to **at least 1.5x the `-Xmx` value** to leave room for background processes like LibreOffice and Tesseract. + +--- + +## Resource-Intensive Operations + +Some operations require significantly more resources than others. If your organization primarily uses specific tools, you should size your deployment based on the most resource-heavy operations your users will perform. + +| Operation | CPU Impact | Memory Impact | Notes | +|---|---|---|---| +| Merge / Split | Low | Proportional to total file sizes | Lightweight file operations | +| OCR (Tesseract) | Very High | High | CPU-bound image analysis | +| File Conversion (LibreOffice) | High | High | Single-threaded per instance | +| PDF-to-Image | Moderate | Very High | Page rendering expands memory significantly | +| PDF/A Conversion | Moderate | High | Font embedding and color profiles | +| Compression | Moderate | High | Rewriting internal PDF structures | + +For example, if your team primarily uses OCR and document conversion, you will need significantly more resources than a team that mainly merges and splits PDFs. Adjust your [Process Limits](./Process-Limits.md) and resource allocation accordingly. + +--- + +## Related + +- [Process Limits](./Process-Limits.md) - Configure session limits and timeouts for all external tools +- [LibreOffice Parallel Processing](./LibreOffice-Parallel-Processing.md) - Scale document conversions with multiple instances +- [Production Deployment Guide](../Server-Admin-Onboarding.md) - Full production setup walkthrough +- [Diagnostics](./Diagnostics.md) - Collect system and application diagnostics for troubleshooting diff --git a/docs/Configuration/Process-Limits.md b/docs/Configuration/Process-Limits.md index 066ea1be..911be42b 100644 --- a/docs/Configuration/Process-Limits.md +++ b/docs/Configuration/Process-Limits.md @@ -41,6 +41,8 @@ Controls how many concurrent instances of each process are allowed. Extra reques **Increase** limits on a beefy server with concurrent users. **Decrease** them on low-RAM servers - LibreOffice in particular is memory-hungry. +For LibreOffice specifically, you can also scale by running multiple remote UNO server instances — see [LibreOffice Parallel Processing](./LibreOffice-Parallel-Processing.md) for details. + :::info Be mindful of memory and CPU usage when raising session limits. Each concurrent process consumes resources, and setting limits too high can starve the host or cause out-of-memory issues possibly killing the instance. Start with the defaults and increase gradually while monitoring your server. ::: diff --git a/docs/FAQ.md b/docs/FAQ.md index 0633c4f3..eebff0e8 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -21,14 +21,16 @@ All feedback and suggestions are appreciated. It is best to submit these via a G You can also reach out in discord but without a ticket to track it the request can often get lost! ### Q5: I found a bug in Stirling PDF. Where can I report it? -Please report any bugs or issues you encounter through our GitHub Issues page. Be sure to include as much detail as possible so we can diagnose and resolve the issue quickly. +Please report any bugs or issues you encounter through our [GitHub Issues page](https://github.com/Stirling-Tools/Stirling-PDF/issues). Be sure to include as much detail as possible so we can diagnose and resolve the issue quickly. If you're running Docker, use the built-in [diagnostics tool](./Configuration/Diagnostics.md) to collect logs, configuration, and system information into a shareable archive. -### Q6: My Stirling PDF Using high RAM at idle, How can I optimize memory usage? +### Q6: My Stirling PDF is using high RAM at idle. How can I optimize memory usage? Stirling PDF's memory usage can be optimized in several ways: -Disable additional features: Set DISABLE_ADDITIONAL_FEATURES=true to reduce RAM consumption. This can significantly lower memory usage, especially during idle periods. +- **Use the Ultra Lite version:** Pull the `latest-ultra-lite` tag from Docker Hub or GitHub, which is specifically designed for lower-end hardware. +- **Tune memory allocation:** See the [Fine Tuning](./Configuration/Performance-Optimization.md#fine-tuning) section of the Performance Optimization guide for how to adjust memory limits. +- **Reduce LibreOffice instances:** Each idle LibreOffice UNO server instance uses approximately 50 MB. The default session limit is 1. See [LibreOffice Parallel Processing](./Configuration/LibreOffice-Parallel-Processing.md) for details. -Use the Ultra Lite version: Pull the latest-ultra-lite tag from Docker Hub or GitHub, which is specifically designed for lower-end hardware. +For detailed sizing recommendations, see the [Performance Optimization](./Configuration/Performance-Optimization.md) guide. ### Q7: I'm experiencing connection errors when pulling from docker.stirling.com diff --git a/docs/Server-Admin-Onboarding.md b/docs/Server-Admin-Onboarding.md index 7c40d816..f986c22c 100644 --- a/docs/Server-Admin-Onboarding.md +++ b/docs/Server-Admin-Onboarding.md @@ -1319,156 +1319,7 @@ find backups/ -name "stirling-data-*.tar.gz" -mtime +30 -delete ## Step 9: Performance Optimization -Optimize Stirling-PDF for your workload and server capacity. - -### 9.1: Resource Allocation - - - - -**Recommended specifications:** -- **CPU:** 2 cores -- **RAM:** 4GB -- **Disk:** 20GB -- **Concurrent operations:** 2-4 - -**Docker resource limits:** -```yaml -deploy: - resources: - limits: - memory: 4G - cpus: '2.0' - reservations: - memory: 2G - cpus: '1.0' -``` - -**Settings:** -```yaml -system: - maxFileSize: 500 # 500MB max file - connectionTimeoutMinutes: 5 - maxConcurrentOperations: 2 -``` - - - - -**Recommended specifications:** -- **CPU:** 4 cores -- **RAM:** 8GB -- **Disk:** 50GB -- **Concurrent operations:** 4-8 - -**Docker resource limits:** -```yaml -deploy: - resources: - limits: - memory: 8G - cpus: '4.0' - reservations: - memory: 4G - cpus: '2.0' -``` - -**Settings:** -```yaml -system: - maxFileSize: 1000 # 1GB max file - connectionTimeoutMinutes: 10 - maxConcurrentOperations: 4 -``` - -**Consider:** -- Load balancer for multiple instances -- Database on separate server - - - - -**Recommended specifications:** -- **CPU:** 8+ cores -- **RAM:** 16GB+ -- **Disk:** 100GB+ (SSD recommended) -- **Concurrent operations:** 8+ - -**Docker resource limits:** -```yaml -deploy: - resources: - limits: - memory: 16G - cpus: '8.0' - reservations: - memory: 8G - cpus: '4.0' -``` - -**Settings:** -```yaml -system: - maxFileSize: 2000 # 2GB max file - connectionTimeoutMinutes: 15 - maxConcurrentOperations: 8 -``` - -**Architecture:** -- Multiple instances for processing -- Load balancer with session affinity -- Dedicated database server -- Redis for session storage - -:::tip Server/Enterprise Recommended -For large organizations, **Server or Enterprise plans** provide: -- Advanced load balancing -- High availability configuration -- Database clustering -- Performance monitoring -- Dedicated support - -[Learn more](#step-10-paid-plans-serverenterprise) -::: - - - - -### 9.2: Storage Management - -**Monitor disk usage:** -```bash -# Check Docker disk usage -docker system df - -# Check Stirling-PDF data usage -du -sh ./stirling-data/* -``` - -**Cleanup strategies:** - -```yaml -system: - # Automatic cleanup settings - tempFileCleanup: true - tempFileMaxAge: 24 # hours - - # Log rotation - logRetentionDays: 30 - maxLogSize: 100 # MB -``` - -**Manual cleanup:** -```bash -# Clean Docker system -docker system prune -a --volumes - -# Clean old logs -find ./stirling-data/logs -name "*.log" -mtime +30 -delete - -# Clean temporary files (if not auto-cleaned) -find ./stirling-data/temp -type f -mtime +1 -delete -``` +For resource sizing recommendations, scaling guidance, and fine tuning, see the dedicated [Performance Optimization & Sizing](./Configuration/Performance-Optimization.md) guide. --- @@ -1517,6 +1368,7 @@ Congratulations! You've successfully deployed and configured Stirling-PDF for yo - [OCR Configuration](./Configuration/OCR.md) - Add more languages - [Pipeline Automation](./Configuration/Pipeline.md) - Automate workflows - [API Integration](./API.md) - Integrate with other systems + - [LibreOffice Parallel Processing](./Configuration/LibreOffice-Parallel-Processing.md) - Scale document conversions 3. **🔒 Harden security** - [Fail2Ban Setup](./Configuration/Fail2Ban.md) - Prevent brute force @@ -1565,9 +1417,10 @@ Congratulations! You've successfully deployed and configured Stirling-PDF for yo **Solutions:** 1. Check resource limits: `docker stats stirling-pdf` -2. Increase memory: Update `deploy.resources.limits.memory` -3. Reduce concurrent operations: Lower `maxConcurrentOperations` -4. Check disk I/O: Use SSD for better performance +2. Increase JVM heap - see [Performance Optimization](./Configuration/Performance-Optimization.md) +3. Increase LibreOffice instances if document conversions are slow - see [LibreOffice Parallel Processing](./Configuration/LibreOffice-Parallel-Processing.md) +4. Check disk I/O: Use SSD for temp file storage +5. Run the built-in [diagnostics tool](./Configuration/Diagnostics.md) and check application logs ### HTTPS/Certificate Issues @@ -1591,13 +1444,15 @@ Congratulations! You've successfully deployed and configured Stirling-PDF for yo ### Need More Help? +Run the built-in [diagnostics tool](./Configuration/Diagnostics.md) inside your Docker container to collect logs, configuration, and system information into a shareable archive. + **For Community Support:** -- Join Discord: https://discord.gg/Cn8pWhQRxZ +- Join Discord: https://discord.gg/HYmhKj45pU - Search GitHub Issues: https://github.com/Stirling-Tools/Stirling-PDF/issues **For Priority Support:** - Upgrade to Server or Enterprise plan -- Email: support@stirlingtools.com +- Email: support@stirlingpdf.com - Get dedicated support team ---