Status	Event
	Weekly schedule
	Last PR

Ansible Role: paperless_ngx

This role installs and sets up the paperless-ngx Electronic Document Management System (EDMS).

Contents

• 1. Requirements
  • 1.1. Ansible
  • 1.2. Supported OS
• 2. Role Variables
  • 2.1. Specific Variables
  • 2.2. Configuration Variables
• 3. Usage Tips
  • 3.1. Updating Paperless-ngx
  • 3.2. Backup/Restore
  • 3.3. Generated Password
  • 3.4. Data Separation
  • 3.5. PostgreSQL Use
• 4. Dependencies
• 5. Example Playbooks
• 6. Contributing
• 7. License

1. Requirements

1.1. Ansible

You need at least version 2.12 of Ansible.

Install the following Ansible collections using ansible-galaxy collection install:

• community.general
• ansible.posix

1.2. Supported Operating Systems

• Debian (version 11 or higher)
• Ubuntu (version focal or higher)

2. Role Variables

Most configuration options from paperless-ngx are available and can be modified. Variables starting with PAPERLESS_* are changed to paperless_ngx_conf_* in defaults/main.yml.

For a complete list and explanations, refer to the documentation.

The variables are split into:

• Role-specific variables
• Original paperless-ngx configuration variables

2.1. Role Specific Variables

Name	Default Value	Description
paperless_ngx_db_type	sqlite	Choose between sqlite or postgresql. If postgresql is used, configure the other db variables as well.
paperless_ngx_dependency_install_tmp_dir	/tmp/	Directory for temporary installation files
paperless_ngx_dir_installation	/opt/paperless-ngx	Directory for static installation files.
paperless_ngx_dir_runtime_data	/var/lib/paperless-ngx	Directory for runtime data.
paperless_ngx_system_user	paperlessngx	User that runs the services and owns the data.
paperless_ngx_version	latest	Software version to install. Use latest or specify a version like 2.0.0.

2.2. Paperless-ngx Configuration Variables

All upcoming variables relate to the paperless-ngx docs and are categorized for easy maintenance.

Name	Default Value	Implemented	Overridden	Hint	Version
paperless_ngx_conf_account_allow_signups	false	Y	Y		2.5
paperless_ngx_conf_admin_mail	root@localhost	Y	Y
paperless_ngx_conf_port	8000	Y	Y
paperless_ngx_conf_secret_key	""	Y	Y	A random password will be generated if not defined.

3. Usage Tips

3.1. Updating Paperless-ngx

To update paperless-ngx, just run the role again. If you chose latest, it’ll get the latest version. Remember to back up your data before updating.

3.2. Backup/Restore

This role does not manage backups or restores—it's focused only on deployment and configuration. For backup strategies, you can refer to this example backup strategy.

3.3. Generated Password

If a password is generated, it's stored locally in pngx_instances/{{ inventory_hostname }}/. If the file exists, it will reuse that password.

3.4. Data Separation

This role ensures that dynamic data directories are not placed within the installation path, preventing unwanted data loss during upgrades.

3.5. PostgreSQL Use

If using PostgreSQL with paperless-ngx, you need to have a running PostgreSQL instance set up separately. Check this example playbook for guidance.

4. Dependencies

No dependencies are required.

5. Example Playbooks

Here's a minimal playbook example:

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

6. Contributing

We welcome contributions! Please see the contributing guide for details on how to proceed.

7. License

This project is licensed under the MIT License.