Як встановити та налаштувати Paperless-ngx на VPS: посібник із self-hosted документообігу

1. Що ми налаштовуємо та навіщо: філософія Paperless-ngx

У 2026 році проблема накопичення паперових документів — чеків, договорів, медичних виписок, інструкцій та рахунків — залишається актуальною. Звичайне сканування в папку на комп'ютері не вирішує задачу: знайти потрібний документ серед сотень файлів "SCAN_001.pdf" практично неможливо. Саме тут на сцену виходить Paperless-ngx.

Paperless-ngx — це форк популярного проекту Paperless-ng, який, в свою чергу, виріс з оригінального Paperless. Це веб-додаток, який індексує ваші скани. Основна магія відбувається в процесі OCR (Optical Character Recognition): система "читає" текст на зображенні або в PDF-файлі, зберігає його в базу даних і дозволяє миттєво знаходити документи за ключовими словами.

Чому варто обрати self-hosted рішення на власному VPS замість хмарних сервісів на кшталт Google Drive або спеціалізованих платних DMS?

• Конфіденційність: Ваші фінансові документи та персональні дані зберігаються на вашому сервері, а не на серверах корпорацій, які можуть аналізувати їх для реклами.
• Відсутність лімітів: Ви обмежені лише обсягом диска вашого VPS. Немає обмежень на кількість документів або користувачів.
• Автоматизація: Ви можете налаштувати "гарячу папку" (consumption folder). Як тільки файл потрапляє туди (через FTP, SMB або мобільний додаток), Paperless-ngx автоматично його обробляє, розпізнає, присвоює теги та відправляє в архів.
• Інтелектуальне тегування: Система використовує машинне навчання для автоматичного визначення кореспондента (відправника) та типу документа на основі накопиченого досвіду.

2. Який VPS-конфіг потрібен під цю задачу

Paperless-ngx — досить вимогливий до ресурсів додаток, особливо в моменти обробки нових документів. Процес OCR (розпізнавання тексту) активно навантажує процесор, а база даних та пошуковий рушій вимагають оперативної пам'яті.

Мінімальні та рекомендовані характеристики сервера наведено в таблиці нижче:

Важливо враховувати, що при нестачі оперативної пам'яті процес OCR може аварійно завершуватися, залишаючи документи необробленими. Якщо ви плануєте завантажувати відразу тисячі сторінок архіву, орієнтуйтеся на більш потужні конфігурації.

Для стабільної роботи та швидкої обробки документів ми рекомендуємо розглянути VPS з вказаними характеристиками. Наявність NVMe дисків значно прискорить індексацію та пошук по базі даних.

Локація сервера: Оскільки ви будете завантажувати особисті документи, вибирайте локацію з мінімальним пінгом до вас і в юрисдикції, якій ви довіряєте. Для користувачів з Європи оптимальні дата-центри в Німеччині або Нідерландах.

3. Підготовка сервера: безпека та залежності

Перш ніж встановлювати сам застосунок, необхідно підготувати середовище. Безпека критично важлива, оскільки DMS міститиме ваші найчутливіші дані.

Оновимо список пакетів і встановлене ПЗ:

sudo apt update && sudo apt upgrade -y

Встановимо базовий набір утиліт, які знадобляться нам у процесі роботи:

sudo apt install -y curl wget git vim software-properties-common ufw fail2ban

Налаштуємо базовий міжмережевий екран (Firewall). Нам потрібно відкрити порти для SSH, HTTP і HTTPS:

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Рекомендовано також створити окремого користувача з правами sudo, щоб не виконувати всі дії від імені root:

# Створення користувача (замініть 'adminuser' на своє ім'я)
sudo adduser adminuser
sudo usermod -aG sudo adminuser
# Переключення на нового користувача
su - adminuser

4. Встановлення Docker і Docker Compose

Paperless-ngx складається з кількох компонентів (веб-сервер, база даних, брокер повідомлень, OCR-рушій). Найнадійніший і найпростіший спосіб запустити все це — використовувати Docker Compose. У 2026 році Docker є стандартом де-факто для self-hosted рішень.

Встановимо Docker з офіційного репозиторію:

# Додаємо GPG-ключ Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Додаємо репозиторій
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Встановлюємо пакети
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Додамо нашого користувача до групи docker, щоб не вводити sudo щоразу:

sudo usermod -aG docker $USER
# Застосуйте зміни групи (або перезайдіть по SSH)
newgrp docker

Перевіримо працездатність:

docker compose version

5. Встановлення Paperless-ngx: покрокове розгортання

