ATTENTION: 👷‍♀️ This project will be assimilated into the official paperless-ngx repo very soon.

Status	Event
	Weekly schedule
	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