Как установить и настроить Stirling PDF на VPS

MAATRIX

Онлайн-конвертеры PDF удобны ровно до момента, когда через них проходит договор с персональными данными или скан паспорта. Каждый такой сервис — это чужой сервер, на который вы отправляете документ и надеетесь, что его не сохранят и не проанализируют. Stirling PDF решает эту проблему буквально: вы поднимаете тот же набор инструментов — слияние, разбивку, OCR, конвертацию, сжатие, водяные знаки — на собственном VPS, и файлы никогда не покидают вашу инфраструктуру.

Что такое Stirling PDF и зачем он на своём сервере

Stirling PDF — открытый веб-инструмент для локальной работы с PDF, который развивался из личного pet-проекта в довольно зрелый продукт с полусотней операций: объединение и разделение документов, добавление и удаление паролей, водяные знаки, конвертация в Word/Excel/изображения и обратно, распознавание текста через встроенный OCR (Tesseract), сжатие, поворот страниц, извлечение изображений, сравнение документов. По сути — замена сразу нескольких платных десктопных программ и десятка сомнительных онлайн-сервисов одним self-hosted приложением с приятным веб-интерфейсом.

Смысл ставить его на свой VPS, а не пользоваться публичным demo-инстансом (он тоже существует) — три вещи. Во-первых, конфиденциальность: документы обрабатываются только на вашем сервере, ничего не логируется на стороне третьих лиц. Во-вторых, отсутствие лимитов — публичные сервисы режут размер файла и число операций в сутки, свой инстанс ограничен только ресурсами сервера. В-третьих, интеграция: Stirling PDF отдаёт REST API, так что его легко подключить к внутренним скриптам и автоматизации документооборота.

Для стабильной работы с OCR и конвертацией в форматы Office хватает 2 CPU и 4 ГБ RAM — этого достаточно для команды из нескольких человек. Если планируете гонять OCR на многостраничных сканах пачками, разумно взять 4 ГБ и больше, потому что Tesseract и LibreOffice (используется под капотом для конвертации в docx/xlsx) любят память при параллельной обработке.

Подготовка сервера и установка Docker

Разворачивать будем через Docker Compose — это официальный и самый предсказуемый способ запуска Stirling PDF, он же используется в большинстве production-сценариев проекта. Если на сервере ещё нет Docker, сначала поставьте его — сам процесс на Ubuntu 24.04 подробно разобран в статье про установку Docker с нуля, здесь коротко:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker --version
docker compose version

Создайте рабочую директорию и структуру для данных приложения:

mkdir -p /opt/stirling-pdf/{data,config,logs,customFiles,pipeline/watchedFolders,pipeline/finishedFolders}
cd /opt/stirling-pdf

Такое разделение важно: Stirling PDF хранит в data базу данных пользователей и настройки, в config — файл конфигурации приложения, а pipeline использует, если вы настроите автоматическую обработку файлов из папки (watched folder).

Docker Compose: базовый конфиг

Вот рабочий docker-compose.yml для полнофункциональной версии (Full) — она включает LibreOffice для конвертации офисных форматов и OCR из коробки:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./data:/usr/share/tessdata
      - ./config:/configs
      - ./logs:/logs
      - ./customFiles:/customFiles
      - ./pipeline:/pipeline
    environment:
      - DOCKER_ENABLE_SECURITY=true
      - SECURITY_ENABLELOGIN=true
      - LANGS=ru_RU,en_GB
      - SYSTEM_DEFAULTLOCALE=ru-RU
      - UI_APPNAME=Stirling PDF
      - UI_HOMEDESCRIPTION=Работа с PDF на собственном сервере
      - SYSTEM_MAXFILESIZE=200
    deploy:
      resources:
        limits:
          memory: 3G

Порт намеренно привязан к 127.0.0.1 — наружу сервис будет смотреть только через reverse proxy с HTTPS, напрямую по HTTP в интернет его выставлять не стоит, особенно если включена авторизация с паролями. SECURITY_ENABLELOGIN=true включает встроенную систему пользователей и ролей — без неё любой, кто знает адрес, получает полный доступ к вашим PDF.

Запускаем:

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

Первый старт занимает от 30 секунд до пары минут — контейнер разворачивает Tesseract-языковые пакеты и прогревает LibreOffice. Когда в логах появится строка о старте Spring Boot приложения на порту 8080, можно проверять:

curl -I http://127.0.0.1:8080