Розробники Paperless-ngx надають зручний скрипт для встановлення, але ми розберемо "ручний" метод через Docker Compose, оскільки він дає більше контролю над конфігурацією та шляхами зберігання даних.

Створимо директорію для проєкту:

mkdir ~/paperless-ngx && cd ~/paperless-ngx

Для роботи нам знадобляться три файли: docker-compose.yml, docker-compose.env і порожні папки для даних.

Створимо структуру папок:

mkdir -p {data,media,export,consume,db}

Тепер створимо файл конфігурації оточення docker-compose.env. Це "серце" налаштувань вашого сервера. Обов'язково змініть значення паролів і секретного ключа!

# Секретний ключ (згенеруйте довгий випадковий рядок)
PAPERLESS_SECRET_KEY=change-this-to-something-very-long-and-random

# Налаштування бази даних
PAPERLESS_DBENGINE=postgresql
PAPERLESS_DBHOST=db
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=your_strong_password_here

# Налаштування Redis
PAPERLESS_REDIS=redis://broker:6379

# Мови OCR (додайте потрібні, наприклад rus, eng, deu)
PAPERLESS_OCR_LANGUAGE=rus+eng

# Часовий пояс
PAPERLESS_TIME_ZONE=Europe/Moscow

# Налаштування URL (вкажіть ваш домен пізніше)
PAPERLESS_URL=https://paperless.yourdomain.com

Тепер створимо основний файл docker-compose.yml. Ми будемо використовувати актуальні версії образів на 2026 рік:

services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - ./redisdata:/data

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    volumes:
      - ./db:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: your_strong_password_here

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db

Запускаємо контейнери у фоновому режимі:

docker compose up -d

Після запуску необхідно створити першого суперкористувача (адміна):

docker compose exec webserver python3 manage.py createsuperuser

Дотримуйтесь інструкцій у терміналі, щоб задати логін, пошту та пароль.

6. Глибока конфігурація: OCR, мови та пошта

Однією з найпотужніших функцій Paperless-ngx є можливість автоматичного збору документів з електронної пошти. Наприклад, ви можете налаштувати систему так, щоб вона перевіряла вашу скриньку та автоматично завантажувала рахунки від провайдерів.

Додайте наступні параметри до вашого docker-compose.env для налаштування поштового агрегатора:

# Включення обробки пошти
PAPERLESS_EMAIL_SECRET=your_email_password_or_app_token
# Частота перевірки (в хвилинах)
PAPERLESS_EMAIL_TASK_INTERVAL=10

Налаштування OCR (Tesseract):

Paperless-ngx використовує Tesseract для розпізнавання тексту. Ви можете налаштувати режим роботи OCR через змінну PAPERLESS_OCR_MODE:

• clean: Створює PDF з текстовим шаром, очищаючи оригінал (за замовчуванням).
• redo: Примусово запускає OCR, навіть якщо в PDF вже є текстовий шар.
• skip: Пропускає OCR, якщо текст вже виявлено.

Якщо у вас слабкий процесор на VPS, можна обмежити кількість потоків для OCR, щоб сервер не "зависав" під час завантаження великих файлів:

# Обмеження до 2 паралельних процесів OCR
PAPERLESS_OCR_THREADS=2

Обробка документів Office:

За замовчуванням Paperless-ngx добре працює з PDF та зображеннями. Щоб він розумів .docx, .xlsx та .pptx, потрібно додати сервіс Gotenberg та Tika. Це розширить можливості системи до повноцінного офісного комбайна.

7. Налаштування веб-сервера та HTTPS (SSL)

Запускати Paperless-ngx на порту 8000 через незашифрований HTTP — небезпечно. Нам потрібен Reverse Proxy, який забезпечить підтримку HTTPS через Let's Encrypt.

Ми будемо використовувати Caddy, оскільки він автоматично отримує та продовжує SSL-сертифікати, вимагаючи мінімум налаштувань.

Встановимо Caddy на VPS:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1G 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1G 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Відредагуємо файл конфігурації Caddy (/etc/caddy/Caddyfile):

paperless.yourdomain.com {
    reverse_proxy localhost:8000
    
    header {
        # Налаштування безпеки
        Strict-Transport-Security "max-age=31536000;"
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Referrer-Policy no-referrer-when-downgrade
    }
}

Перезапустіть Caddy, щоб застосувати зміни:

sudo systemctl restart caddy

Тепер ваш Paperless-ngx доступний за адресою https://paperless.yourdomain.com з валідним SSL-сертифікатом.

8. Бекапи та обслуговування: зберігаємо дані назавжди

Документи — це дані, які не можна втрачати. У Paperless-ngx потрібно бекапити три речі: базу даних, медіа-файли (самі документи) та конфігураційні файли.

