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

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

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

Операционная система: Ubuntu.
Системные зависимости: python3, python3-pip, python3-venv, python3-dev, redis-server, tesseract-ocr (включая поддержку русского языка tesseract-ocr-rus), imagemagick, ghostscript, unpaper, libpoppler-cpp-dev, libmagic-dev, mime-support, fonts-liberation.
Права доступа: Необходим доступ с правами суперпользователя для установки системных пакетов и создания пользователей.

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 — база данных и рабочие данные Paperless.
/opt/paperless/media — хранилище медиафайлов (документов).
/opt/paperless/consume — директория для загрузки новых документов на обработку.
/opt/paperless/export — директория для экспорта данных.
/root/nginx — конфигурации и файлы Docker Compose для прокси-сервера.

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

Развертывание выполняется путем распаковки архива версии v2.20.15 из репозитория GitHub в директорию /opt/paperless. После распаковки происходит:

Создание системного пользователя paperless.
Установка зависимостей Python через pip в виртуальное окружение.
Выполнение миграций базы данных через manage.py migrate.
Создание суперпользователя для доступа к веб-интерфейсу.

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

Пользователь: Для работы основных процессов используется системный пользователь paperless с домашней директорией /opt/paperless.
Безопасность ImageMagick: В конфигурационном файле /etc/ImageMagick-6/policy.xml разрешено чтение и запись PDF-файлов для обеспечения корректной обработки документов.
Конфигурация: Файл paperless.conf имеет права доступа 0640, доступные только пользователю paperless и группе paperless.

Базы данных¶

В качестве хранилища используется встроенная база данных (через Django ORM), а для управления очередями задач и кэширования используется Redis, работающий как системный сервис (redis-server).

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

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

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

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

Обновление выполняется через обновление пакетов или перезапуск скрипта установки. Для контейнера Nginx используется команда:

docker compose up -d

в директории /root/nginx.

Настройки прав¶

Все основные рабочие директории (data, media, consume, export) принадлежат пользователю paperless и группе paperless.

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

Конфигурация Paperless: /opt/paperless/paperless.conf
Конфигурация Nginx (Docker): /data/nginx/user_conf.d
Секреты SSL: в томе nginx_secrets.

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

Порт	Назначение	Режим доступа
`443`	HTTPS (через Nginx)	Внешний доступ
`3000`	Веб-интерфейс Paperless	Внутренний (локальный)

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

Управление основными компонентами приложения осуществляется через systemd:

Запуск всех сервисов:

systemctl start paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue redis-server

Остановка сервисов:

systemctl stop paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue

Прокси серверы¶

Для обеспечения защищенного соединения используется Nginx в связке с Certbot. Контейнер nginx-certbot автоматически управляет получением и обновлением SSL-сертификатов Let's Encrypt. Трафик перенаправляется на внутренний порт приложения 3000.