mash-playbook/docs/services/paperless-ngx.md

# Paperless-ngx

[Paperless-ngx](https://paperless-ngx.com) s a community-supported open-source document management system that transforms your physical documents into a searchable online archive so you can keep, well, less paper. MASH can install paperless-ngx with the [`mother-of-all-self-hosting/ansible-role-paperless`](https://github.com/mother-of-all-self-hosting/ansible-role-paperless) ansible role.


## Dependencies

This service requires the following other services:

- a [Postgres](postgres.md) database
- a [KeyDB](keydb.md) data-store, installation details [below](#keydb)
- a [Traefik](traefik.md) reverse-proxy server


## Configuration

To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process:

```yaml
########################################################################
#                                                                      #
# paperless                                                            #
#                                                                      #
########################################################################

paperless_enabled: true

paperless_hostname: paperless.example.org

# KeyDB configuration, as described below

########################################################################
#                                                                      #
# /paperless                                                           #
#                                                                      #
########################################################################
```

### KeyDB

As described on the [KeyDB](keydb.md) documentation page, if you're hosting additional services which require KeyDB on the same server, you'd better go for installing a separate KeyDB instance for each service. See [Creating a KeyDB instance dedicated to paperless-ngx](#creating-a-keydb-instance-dedicated-to-paperless-ngx).

If you're only running paperless-ngx on this server and don't need to use KeyDB for anything else, you can [use a single KeyDB instance](#using-the-shared-keydb-instance-for-authentik).

#### Using the shared KeyDB instance for authentik

To install a single (non-dedicated) KeyDB instance (`mash-keydb`) and hook paperless to it, add the following **additional** configuration:

```yaml
########################################################################
#                                                                      #
# keydb                                                                #
#                                                                      #
########################################################################

keydb_enabled: true

########################################################################
#                                                                      #
# /keydb                                                               #
#                                                                      #
########################################################################


########################################################################
#                                                                      #
# paperless                                                            #
#                                                                      #
########################################################################

# Base configuration as shown above

# Point paperless to the shared KeyDB instance
paperless_redis_hostname: "{{ keydb_identifier }}"

# Make sure the authentik service (mash-authentik.service) starts after the shared KeyDB service (mash-keydb.service)
paperless_systemd_required_services_list_custom:
  - "{{ keydb_identifier }}.service"

# Make sure the authentik container is connected to the container network of the shared KeyDB service (mash-keydb)
paperless_container_additional_networks_custom:
  - "{{ keydb_identifier }}"

########################################################################
#                                                                      #
# /paperless                                                           #
#                                                                      #
########################################################################
```

This will create a `mash-keydb` KeyDB instance on this host.

This is only recommended if you won't be installing other services which require KeyDB. Alternatively, go for [Creating a KeyDB instance dedicated to paperless-ngx](#creating-a-keydb-instance-dedicated-to-paperless-ngx).


#### Creating a KeyDB instance dedicated to paperless

The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation.

Adjust your `inventory/hosts` file as described in [Re-do your inventory to add supplementary hosts](../running-multiple-instances.md#re-do-your-inventory-to-add-supplementary-hosts), adding a new supplementary host (e.g. if `paperless.example.org` is your main one, create `paperless.example.org-deps`).

Then, create a new `vars.yml` file for the

`inventory/host_vars/paperless.example.org-deps/vars.yml`:

```yaml
---

########################################################################
#                                                                      #
# Playbook                                                             #
#                                                                      #
########################################################################

# Put a strong secret below, generated with `pwgen -s 64 1` or in another way
# Various other secrets will be derived from this secret automatically.
mash_playbook_generic_secret_key: ''

# Override service names and directory path prefixes
mash_playbook_service_identifier_prefix: 'mash-paperless-'
mash_playbook_service_base_directory_name_prefix: 'paperless-'

########################################################################
#                                                                      #
# /Playbook                                                            #
#                                                                      #
########################################################################


########################################################################
#                                                                      #
# keydb                                                                #
#                                                                      #
########################################################################

keydb_enabled: true

########################################################################
#                                                                      #
# /keydb                                                               #
#                                                                      #
########################################################################
```

This will create a `mash-paperless-keydb` instance on this host with its data in `/mash/paperless-keydb`.

Then, adjust your main inventory host's variables file (`inventory/host_vars/paperless.example.org/vars.yml`) like this:

```yaml
########################################################################
#                                                                      #
# paperless                                                            #
#                                                                      #
########################################################################

# Base configuration as shown above

# Point authentik to its dedicated KeyDB instance
paperless_redis_hostname: mash-authentik-keydb

# Make sure the authentik service (mash-paperless.service) starts after its dedicated KeyDB service (mash-paperless-keydb.service)
paperless_systemd_required_services_list_custom:
  - "mash-paperless-keydb.service"

# Make sure the authentik container is connected to the container network of its dedicated KeyDB service (mash-paperless-keydb)
authentik_container_additional_networks_custom:
  - "mash-paperless-keydb"

########################################################################
#                                                                      #
# /paperless                                                           #
#                                                                      #
########################################################################
```


## Installation

If you've decided to install a dedicated KeyDB instance for paperless, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `paperless.example.org-deps`), before running installation for the main one (e.g. `paperless.example.org`).


## Usage

Access your instance in your browser at `https://paperless.example.org`

Refer to the [official documentation](https://docs.paperless-ngx.com/) to learn how to use paperless.
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00			`# Paperless-ngx`

			[Paperless-ngx](https://paperless-ngx.com) s a community-supported open-source document management system that transforms your physical documents into a searchable online archive so you can keep, well, less paper. MASH can install paperless-ngx with the [`mother-of-all-self-hosting/ansible-role-paperless`](https://github.com/mother-of-all-self-hosting/ansible-role-paperless) ansible role.


			`## Dependencies`

			`This service requires the following other services:`

			`- a [Postgres](postgres.md) database`
			`- a [KeyDB](keydb.md) data-store, installation details [below](#keydb)`
			`- a [Traefik](traefik.md) reverse-proxy server`


			`## Configuration`

			To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process:

			```yaml
			`########################################################################`
			`# #`
docs: expand 2024-04-30 08:13:48 +02:00			`# paperless #`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00			`# #`
			`########################################################################`

docs: expand 2024-04-30 08:13:48 +02:00			`paperless_enabled: true`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
docs: expand 2024-04-30 08:13:48 +02:00			`paperless_hostname: paperless.example.org`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
			`# KeyDB configuration, as described below`

			`########################################################################`
			`# #`
docs: expand 2024-04-30 08:13:48 +02:00			`# /paperless #`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00			`# #`
			`########################################################################`
			```

			`### KeyDB`

			`As described on the [KeyDB](keydb.md) documentation page, if you're hosting additional services which require KeyDB on the same server, you'd better go for installing a separate KeyDB instance for each service. See [Creating a KeyDB instance dedicated to paperless-ngx](#creating-a-keydb-instance-dedicated-to-paperless-ngx).`

docs: expand 2024-04-30 08:13:48 +02:00			`If you're only running paperless-ngx on this server and don't need to use KeyDB for anything else, you can [use a single KeyDB instance](#using-the-shared-keydb-instance-for-authentik).`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
			`#### Using the shared KeyDB instance for authentik`

docs: expand 2024-04-30 08:13:48 +02:00			To install a single (non-dedicated) KeyDB instance (`mash-keydb`) and hook paperless to it, add the following additional configuration:
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
			```yaml
			`########################################################################`
			`# #`
			`# keydb #`
			`# #`
			`########################################################################`

			`keydb_enabled: true`

			`########################################################################`
			`# #`
			`# /keydb #`
			`# #`
			`########################################################################`


			`########################################################################`
			`# #`
docs: expand 2024-04-30 08:13:48 +02:00			`# paperless #`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00			`# #`
			`########################################################################`

			`# Base configuration as shown above`

docs: expand 2024-04-30 08:13:48 +02:00			`# Point paperless to the shared KeyDB instance`
			`paperless_redis_hostname: "{{ keydb_identifier }}"`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
			`# Make sure the authentik service (mash-authentik.service) starts after the shared KeyDB service (mash-keydb.service)`
docs: expand 2024-04-30 08:13:48 +02:00			`paperless_systemd_required_services_list_custom:`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00			`- "{{ keydb_identifier }}.service"`

			`# Make sure the authentik container is connected to the container network of the shared KeyDB service (mash-keydb)`
docs: expand 2024-04-30 08:13:48 +02:00			`paperless_container_additional_networks_custom:`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00			`- "{{ keydb_identifier }}"`

			`########################################################################`
			`# #`
docs: expand 2024-04-30 08:13:48 +02:00			`# /paperless #`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00			`# #`
			`########################################################################`
			```

			This will create a `mash-keydb` KeyDB instance on this host.

docs: expand 2024-04-30 08:13:48 +02:00			`This is only recommended if you won't be installing other services which require KeyDB. Alternatively, go for [Creating a KeyDB instance dedicated to paperless-ngx](#creating-a-keydb-instance-dedicated-to-paperless-ngx).`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00

docs: expand 2024-04-30 08:13:48 +02:00			`#### Creating a KeyDB instance dedicated to paperless`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
			`The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation.`

docs: expand 2024-04-30 08:13:48 +02:00			Adjust your `inventory/hosts` file as described in [Re-do your inventory to add supplementary hosts](../running-multiple-instances.md#re-do-your-inventory-to-add-supplementary-hosts), adding a new supplementary host (e.g. if `paperless.example.org` is your main one, create `paperless.example.org-deps`).
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
			Then, create a new `vars.yml` file for the

docs: expand 2024-04-30 08:13:48 +02:00			`inventory/host_vars/paperless.example.org-deps/vars.yml`:
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
			```yaml
			`---`

			`########################################################################`
			`# #`
			`# Playbook #`
			`# #`
			`########################################################################`

			# Put a strong secret below, generated with `pwgen -s 64 1` or in another way
			`# Various other secrets will be derived from this secret automatically.`
			`mash_playbook_generic_secret_key: ''`

			`# Override service names and directory path prefixes`
docs: expand 2024-04-30 08:13:48 +02:00			`mash_playbook_service_identifier_prefix: 'mash-paperless-'`
			`mash_playbook_service_base_directory_name_prefix: 'paperless-'`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
			`########################################################################`
			`# #`
			`# /Playbook #`
			`# #`
			`########################################################################`


			`########################################################################`
			`# #`
			`# keydb #`
			`# #`
			`########################################################################`

			`keydb_enabled: true`

			`########################################################################`
			`# #`
			`# /keydb #`
			`# #`
			`########################################################################`
			```

docs: expand 2024-04-30 08:13:48 +02:00			This will create a `mash-paperless-keydb` instance on this host with its data in `/mash/paperless-keydb`.
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
docs: expand 2024-04-30 08:13:48 +02:00			Then, adjust your main inventory host's variables file (`inventory/host_vars/paperless.example.org/vars.yml`) like this:
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
			```yaml
			`########################################################################`
			`# #`
docs: expand 2024-04-30 08:13:48 +02:00			`# paperless #`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00			`# #`
			`########################################################################`

			`# Base configuration as shown above`

			`# Point authentik to its dedicated KeyDB instance`
docs: expand 2024-04-30 08:13:48 +02:00			`paperless_redis_hostname: mash-authentik-keydb`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
docs: expand 2024-04-30 08:13:48 +02:00			`# Make sure the authentik service (mash-paperless.service) starts after its dedicated KeyDB service (mash-paperless-keydb.service)`
			`paperless_systemd_required_services_list_custom:`
			`- "mash-paperless-keydb.service"`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
docs: expand 2024-04-30 08:13:48 +02:00			`# Make sure the authentik container is connected to the container network of its dedicated KeyDB service (mash-paperless-keydb)`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00			`authentik_container_additional_networks_custom:`
docs: expand 2024-04-30 08:13:48 +02:00			`- "mash-paperless-keydb"`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00
			`########################################################################`
			`# #`
docs: expand 2024-04-30 08:13:48 +02:00			`# /paperless #`
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00			`# #`
			`########################################################################`
			```


			`## Installation`

docs: expand 2024-04-30 08:13:48 +02:00			If you've decided to install a dedicated KeyDB instance for paperless, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `paperless.example.org-deps`), before running installation for the main one (e.g. `paperless.example.org`).
docs(paperless): Start with paperless documentation 2024-04-29 23:56:29 +02:00

			`## Usage`

			Access your instance in your browser at `https://paperless.example.org`

docs: expand 2024-04-30 08:13:48 +02:00			`Refer to the [official documentation](https://docs.paperless-ngx.com/) to learn how to use paperless.`