Status	Event
	Weekly schedule
	Last PR

Ansible Role: paperless_ngx

Installs and configures paperless-ngx EDMS.

1. Requirements
- 1.1. Ansible
- 1.2. Supported operating systems
1. Role Variables
- 2.1. Role specific variables
- 2.2. Paperless-ngx configuration variables
1. Usage advices
- 3.1. Updating Paperless-ngx
- 3.2. Backup/Restore
- 3.3. Generated password
- 3.4. Separation of static (~ installation) and dynamic (~ runtime) data
- 3.5. PostgreSQL usage
1. Dependencies
1. Example Playbooks
1. Contributing
1. License

1. Requirements

1.1. Ansible

ansible_version_minimum: "2.12" or newer is required.

The following Ansible collections need to be installed (via ansible-galaxy collection install)

community.general
ansible.posix

1.2. Supported operating systems

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

2. 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

2.1. Role specific variables

Name	Default Value	Description
`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.
``

2.2. Paperless-ngx configuration variables

All the upcoming vars correspond with the vars from paperless-ngx docs. The following list of variables is sorted alphabetically to simplify maintenance of this role. In the official documentation, these are assigned to corresponding categories.

To save reading space a few abbreviations are used in the table 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.

Name	Default Value	I	O	H	V
`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_admin_user`	admin	Y	Y
`paperless_ngx_conf_allowed_hosts`	"*"	Y	Y
`paperless_ngx_conf_auto_login_username`	""	Y	Y
`paperless_ngx_conf_bind_addr`	"[::]"	Y	Y
`paperless_ngx_conf_consumer_asn_barcode_prefix`	ASN	Y	Y		1.12
`paperless_ngx_conf_consumer_barcode_string`	'PATCHT'	Y	Y
`paperless_ngx_conf_consumer_barcode_tiff_support`	false	Y	Y
`paperless_ngx_conf_consumer_delete_duplicates`	false	Y	Y
`paperless_ngx_conf_consumer_enable_asn_barcode`	false	Y	Y		1.12
`paperless_ngx_conf_consumer_enable_barcodes`	false	Y	Y
`paperless_ngx_conf_consumer_ignore_patterns`	[".DS_STORE/", "._", ".stfolder/", ".stversions/", ".localized/*", "desktop.ini"]	Y	Y
`paperless_ngx_conf_consumer_inotify_delay`	0.5	Y	Y
`paperless_ngx_conf_consumer_polling_delay`	5	Y	Y
`paperless_ngx_conf_consumer_polling_retry_count`	5	Y	Y
`paperless_ngx_conf_consumer_polling`	0	Y	Y
`paperless_ngx_conf_consumer_recursive`	false	Y	Y
`paperless_ngx_conf_consumer_subdirs_as_tags`	false	Y	Y
`paperless_ngx_conf_consumption_dir`	"{{ paperless_ngx_dir_runtime_data }}/consumption"	Y	Y
`paperless_ngx_conf_convert_binary`	convert	Y	Y
`paperless_ngx_conf_convert_memory_limit`	0	Y	Y
`paperless_ngx_conf_convert_tmpdir`	""	Y	Y
`paperless_ngx_conf_cookie_prefix`	""	Y	Y
`paperless_ngx_conf_cors_allowed_hosts`	http://localhost:8000	Y	Y
`paperless_ngx_conf_csrf_trusted_origins`		Y	Y
`paperless_ngx_conf_data_dir`	"{{ paperless_ngx_dir_runtime_data }}/data"	Y	Y
`paperless_ngx_conf_date_order`	"DMY"	Y	Y
`paperless_ngx_conf_db_timeout`		Y	Y
`paperless_ngx_conf_dbengine`		Y	N	Not used by the role
`paperless_ngx_conf_dbhost`	localhost	Y	Y
`paperless_ngx_conf_dbname`	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_dbport`	5432	Y	Y
`paperless_ngx_conf_dbsslmode`	prefer	Y	Y
`paperless_ngx_conf_dbuser`	paperlessngx	Y	Y
`paperless_ngx_conf_email_task_cron`	"/10 * * *"	Y	Y		1.12
`paperless_ngx_conf_enable_compression`	true	Y	Y		1.13
`paperless_ngx_conf_enable_flower`	false	Y	Y	Whether to start flower or not. See using flower for more information	1.10
`paperless_ngx_conf_enable_http_remote_user`	""	Y	Y
`paperless_ngx_conf_enable_nltk`	1	Y	Y		1.11
`paperless_ngx_conf_enable_update_check`		Y	Y	Will be removed in the future
`paperless_ngx_conf_filename_date_order`	""	Y	Y
`paperless_ngx_conf_filename_format_remove_none`	false	Y	Y
`paperless_ngx_conf_filename_format`	""	Y	Y
`paperless_ngx_conf_force_script_name`	""	Y	Y
`paperless_ngx_conf_gs_binary`	gs	Y	Y
`paperless_ngx_conf_http_remote_user_header_name`	HTTP_REMOTE_USER	Y	Y
`paperless_ngx_conf_ignore_dates`	""	Y	Y
`paperless_ngx_conf_index_task_cron`	"0 0 * * *"	Y	Y		1.12
`paperless_ngx_conf_logging_dir`	"{{ paperless_ngx_dir_runtime_data }}/log"
`paperless_ngx_conf_logout_redirect_url`		Y	Y
`paperless_ngx_conf_logrotate_max_backups`	20	Y	Y
`paperless_ngx_conf_logrotate_max_size`	1024 * 1024	Y	Y
`paperless_ngx_conf_media_root`	"{{ paperless_ngx_dir_runtime_data }}/media"	Y	Y
`paperless_ngx_conf_nltk_dir`	/usr/share/nltk_data	Y	Y		1.11
`paperless_ngx_conf_number_of_suggested_dates`	3	Y	Y
`paperless_ngx_conf_ocr_clean`	clean	Y	Y
`paperless_ngx_conf_ocr_deskew`	true	Y	Y
`paperless_ngx_conf_ocr_image_dpi`	""	Y	Y
`paperless_ngx_conf_ocr_language`	eng	Y	Y
`paperless_ngx_conf_ocr_languages`	[eng,deu,fra,ita,spa]	Y	Y
`paperless_ngx_conf_ocr_max_image_pixels`		Y	Y
`paperless_ngx_conf_ocr_mode`	skip	Y	Y
`paperless_ngx_conf_ocr_output_type`	pdfa	Y	Y
`paperless_ngx_conf_ocr_pages`	0	Y	Y
`paperless_ngx_conf_ocr_rotate_pages_threshold`	12	Y	Y
`paperless_ngx_conf_ocr_rotate_pages`	true	Y	Y
`paperless_ngx_conf_ocr_user_args`	[optimize=1]	Y	Y
`paperless_ngx_conf_port`	8000	Y	Y
`paperless_ngx_conf_post_consume_script`	""	Y	Y
`paperless_ngx_conf_pre_consume_script`	""	Y	Y
`paperless_ngx_conf_redis`	redis://{{ paperless_ngx_redis_host }}:{{ paperless_ngx_redis_port }}	Y	N
`paperless_ngx_conf_sanity_task_cron`	"30 0 * * sun"	Y	Y		1.12
`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_static_url`	/static/	Y	Y
`paperless_ngx_conf_staticdir`	../static	Y	N
`paperless_ngx_conf_task_workers`	1	Y	Y
`paperless_ngx_conf_threads_per_worker`	paperless_ngx_conf_task_workers	Y	Y
`paperless_ngx_conf_thumbnail_font_name`	/usr/share/fonts/liberation/LiberationSerif-Regular.ttf	Y	Y
`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
`paperless_ngx_conf_time_zone`	Europe/London	Y	Y
`paperless_ngx_conf_train_task_cron`	"5 /1 * *"	Y	Y		1.12
`paperless_ngx_conf_trash_dir`	"{{ paperless_ngx_dir_runtime_data }}/trash"	Y	Y
`paperless_ngx_conf_url`	http://localhost:8000	Y	Y
`paperless_ngx_conf_usermap_gid`		Y	Y	System users gid
`paperless_ngx_conf_usermap_uid`		Y	Y	System users id
`paperless_ngx_conf_webserver_workers`	1	Y	Y
`paperless_ngx_conf_worker_timeout`	1800	Y	Y

3. Usage advices

3.1. Updating Paperless-ngx

If you installed Paperless-ngx with the help of this role and you want to update to a newer version than all you have to do is to run this role again (if you chose latest as the version identifier). If you specified a specific version to install than all you need to do is to change this value to a newer one and run the role again.

This role will not update anything else than Paperless-ngx. So updates for the operating system and depended packages need to be handled seperately.

PLEASE THINK ABOUT BACKUPS before you upgrade.

3.2. Backup/Restore

Please be aware that this role does not offer any mechanism of backup or restore. This is intention. To seperate concerns this role is only focused towards 'deployments' of the software artifacts and its configuration. An example of a working backup strategy can be found here: Link to example backup strategy

3.3. 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

3.4. 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.

3.5. PostgreSQL usage

If you want to use Paperless-ngx together with PostgreSQL a running instance of PostgreSQL is required. This role does not automatically install such a database instance for you. However, here is you can read an example how to set up such an instance from scretch: Link to example playbook

4. Dependencies

No dependencies

5. Example Playbooks

minimal_runnable_playbook.yml:

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

6. Contributing

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

7. License

MIT

abbbi / ansible