Stirling PDF на Ubuntu 24.04: пошаговая установка

MAATRIX

Онлайн-конвертеры PDF просят загрузить документ на чужой сервер — а если это договор, паспорт или бухгалтерская отчётность, отдавать их куда-то на сторону не хочется. Stirling PDF решает это одной командой docker compose up: вы получаете свой собственный веб-инструмент для слияния, разбивки, OCR, конвертации и десятков других операций с PDF, который работает только на вашем сервере. Ниже — пошаговая установка на чистый Ubuntu 24.04, от подготовки системы до HTTPS и логина.

Что нужно для сервера

Stirling PDF — это Java-приложение (Spring Boot) в Docker-контейнере, который в полной сборке тянет за собой LibreOffice, Tesseract OCR, Qpdf, Ghostscript и Python-обвязку для конвертации. Это заметно тяжелее, чем условный Uptime Kuma, поэтому не берите минимальный тариф:

• CPU: 2 vCPU — конвертация офисных форматов в PDF через LibreOffice и OCR по многостраничным сканам заметно грузят процессор.
• RAM: от 2 ГБ для лёгких сценариев (слияние, разбивка, разворот страниц), от 4 ГБ — если планируете активно гонять OCR и конвертацию DOCX/XLSX в PDF на больших файлах. Полная сборка образа сама по себе съедает 400-600 МБ до первого запроса.
• Диск: от 20 ГБ — под сам образ (полная сборка весит 1-1.5 ГБ), временные файлы конвертации и, если включите, историю обработанных документов.
• ОС: Ubuntu 24.04 LTS, чистая установка.

Дальше всё — через Docker, поэтому системных зависимостей, кроме самого Docker, не нужно.

Обновите систему перед началом:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl ca-certificates

Если Docker ещё не установлен — сделайте это по отдельной инструкции: Docker на Ubuntu 24.04 с нуля. Дальше предполагаю, что docker и docker compose (плагин, не отдельный docker-compose) у вас уже работают — проверить можно командой docker compose version.

Готовим каталоги и compose-файл

Создайте рабочую директорию и подкаталоги для томов — Stirling PDF монтирует несколько volume для конфигов, языковых пакетов OCR, кастомных файлов и логов:

sudo mkdir -p /opt/stirling-pdf/{trainingData,extraConfigs,customFiles,logs,pipeline}
cd /opt/stirling-pdf

Создайте docker-compose.yml:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./trainingData:/usr/share/tessdata
      - ./extraConfigs:/configs
      - ./customFiles:/customFiles/
      - ./logs:/logs/
      - ./pipeline:/pipeline/
    environment:
      - DOCKER_ENABLE_SECURITY=true
      - SECURITY_ENABLELOGIN=true
      - LANGS=en_GB,ru_RU
      - UI_APPNAME=Stirling PDF
      - SYSTEM_DEFAULTLOCALE=ru_RU
    ulimits:
      nofile:
        soft: 65536
        hard: 65536

Пара важных моментов:

• Порт 8080 сознательно опубликован только на 127.0.0.1 — снаружи он недоступен, наружу приложение отдаст обратный прокси с HTTPS (настроим ниже). Публиковать 8080 на всех интерфейсах без прокси и логина — плохая идея: PDF-инструмент, который принимает файлы, не должен смотреть в интернет без аутентификации.
• Тег latest у Stirling PDF тянет полную сборку со всеми конвертерами и OCR. У проекта также есть более лёгкие варианты сборки (без LibreOffice/Weasyprint) — если вам не нужна конвертация офисных форматов, посмотрите актуальный список тегов на Docker Hub на момент установки: набор тегов и их состав у проекта время от времени меняется.
• Точный список переменных окружения тоже стоит сверить с README текущей версии образа перед продакшен-запуском — проект активно развивается, и часть флагов (особенно вокруг безопасности и SSO) могла измениться.

Запускаем:

docker compose up -d
docker compose logs -f stirling-pdf

Дождитесь в логах строки о старте Spring Boot (обычно занимает 15-40 секунд на первом запуске — приложению нужно инициализировать конфиги). После этого проверьте локально:

curl -I http://127.0.0.1:8080

Ответ 200 OK или редирект на страницу логина означает, что контейнер поднялся штатно.

OCR и языковые пакеты

Одна из главных причин ставить Stirling PDF на свой сервер — распознавание текста в сканах (OCR) без отправки документов в облако. Полная сборка образа уже включает Tesseract, но пакет русского языка нужно докачать явно через переменную LANGS, как в примере выше (ru_RU).

При первом старте с новым значением LANGS контейнер скачивает языковые данные во время инициализации — это может занять минуту-другую в зависимости от канала. Проверить, что пакет встал, можно так:

docker exec stirling-pdf ls /usr/share/tessdata/

В списке должны появиться файлы вида rus.traineddata и eng.traineddata. Если файла нет — проверьте написание кода языка в LANGS и логи контейнера на ошибки сети (докачка идёт из интернета, так что если у сервера строгий исходящий firewall — откройте нужные направления или скачайте .traineddata вручную и положите в примонтированный ./trainingData).