Метод 1: Експорт вбудованою утилітою

Paperless-ngx має вбудовану команду експорту, яка вивантажує все в папку /export:

docker compose exec webserver document_exporter ../export/

Метод 2: Скрипт автоматичного бекапу

Створимо простий bash-скрипт backup.sh, який буде архівувати дані та відправляти їх у віддалене сховище (наприклад, S3 або інший сервер через rsync):

#!/bin/bash
BACKUP_DIR="/home/adminuser/backups"
DATE=$(date +%Y-%m-%d)
PROJECT_DIR="/home/adminuser/paperless-ngx"

mkdir -p $BACKUP_DIR

# 1. Дамп бази даних PostgreSQL
docker compose exec -t db pg_dumpall -c -U paperless > $BACKUP_DIR/db_backup_$DATE.sql

# 2. Архівація медіа-файлів та конфігів
tar -czf $BACKUP_DIR/paperless_files_$DATE.tar.gz -C $PROJECT_DIR data media docker-compose.yml docker-compose.env

# 3. Видалення старих бекапів (старше 30 днів)
find $BACKUP_DIR -type f -mtime +30 -delete

Додайте виконання скрипта в crontab (crontab -e), щоб він запускався щоночі о 03:00:

0 3   * /bin/bash /home/adminuser/paperless-ngx/backup.sh

9. Troubleshooting + FAQ

Чому процес OCR займає так багато часу?

Розпізнавання тексту — ресурсомістка задача. На 2-ядерному VPS одна сторінка може оброблятися від 5 до 20 секунд. Якщо ви завантажили відразу 100 документів, система поставить їх у чергу. Перевірити стан черги можна у веб-інтерфейсі в розділі "Settings" -> "Worker Status". Для прискорення процесу збільште кількість ядер CPU.

Помилка "Out of Memory" при обробці великих PDF

Це відбувається, коли Tesseract намагається обробити багатосторінковий документ високої роздільної здатності. Рішення: додайте Swap-файл на ваш VPS (мінімум 2-4 ГБ). Це дозволить системі використовувати диск як тимчасову оперативну пам'ять.

Як оновити Paperless-ngx до останньої версії?

Завдяки Docker оновлення проходить безшовно:

cd ~/paperless-ngx
docker compose pull
docker compose up -d

Docker автоматично завантажить нові образи та перезапустить контейнери, зберігши всі ваші дані.

Який VPS-конфіг мінімально підійде?

Мінімально працездатний варіант — 2 ГБ RAM та 2 vCPU, але вам обов'язково потрібно буде налаштувати Swap-файл, інакше веб-інтерфейс буде "падати" під час завантаження документів. Для комфортної роботи без затримок ми рекомендуємо 4-8 ГБ RAM.

Що вибрати — VPS чи dedicated для цієї задачі?

Для особистого архіву (до 10 000 документів) VPS більш ніж достатньо. Dedicated сервер варто розглядати тільки в тому випадку, якщо ви впроваджуєте Paperless-ngx у великій компанії з десятками співробітників, які щодня сканують сотні сторінок, або якщо вам потрібен екстремально високий рівень дискової продуктивності для миттєвого пошуку по мільйонам слів.

Як сканувати документи прямо в Paperless?

Найзручніший спосіб — мобільні додатки (наприклад, Paperless Mobile для iOS/Android). Вони дозволяють сфотографувати документ, обрізати його та відправити по API у ваш Paperless-ngx. Також багато сучасних сканерів підтримують функцію "Scan to FTP" — налаштуйте сканер на відправку файлів у папку consume на вашому сервері.

10. Висновки та наступні кроки

Ми успішно розгорнули професійну систему управління документами на власному сервері. Тепер у вас є безпечне, швидке та повністю контрольоване сховище для всіх ваших паперів.

Що робити далі для поліпшення системи?

• Налаштуйте ієрархію тегів: Розділіть документи за категоріями: "Фінанси", "Здоров'я", "Робота", "Авто".
• Підключіть IMAP: Налаштуйте автоматичне збирання листів з вашої поштової скриньки, щоб рахунки за інтернет або електрику потрапляли в архів самі.
• Організуйте офлайн-копію: Налаштуйте синхронізацію папки export з вашим домашнім ПК або NAS через Syncthing, щоб мати доступ до документів навіть за відсутності інтернету.

Перехід на безпаперовий офіс — це не тільки екологічно, але й неймовірно зручно. Більше жодних папок-реєстраторів та втрачених гарантійних талонів — все, що вам потрібно, тепер знаходиться на відстані одного пошукового запиту.