Why Your Self-Hosted Stirling-PDF Container OOMs, Hangs or Returns a Broken PDF: 15 Anti-Patterns and Their Fixes

说明与用途

不正确的内存限制、镜像版本、OCR 语言包和临时文件处理导致 Stirling-PDF 崩溃。设置内存限制、JVM 堆、正确的镜像、挂载语言数据、管理临时文件并延长代理超时可解决问题。

问题

Self-hosted Stirling-PDF containers frequently crash, hang, or produce corrupted PDFs due to misconfigurations such as missing memory limits, incorrect image variants, inadequate OCR language packs, and improper temporary file handling.

结果

Properly configuring memory limits, JVM heap, image variants, OCR language packs, temporary file storage, and proxy timeouts eliminates OOM crashes, hangs, and corrupted PDFs, enabling reliable self-hosted Stirling-PDF deployments.

工作流

• 1. Inspect container exit codes and logs to identify failure type.
• 2. Set a memory limit (e.g., 2–4 GB) and configure JVM heap with JAVA_TOOL_OPTIONS=-XX:MaxRAMPercentage=50.
• 3. Choose the correct image variant (latest, ultra-lite, or fat) based on required features.
• 4. Mount a volume at /usr/share/tessdata with needed language data for OCR.
• 5. Mount /tmp/stirling-pdf to a tmpfs or bind mount a directory to avoid overlay layer issues.
• 6. Configure temp file cleanup in /configs/settings.yml.
• 7. Adjust reverse proxy timeouts to exceed longest expected job duration.
• 8. Monitor docker stats during large jobs to verify resource usage.

证据

Docker applies no memory limit by default. A container-aware JVM with no -Xmx claims a maximum heap of 25 percent of the memory it can see, which is the host's total RAM when you set no limit.

来源

The UI still shows every button either way, which is why this fails so confusingly.

来源