Merge pull request #198 from mother-of-all-self-hosting/paperless

Add paperless-ngx

VERSIONS.md

@@ -55,6 +55,7 @@
 * Outline: 0.74.0-0
 * Owncast: 0.1.2
 * Oxitraffic: 0.9.0
+* Paperless: 2.7.2
 * Peertube: v6.0.4
 * Prometheus: v2.51.2
 * Prometheus Blackbox Exporter: v0.25.0

docs/services/paperless-ngx.md

@@ -0,0 +1,192 @@
+# 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.
+
+**Warning** Paperless-ngx currently [does not support](https://github.com/paperless-ngx/paperless-ngx/issues/6352) running the container rootless, therefore the role has not the usual security features of other services provided by this playbook. This put your system more at higher risk as vulnerabilities can have a higher impact.
+
+## 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
+
+# Set the following variables to create an initial admin user
+# It will not re-create an admin user, it will not change a password if the user is already created
+# paperless_admin_user: USERNAME
+# paperless_admin_password: SECURE_PASSWORD
+
+# 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-paperless).
+
+#### Using the shared KeyDB instance for paperless-ngx
+
+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 paperless service (mash-paperless.service) starts after the shared KeyDB service (mash-keydb.service)
+paperless_systemd_required_services_list_custom:
+  - "{{ keydb_identifier }}.service"
+
+# Make sure the paperless 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 paperless to its dedicated KeyDB instance
+paperless_redis_hostname: mash-paperless-keydb
+
+# Make sure the paperless 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 paperless container is connected to the container network of its dedicated KeyDB service (mash-paperless-keydb)
+paperless_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/supported-services.md

@@ -54,6 +54,7 @@
 | [OAuth2-Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) | A reverse proxy and static file server that provides authentication using OpenID Connect Providers (Google, GitHub, [Keycloak](services/keycloak.md), and others) to SSO-protect services which do not support SSO natively. | [Link](services/oauth2-proxy.md) |
 | [Owncast](https://owncast.online/) | Owncast is a free and open source live video and web chat server for use with existing popular broadcasting software. | [Link](services/owncast.md) |
 | [OxiTraffic](https://codeberg.org/mo8it/oxitraffic) | [OxiTraffic](https://codeberg.org/mo8it/oxitraffic) is a self-hosted, simple and privacy respecting website traffic tracker. | [Link](services/oxitraffic.md) |
+| [Paperless-ngx](https://paperless-ngx.com) | [Paperless-ngx](https://paperless-ngx.com) is 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. | [Link](services/paperless-ngx.md) |
 | [PeerTube](https://joinpeertube.org/) | A tool for sharing online videos | [Link](services/peertube.md) |
 | [Postgis](https://postgis.net/) | A spatial database extender for PostgreSQL object-relational database | [Link](services/postgis.md) |
 | [Postgres](https://www.postgresql.org) | A powerful, open source object-relational database system | [Link](services/postgres.md) |

templates/group_vars_mash_servers

@@ -463,6 +463,11 @@ mash_playbook_devture_systemd_service_manager_services_list_auto_itemized:
     {{ ({'name': (oxitraffic_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'oxitraffic']} if oxitraffic_enabled else omit) }}
   # /role-specific:oxitraffic
 
+  # role-specific:paperless
+  - |-
+    {{ ({'name': (paperless_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'paperless']} if paperless_enabled else omit) }}
+  # /role-specific:paperless
+
   # role-specific:peertube
   - |-
     {{ ({'name': (peertube_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'peertube']} if peertube_enabled else omit) }}
@@ -841,6 +846,18 @@ mash_playbook_devture_postgres_managed_databases_auto_itemized:
     }}
   # /role-specific:oxitraffic
 
+
+  # role-specific:paperless
+  - |-
+    {{
+      ({
+        'name': paperless_database_name,
+        'username': paperless_database_username,
+        'password': paperless_database_password,
+      } if paperless_enabled and paperless_database_hostname == devture_postgres_identifier else omit)
+    }}
+  # /role-specific:paperless
+
   # role-specific:peertube
   - |-
     {{
@@ -3955,6 +3972,54 @@ oxitraffic_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certRe
 # /role-specific:oxitraffic
 
 
+# role-specific:paperless
+########################################################################
+#                                                                      #
+# paperless                                                            #
+#                                                                      #
+########################################################################
+
+paperless_enabled: false
+
+paperless_identifier: "{{ mash_playbook_service_identifier_prefix }}paperless"
+
+paperless_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base_directory_name_prefix }}paperless"
+
+paperless_uid: "{{ mash_playbook_uid }}"
+paperless_gid: "{{ mash_playbook_gid }}"
+
+paperless_database_hostname: "{{ devture_postgres_identifier if devture_postgres_enabled else '' }}"
+paperless_database_username: "paperless"
+paperless_database_port: "{{ '5432' if devture_postgres_enabled else '' }}"
+paperless_database_password: "{{ '%s' | format(mash_playbook_generic_secret_key) | password_hash('sha512', 'db.paperless', rounds=655555) | to_uuid }}"
+
+paperless_systemd_required_services_list: |
+  {{
+    (['docker.service'])
+    +
+    ([devture_postgres_identifier ~ '.service'] if devture_postgres_enabled and paperless_database_hostname == devture_postgres_identifier else [])
+  }}
+
+paperless_container_additional_networks_auto: |
+  {{
+    ([mash_playbook_reverse_proxyable_services_additional_network] if mash_playbook_reverse_proxyable_services_additional_network else [])
+    +
+    ([devture_postgres_container_network] if devture_postgres_enabled and paperless_database_hostname == devture_postgres_identifier and paperless_container_network != devture_postgres_container_network else [])
+  }}
+
+paperless_container_labels_traefik_enabled: "{{ mash_playbook_traefik_labels_enabled }}"
+paperless_container_labels_traefik_docker_network: "{{ mash_playbook_reverse_proxyable_services_additional_network }}"
+paperless_container_labels_traefik_entrypoints: "{{ devture_traefik_entrypoint_primary }}"
+paperless_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolver_primary }}"
+
+########################################################################
+#                                                                      #
+# /paperless                                                           #
+#                                                                      #
+########################################################################
+# /role-specific:paperless
+
+
 
 # role-specific:peertube
 ########################################################################

templates/requirements.yml

@@ -228,6 +228,9 @@
   version: v0.9.0-0
   name: oxitraffic
   activation_prefix: oxitraffic_
+- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-paperless.git
+  version: v2.7.2-1
+  name: paperless
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-peertube.git
   version: v6.0.4-0
   name: peertube

templates/setup.yml

@@ -290,6 +290,10 @@
     - role: galaxy/oxitraffic
     # /role-specific:oxitraffic
 
+    # role-specific:paperless
+    - role: galaxy/paperless
+    # /role-specific:paperless
+
     # role-specific:peertube
     - role: galaxy/peertube
     # /role-specific:peertube