Обзор развертывания Paperless-ngx на сервере¶

Предварительные требования¶

Для корректной работы приложения требуются следующие системные компоненты и параметры:

Операционная система: Ubuntu.
Права доступа: Права суперпользователя (root) для установки системных пакетов и создания пользователей.
Зависимости: Python 3, Redis, Tesseract OCR (с поддержкой русского языка), ImageMagick, Ghostscript, Unpaper, Poppler.
Порты:
Внутренний порт приложения: 3000.
Внешний порт доступа: 443 (через прокси).

FDQN итоговой панели на домене hostkey.in¶

Доступ к приложению осуществляется по следующему шаблону доменного имени:

Параметр	Значение
Префикс	`paperless-ngx`
Домен	`hostkey.in`
Полный шаблон	`paperless-ngx{Server_ID_from_Invapi}.hostkey.in`

Структура файлов и каталогов¶

Основные директории приложения и конфигураций:

/opt/paperless — корневой каталог приложения.
/opt/paperless/src — исходный код приложения.
/opt/paperless/.venv — виртуальное окружение Python.
/opt/paperless/data — база данных и системные данные.
/opt/paperless/media — хранилище загруженных документов.
/opt/paperless/consume — директория для автоматического импорта файлов.
/opt/paperless/export — директория для экспорта данных.
/root/nginx — конфигурация прокси-сервера Nginx и Docker Compose.

Процесс установки приложения¶

Установка выполняется в несколько этапов:

Подготовка системы: Устанавливаются системные зависимости (Python, Redis, OCR-движки и библиотеки обработки изображений).
Настройка базы данных: Запускается и активируется сервис redis-server.
Создание пользователя: Создается системный пользователь paperless с домашним каталогом /opt/paperless.
Загрузка приложения: Скачивается архив версии v2.20.15, который распаковывается в /opt/paperless.
Настройка окружения:
Создаются необходимые рабочие директории (data, media, consume, export).
Из файла requirements.txt удаляются неиспользуемые зависимости (mysqlclient, psycopg-c).
Создается виртуальное окружение Python и устанавливаются все необходимые библиотеки через pip.
Конфигурация:
Создается файл конфигурации paperless.conf с настройками часового пояса (Europe/Moscow) и путей к директориям.
Настраивается политика ImageMagick для разрешения обработки PDF-файлов.
Инициализация данных: Выполняются миграции базы данных через manage.py migrate. Создается учетная запись администратора (superuser).
Настройка служб: Создаются и активируются системные службы systemd для управления процессами веб-сервера, потребителя документов, планировщика задач и очереди задач.

Права доступа и безопасность¶

Для работы приложения используется выделенный системный пользователь paperless.
Файл конфигурации paperless.conf имеет ограниченные права доступа (0640), доступные только владельцу и группе.
Настройка ImageMagick изменяет политику безопасности для обеспечения возможности чтения/записи PDF.

Базы данных¶

Приложение использует Redis в качестве основного хранилища (через redis-server) для управления очередями задач и фоновыми процессами. Данные приложения хранятся локально в директории /opt/paperless/data.

Контейнеры Docker и их запуск¶

Для обеспечения работы веб-сервера с SSL-сертификатами используется контейнер:

Имя образа	Порты	Тома (volumes)	Переменные окружения	Политика перезапуска
`jonasal/nginx-certbot:latest`	`host` mode	`nginx_secrets:/etc/letsencrypt`, `/data/nginx/user_conf.d:/etc/nginx/user_conf.d`	`CERTBOT_EMAIL=hkadm@hostkey.com`	`unless-stopped`

Контейнер Nginx работает в режиме network_mode: host для обеспечения корректной работы с сертификатами и проксированием трафика.

Кастомные скрипты и дополнительные настройки¶

В процессе развертывания выполняются следующие действия:

Настройка ImageMagick: В файл /etc/ImageMagick-6/policy.xml вносятся изменения для снятия ограничений на обработку PDF.
Управление очередями: Настраиваются специализированные службы systemd для управления компонентами Celery (worker, beat) и потребителем документов (document_consumer).

Инструкция по обновлению приложения¶

Для обновления основного приложения необходимо:

Перейти в директорию /opt/paperless.
Выполнить обновление через пакетный менеджер или перезапуск установочного процесса для подтягивания новой версии исходного кода.
Обновить зависимости в виртуальном окружении: pip install -r requirements.txt внутри .venv.
Выполнить миграции базы данных: /opt/paperless/.venv/bin/python manage.py migrate из директории /opt/paperless/src.

Расположение конфигурационных файлов и данных¶

Конфигурация приложения: /opt/paperless/paperless.conf
Данные пользователя: /opt/paperless/media
Файлы для автоматического импорта: /opt/paperless/consume
База данных (в рамках структуры): /opt/paperless/data

Доступные порты для подключения¶

443 (HTTPS): Основной порт доступа к веб-интерфейсу через Nginx.
3000 (HTTP): Внутренний порт приложения Paperless-ngx.
6379: Порт Redis.