Статус	Событие
	Еженедельное расписание
	Последний PR

Ansible Роль: paperless_ngx

Устанавливает и настраивает систему управления электронными документами paperless-ngx.

1. Требования

1.1. Ansible

Требуется Ansible версии не ниже 2.12.

Необходимо установить следующие коллекции Ansible (через ansible-galaxy collection install):

• community.general
• ansible.posix

1.2. Поддерживаемые операционные системы

• Debian (>=11)
• Ubuntu (>=focal)

2. Переменные роли

Большинство переменных конфигурации от самого paperless-ngx доступны и принимают соответствующие аргументы. Каждая переменная конфигурации PAPERLESS_* преобразуется в нижний регистр и вместо этого префиксируется как paperless_ngx_conf_* в defaults/main.yml.

Полный список с объяснениями и разрешенными значениями можно найти в текущей документации.

Следующие разделы делятся на:

• Переменные, специфичные для роли
• Переменные конфигурации оригинального paperless-ngx

2.1. Переменные, специфичные для роли

Имя	Значение по умолчанию	Описание
paperless_ngx_db_type	sqlite	Доступные типы БД - sqlite и postgresql. Если выбран postgresql, необходимо также настроить другие переменные, связанные с БД.
paperless_ngx_dependency_install_tmp_dir	/tmp/	Директория для временных файлов установки зависимостей
paperless_ngx_dir_force_permission_exclude	[]	Какие директории следует исключить из проверки/установки прав. См. документацию.
paperless_ngx_dir_installation	/opt/paperless-ngx	Директория, в которую записываются статические файлы установки paperless-ngx.
paperless_ngx_dir_python	/opt/python/{{ paperless_ngx_python_version_short }}	Директория, в которую компилируются бинарные файлы python.
paperless_ngx_dir_runtime_data	/var/lib/paperless-ngx	Директория, где будут храниться данные во время выполнения.
paperless_ngx_dir_virtualenv	"{{ paperless_ngx_dir_installation }}/.venv"	Директория для необходимого python venv.
paperless_ngx_jbig2enc_enabled	true	Нужно ли устанавливать и использовать jbig2enc для OCRmyPDF.
paperless_ngx_jbig2enc_lossy	false	Запускать jbig2enc в режиме с потерями или нет.
paperless_ngx_jbig2enc_version	0.29	Какую версию установить.
paperless_ngx_redis_host	localhost	Хост Redis
paperless_ngx_redis_port	6379	Порт Redis
paperless_ngx_system_group	paperlessngx	Группа, к которой принадлежит системный пользователь.
paperless_ngx_system_user	paperlessngx	Пользователь, который будет выполнять службы и владеть данными.
paperless_ngx_system_user_additional_groups	[]	Опционально добавьте системного пользователя в дополнительные группы. Например, для чтения сертификатов TLS, которые могут быть прочитаны группой ssl-cert.
paperless_ngx_version	latest	Версия программного обеспечения для установки. Используйте latest или конкретную версию в формате '2.0.0'. Поддерживается только paperless_ngx_version_minimum: '2.0.0' и выше.
``

2.2. Переменные конфигурации Paperless-ngx

Все следующие переменные соответствуют переменным из документации paperless-ngx. Следующий список переменных отсортирован в алфавитном порядке для упрощения обслуживания этой роли. В официальной документации они распределены по соответствующим категориям.

3. Рекомендации по использованию

3.1. Обновление Paperless-ngx

Если вы установили Paperless-ngx с помощью этой роли и хотите обновить ее до более новой версии, вам нужно просто снова запустить эту роль (если вы выбрали latest в качестве идентификатора версии). Если вы указали конкретную версию для установки, вам просто нужно изменить это значение на более новое и снова запустить роль.

Эта роль не будет обновлять ничего другого, кроме Paperless-ngx. Поэтому обновления операционной системы и зависимых пакетов нужно обрабатывать отдельно.

ПОЖАЛУЙСТА, ПОДУМАЙТЕ О РЕЗЕРВНЫХ КОПИЯХ перед обновлением.

3.2. Резервное копирование/восстановление

Обратите внимание, что эта роль не предлагает механизм резервного копирования или восстановления. Это намеренно. Для разделения задач эта роль сосредоточена только на "развертывании" программных артефактов и их конфигурации. Пример рабочей стратегии резервного копирования можно найти здесь: Ссылка на пример стратегии резервного копирования

3.3. Сгенерированный пароль

Роль использует поиск пароля Ansible:

• Если пароль сгенерирован ролью, Ansible хранит его локально в pngx_instances/{{ инвентарный_хост }} (относительно рабочей директории)
• если файл уже существует, используется его содержимое
• смотрите документацию по поиску паролей Ansible для получения дополнительной информации

3.4. Разделение статических (~ установки) и динамических (~ времени выполнения) данных

Эта роль проверяет, чтобы вы не устанавливали одну из директорий данных (например, consumption и т. д.) в подкаталог пути установки. Для упрощения жизни эта роль удаляет папку установки и создает совершенно новую при обновлении. Это свежо и чисто. Также таким образом вы избавитесь от нежелательной потери данных во время обновлений.

3.5. Использование PostgreSQL

Если вы хотите использовать Paperless-ngx вместе с PostgreSQL, необходима работающая инстанция PostgreSQL. Эта роль автоматически не устанавливает такую базу данных для вас. Однако, вот пример, как настроить такую инстанцию с нуля: Ссылка на пример плейбука

4. Зависимости

Нет зависимостей

5. Примеры плейбуков

minimal_runnable_playbook.yml:

- hosts: все
    roles:
        - { role: paperless_ngx.paperless_ngx }
    vars:
        var1:
        var2:
        ...

6. Вклад

Мы приветствуем ваш вклад в эту роль! Пожалуйста, ознакомьтесь с руководством по внесению вклада для получения рекомендаций о дальнейшем процессе.

7. Лицензия

MIT