Качество распознавания на сканах с плохим контрастом или рукописным текстом остаётся ограниченным — это особенность Tesseract, а не конкретной сборки, и никакая настройка контейнера этого не изменит. Для чистых типографских сканов результат обычно вполне рабочий.

Закрываем доступ: логин, firewall, HTTPS

Три уровня защиты, и все три стоит включить, а не выбирать один из.

1. Встроенный логин. Переменные DOCKER_ENABLE_SECURITY=true и SECURITY_ENABLELOGIN=true в compose-файле выше включают экран входа. При первом запуске Stirling PDF создаёт учётку администратора — данные для входа по умолчанию и процедура их смены на актуальную версию образа лучше сверить в логах первого старта (docker compose logs stirling-pdf | grep -i admin) и в README, так как поведение по умолчанию менялось между релизами проекта. Первым делом после входа смените пароль администратора и, если инструмент будет доступен нескольким сотрудникам, заведите отдельные учётки вместо общего пароля.

2. Firewall на уровне сервера. Порт 8080 уже не торчит наружу (мы завязали его на 127.0.0.1), но стоит явно закрыть всё лишнее и на уровне ufw:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

3. HTTPS через обратный прокси. Отдавать инструмент для работы с чужими документами по голому HTTP — плохая практика: логин и файлы будут идти в открытом виде. Проще всего поднять Caddy, который сам получит и продлит сертификат Let's Encrypt — разберитесь по отдельной статье: Caddy с авто-SSL на Ubuntu 24.04. Конфиг для Stirling PDF минимальный — Caddyfile:

pdf.вашдомен.ru {
    reverse_proxy 127.0.0.1:8080
}

После sudo systemctl reload caddy (или перезапуска контейнера Caddy, если он тоже в Docker) сертификат выпустится автоматически и инструмент станет доступен по https://pdf.вашдомен.ru с логином на входе.

Если Stirling PDF будет использовать несколько человек и вы хотите единую точку входа с MFA поверх встроенного логина — вынесите его за Authelia, она встраивается в тот же Caddy как forward_auth. Для одного-двух пользователей это обычно избыточно — встроенного логина хватает.

Проверка: слияние, разбивка, OCR, конвертация

После входа откроется главная страница с плитками инструментов — их у Stirling PDF около полусотни, сгруппированных по категориям. Стоит прогнать несколько базовых сценариев, чтобы убедиться, что тяжёлые операции (LibreOffice, OCR) действительно работают, а не просто отдают ошибку 500 из-за нехватки памяти:

• Merge / Split — загрузите пару тестовых PDF, объедините, затем разбейте обратно по страницам. Это самые лёгкие операции, работают без LibreOffice и OCR — если и они падают, проблема на уровне самого контейнера или томов, смотрите docker compose logs.
• OCR / Add OCR Layer — прогоните скан или PDF без текстового слоя с выбранным языком rus. Если процесс подвисает надолго или падает по таймауту — вероятно, серверу не хватает RAM на конкретный размер файла; проверьте docker stats stirling-pdf во время обработки.
• Convert to PDF (DOCX/XLSX → PDF) — этот путь идёт через LibreOffice внутри контейнера, самый ресурсоёмкий. Если конвертация падает с ошибкой о LibreOffice — убедитесь, что используете полную сборку образа (stirlingtools/stirling-pdf:latest), а не облегчённую без офисных конвертеров.
• Watermark / Split by size — быстрые проверки, что запись файлов через смонтированные тома (customFiles, pipeline) работает без ошибок прав доступа.

Если что-то падает именно на записи файлов — почти всегда дело в правах на хостовые каталоги: контейнер пишет от своего внутреннего пользователя, и на некоторых версиях образа стоит выставить владельца каталогов явно:

sudo chown -R 1000:1000 /opt/stirling-pdf/{customFiles,logs,pipeline,extraConfigs}
docker compose restart stirling-pdf

Обновление и обслуживание

Полная сборка Stirling PDF обновляется довольно активно — новые операции, фиксы OCR, изменения в UI. Обновление сводится к стандартному циклу:

cd /opt/stirling-pdf
docker compose pull
docker compose up -d

Перед обновлением на проде стоит глянуть changelog релиза — у проекта иногда меняются переменные окружения и структура томов между мажорными версиями, и бездумный pull в самый неподходящий момент может сломать OCR-языки или логин. Если хочется автоматизировать этот процесс без ручного контроля — можно повесить Watchtower, но для инструмента, через который проходят чужие документы, ручное обновление с чтением changelog надёжнее.

Резервного копирования как такового у Stirling PDF немного: если не хранить историю обработки файлов внутри приложения (по умолчанию файлы обрабатываются и не остаются на диске после ответа), бэкапить нужно в основном docker-compose.yml и содержимое extraConfigs — это не гигабайты, ежедневный tar каталога /opt/stirling-pdf в cron полностью закрывает вопрос.

Частые вопросы