Skip to content

Ansible role to set up paperless-ngx πŸ‘·β€β™€οΈ 🚧 Continued under official paperless-ngx organisation

Notifications You must be signed in to change notification settings

stevenengland/paperless_ngx_ansible_role

Repository files navigation

ATTENTION: πŸ‘·β€β™€οΈ This project will be assimilated into the official paperless-ngx repo very soon.

Status Event
Code Testing Weekly schedule
Code Testing Last PR

Ansible Role: paperless-ngx

Installs and configures paperless-ngx EDMS on Debian/Ubuntu systems.

NOTE: This role is based on the role made by the devs of paperless-ngx itself paperless-ngx/ansible. Because the role seems to be stale and I wanted to dive deeper into ansible as well as paperless-ngx I devided to recreate the role.

Requirements

No special system requirements. ansible_version_minimum: "4.0.0" or newer is required.

Role Variables

Most configuration variables from paperless-ngx itself are available and accept their respective arguments. Every PAPERLESS_* configuration variable is lowercased and instead prefixed with paperless_ngx_conf_* in defaults/main.yml.

For a full listing including explanations and allowed values, see the current documentation.

The following sections are devided into:

  • Role specific variables
  • Original paperless-ngx configuration variables

Role specific variables

Name Default Value Description
paperless_ngx_backup_on_upgrade true Whether to backup old installation files before upgrade.
paperless_ngx_db_type sqlite Available db types are sqlite and postgresql. If postrgresql is chosen then the other db_ vars must be configured too.
paperless_ngx_dir_force_permission_exclude [] Which directories should be skipped from permission check/setting. See docs.
paperless_ngx_dir_installation /opt/paperless-ngx The directory where paperless-ngx static installation files are written to.
paperless_ngx_dir_runtime_data /var/lib/paperless-ngx The directory where the runtime data will be stored.
paperless_ngx_dir_virtualenv "{{ paperless_ngx_dir_installation }}/.venv" The directory for the needed python venv.
paperless_ngx_jbig2enc_enabled true Whether to install and use jbig2enc for OCRmyPDF.
paperless_ngx_jbig2enc_lossy false Run jbig2enc in lossy mode or not.
paperless_ngx_jbig2enc_tmp_dir /tmp/ Directory for temporary jbig2enc files
paperless_ngx_jbig2enc_version 0.29 Which version to install.
paperless_ngx_redis_host localhost Redis host
paperless_ngx_redis_port 6379 Redis port
paperless_ngx_system_group paperlessngx The group to which the system user belongs.
paperless_ngx_system_user paperlessngx The user that will execute the services and own the data.
paperless_ngx_system_user_additional_groups [] Optionally add the system user to more groups. For example to read TLS certificates that can be read by the group ssl-cert.
paperless_ngx_version latest Sofware version to install. Use latest or any specific version in the format '1.10.0'. Only paperless_ngx_version_minimum: '1.10.0' and higher supported.
``

paperless-ngx configuration variables

All the upcoming vars correspond with the vars from paperless-ngx docs. To save reading space a few abbreviations are used in the tables down below:

  • I - Implemented in this role? [Y/N]
  • O - Variable is meant to be overridden? [Y/N] If No it should not be altered.
  • H - Hint
  • V - Version of paperless-ngx that introduced this var.

Required services

Name Default Value I O H V
paperless_ngx_conf_redis redis://{{ paperless_ngx_redis_host }}:{{ paperless_ngx_redis_port }} Y N
paperless_ngx_conf_dbengine Y N Not used by the role
paperless_ngx_conf_dbhost localhost Y Y
paperless_ngx_conf_dbport 5432 Y Y
paperless_ngx_conf_dbname paperlessngx Y Y
paperless_ngx_conf_dbuser paperlessngx Y Y
paperless_ngx_conf_dbpass "" Y Y The db password. If not defined by the user, a random password will be generated -> see section below about passwords.
paperless_ngx_conf_dbsslmode prefer Y Y
paperless_ngx_conf_db_timeout Y Y

Path and folders

