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.

Источник