Reverse proxy и HTTPS

Для внешнего доступа нужен домен или поддомен (например, pdf.вашдомен.ru), указывающий A-записью на IP сервера, и reverse proxy с TLS-терминацией. Если вы уже используете Caddy — конфиг простой, добавьте блок в Caddyfile:

pdf.example.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy сам выпустит и обновит сертификат Let's Encrypt. Если Caddy на сервере ещё не настроен, есть отдельная пошаговая статья про установку Caddy с авто-SSL на Ubuntu 24.04 — процесс занимает минут десять.

Для Nginx конфиг чуть длиннее, потому что Stirling PDF умеет загружать крупные файлы и держать долгие соединения на OCR-задачах:

server {
    listen 443 ssl http2;
    server_name pdf.example.com;

    ssl_certificate     /etc/letsencrypt/live/pdf.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pdf.example.com/privkey.pem;

    client_max_body_size 250M;
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Значение client_max_body_size подгоните под реальные файлы — если работаете со сканами многостраничных договоров или архивами PDF, 250 МБ может быть мало. Таймауты в 300 секунд нужны для OCR тяжёлых документов на слабом CPU — распознавание 50-страничного скана может занимать несколько минут, и без увеличенного таймаута nginx оборвёт соединение раньше, чем Stirling PDF успеет ответить.

Первый запуск: пользователи и права доступа

Открыв https://pdf.example.com, при первом входе система попросит создать администратора — логин и пароль задаются через веб-интерфейс, а не через переменные окружения (это осознанное решение разработчиков ради безопасности). После входа в разделе Admin можно:

• создавать дополнительных пользователей с ролями (обычный пользователь, администратор, режим только для API);
• ограничивать список доступных операций по ролям — например, дать бухгалтерии только слияние и подпись, без доступа к удалению страниц;
• включить или выключить регистрацию новых пользователей.

Если Stirling PDF нужен только вам одному и без веба, авторизацию можно отключить (SECURITY_ENABLELOGIN=false), но тогда обязательно закройте доступ на уровне firewall или Basic Auth в reverse proxy — иначе любой узнавший адрес сможет загружать и скачивать чужие файлы.

OCR и конвертация: что нужно знать заранее

Full-образ включает Tesseract OCR и LibreOffice, но по умолчанию установлены не все языковые пакеты. Русский язык добавляется через переменную LANGS=ru_RU,en_GB в compose-файле, как в примере выше — после пересоздания контейнера (docker compose up -d --force-recreate) в интерфейсе OCR появится опция распознавания на русском.

Важный нюанс с качеством: OCR хорошо справляется с чистыми сканами в 300 dpi и печатным текстом, но на фотографиях документов с телефона (кривизна, тени, низкое разрешение) точность распознавания заметно падает — это ограничение Tesseract, а не Stirling PDF, и универсального решения тут нет, кроме как пересканировать документ нормально или предобработать изображение перед загрузкой.

Конвертация PDF → Word/Excel и обратно идёт через LibreOffice в headless-режиме внутри контейнера. Сложная вёрстка (многоколоночные таблицы, встроенные формулы, нестандартные шрифты) конвертируется не идеально — это общее ограничение всех движков на базе LibreOffice/OpenOffice, включая платные облачные сервисы. Для простых текстовых документов результат обычно приемлемый, для сложных макетов лучше проверять руками после конвертации.

Бэкапы и обновление

Все пользовательские данные и настройки лежат в примонтированных томах ./data и ./config — сами PDF-файлы в постоянное хранилище не попадают, они обрабатываются в памяти контейнера и удаляются после скачивания результата. Бэкапить нужно именно эти две директории плюс сам docker-compose.yml:

tar czf stirling-backup-$(date +%F).tar.gz \
  /opt/stirling-pdf/data /opt/stirling-pdf/config /opt/stirling-pdf/docker-compose.yml

Если хотите поставить это на регулярную основу с ротацией и выгрузкой во внешнее хранилище, посмотрите статью про бэкап Docker volume на сервере — там разобраны типовые ошибки, включая бэкап «на живую» без остановки контейнера.

Обновление до новой версии — обычная процедура для Docker-сервисов:

docker compose pull
docker compose up -d

Перед крупным обновлением (смена мажорной версии) стоит свериться с release notes проекта на GitHub — в редких случаях меняется формат конфигурации или переменных окружения, и старый docker-compose.yml может потребовать правок.

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