Name Default Value I O H V
paperless_ngx_conf_consumption_dir "{{ paperless_ngx_dir_runtime_data }}/consumption" Y Y
paperless_ngx_conf_data_dir "{{ paperless_ngx_dir_runtime_data }}/data" Y Y
paperless_ngx_conf_trash_dir "{{ paperless_ngx_dir_runtime_data }}/trash" Y Y
paperless_ngx_conf_media_root "{{ paperless_ngx_dir_runtime_data }}/media" Y Y
paperless_ngx_conf_staticdir ../static Y N
paperless_ngx_conf_filename_format "" Y Y
paperless_ngx_conf_filename_format_remove_none false Y Y
paperless_ngx_conf_logging_dir "{{ paperless_ngx_dir_runtime_data }}/log"
paperless_ngx_conf_nltk_dir /usr/share/nltk_data Y Y 1.11

Logging

Name Default Value I O H V
paperless_ngx_conf_logrotate_max_size 1024 * 1024 Y Y
paperless_ngx_conf_logrotate_max_backups 20 Y Y

Hosting & Security

Name Default Value I O H V
paperless_ngx_conf_secret_key "" Y Y If not defined by the user, a random password will be generated -> see section below about passwords.
paperless_ngx_conf_url http://localhost:8000 Y Y
paperless_ngx_conf_csrf_trusted_origins Y Y
paperless_ngx_conf_allowed_hosts "*" Y Y
paperless_ngx_conf_cors_allowed_hosts http://localhost:8000 Y Y
paperless_ngx_conf_force_script_name "" Y Y
paperless_ngx_conf_static_url /static/ Y Y
paperless_ngx_conf_auto_login_username "" Y Y
paperless_ngx_conf_admin_user admin Y Y
paperless_ngx_conf_admin_mail root@localhost Y Y
paperless_ngx_conf_admin_password Y Y The superuser password. If not defined by the user, a random password will be generated -> see section below about passwords.
paperless_ngx_conf_cookie_prefix "" Y Y
paperless_ngx_conf_enable_http_remote_user "" Y Y
paperless_ngx_conf_http_remote_user_header_name HTTP_REMOTE_USER Y Y
paperless_ngx_conf_logout_redirect_url Y Y

OCR settings

Name Default Value I O H V
paperless_ngx_conf_ocr_language eng Y Y
paperless_ngx_conf_ocr_mode skip Y Y
paperless_ngx_conf_ocr_clean clean Y Y
paperless_ngx_conf_ocr_deskew true Y Y
paperless_ngx_conf_ocr_rotate_pages true Y Y
paperless_ngx_conf_ocr_rotate_pages_threshold 12 Y Y
paperless_ngx_conf_ocr_output_type pdfa Y Y
paperless_ngx_conf_ocr_pages 0 Y Y
paperless_ngx_conf_ocr_image_dpi "" Y Y
paperless_ngx_conf_ocr_max_image_pixels Y Y
paperless_ngx_conf_ocr_user_args [optimize=1] Y Y

Tika settings

Name Default Value I O H V
paperless_ngx_conf_tika_enabled false Y Y
paperless_ngx_conf_tika_endpoint http://localhost:9998 Y Y
paperless_ngx_conf_tika_gotenberg_endpoint http://localhost:3000 Y Y

Software tweaks

Name Default Value I O H V
paperless_ngx_conf_task_workers 1 Y Y
paperless_ngx_conf_threads_per_worker paperless_ngx_conf_task_workers Y Y
paperless_ngx_conf_worker_timeout 1800 Y Y
paperless_ngx_conf_time_zone Europe/London Y Y
paperless_ngx_conf_enable_nltk 1 Y Y 1.11
paperless_ngx_conf_email_task_cron "*/10 * * * *" Y Y 1.12
paperless_ngx_conf_train_task_cron "5 */1 * * *" Y Y 1.12
paperless_ngx_conf_index_task_cron "0 0 * * *" Y Y 1.12
paperless_ngx_conf_sanity_task_cron "30 0 * * sun" Y Y 1.12
paperless_ngx_conf_enable_compression true Y Y 1.13

Polling

Name Default Value I O H V
paperless_ngx_conf_consumer_polling 0 Y Y
paperless_ngx_conf_consumer_polling_retry_count 5 Y Y
paperless_ngx_conf_consumer_polling_delay 5 Y Y

iNotify

Name Default Value I O H V
paperless_ngx_conf_consumer_inotify_delay 0.5 Y Y
paperless_ngx_conf_consumer_delete_duplicates false Y Y
paperless_ngx_conf_consumer_recursive false Y Y
paperless_ngx_conf_consumer_subdirs_as_tags false Y Y
paperless_ngx_conf_consumer_enable_barcodes false Y Y
paperless_ngx_conf_consumer_barcode_tiff_support false Y Y
paperless_ngx_conf_consumer_barcode_string 'PATCHT' Y Y
paperless_ngx_conf_consumer_enable_asn_barcode false Y Y 1.12
paperless_ngx_conf_consumer_asn_barcode_prefix ASN Y Y 1.12
paperless_ngx_conf_convert_memory_limit 0 Y Y
paperless_ngx_conf_convert_tmpdir "" Y Y
paperless_ngx_conf_post_consume_script "" Y Y
paperless_ngx_conf_filename_date_order "" Y Y
paperless_ngx_conf_number_of_suggested_dates 3 Y Y
paperless_ngx_conf_thumbnail_font_name /usr/share/fonts/liberation/LiberationSerif-Regular.ttf Y Y
paperless_ngx_conf_ignore_dates "" Y Y
paperless_ngx_conf_date_order "DMY" Y Y
paperless_ngx_conf_consumer_ignore_patterns [".DS_STORE/", "._", ".stfolder/", ".stversions/", ".localized/*", "desktop.ini"] Y Y

Binaries

Name Default Value I O H V
paperless_ngx_conf_convert_binary convert Y Y
paperless_ngx_conf_gs_binary gs Y Y

Docker specific options

Note: These settings are called Docker specific in the paperless-ngx docs but in case of this role they are also applied for bare metal/lxc installations. Some of them would have been better placed under other sections (like webserver workers would have been better placed under hosting settings). But to keep aligned with the paperless-ngx docs they are written down here.

Name Default Value I O H V
paperless_ngx_conf_webserver_workers 1 Y Y
paperless_ngx_conf_bind_addr "[::]" Y Y
paperless_ngx_conf_port 8000 Y Y
paperless_ngx_conf_usermap_uid Y Y System users id
paperless_ngx_conf_usermap_gid Y Y System users gid
paperless_ngx_conf_ocr_languages [eng,deu,fra,ita,spa] Y Y
paperless_ngx_conf_enable_flower false Y Y Whether to start flower or not. See using flower for more information 1.10

Update Checking

Name Default Value I O H V
paperless_ngx_conf_enable_update_check Y Y Will be removed in the future

Usage advice

Generated password

The role uses Ansible's password lookup:

  • If a password is generated by the role, ansible stores it locally in pngx_instances/{{ incentory_hostname }}/ (relative to the working directory)
  • if the file already exist, it reuse its content
  • see the ansible password lookup documentation for more info

Separation of static (~ installation) and dynamic (~ runtime) data

This role checks that you do not set one of the data dirs (like consumption etc.) as a subdirectory of the installation path. For making my life easier this role deletes the installation folder and creates a complete new one when upgrading. This is fresh and clean. Also this way you are kept from unwanted deletions of your data during upgrades.

Dependencies

There is a dependency on jmespath. This is included as part of the community.general collection within ansible. Please follow this link for more information - https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html#selecting-json-data-json-queries

Example Playbooks

minimal_runnable_playbook.yml:

- hosts: all
    roles:
        - { role: stevenengland.paperless_ngx }
    vars:
        var1:
        var2:
        ...

Contributing

We encourage you to contribute to this role! Please check out the contributing guide for guidelines about how to proceed.

License

MIT

About

Ansible role to set up paperless-ngx πŸ‘·β€β™€οΈ 🚧 Continued under official paperless-ngx organisation

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published