Paperless ngx

README.md

@@ -73,7 +73,7 @@ If you have a spare domain name you can configure applications to be accessible
 * [openHAB](https://www.openhab.org/) - A vendor and technology agnostic open source automation software for your home
 * [Organizr](https://organizr.app/) - ORGANIZR aims to be your one stop shop for your Servers Frontend.
 * [overseerr](https://docs.overseerr.dev) - open source software application for managing requests for your media library
-* [Paperless_ng](https://github.com/jonaswinkler/paperless-ng) - Scan, index and archive all your physical documents
+* [paperless_ngx](https://docs.paperless-ngx.com/) - Scan, index and archive all your physical documents
 * [Piwigo](https://piwigo.org/) - Photo Gallery Software
 * [Plex](https://www.plex.tv/) - Plex Media Server
 * [Portainer](https://portainer.io/) - for managing Docker and running custom images

nas.yml

@@ -306,10 +306,10 @@
         - overseerr
       when: (overseerr_enabled | default(False))
 
-    - role: paperless_ng
+    - role: paperless_ngx
       tags:
-        - paperless_ng
-      when: (paperless_ng_enabled | default(False))
+        - paperless_ngx
+
 
     - role: piwigo
       tags:

roles/paperless_ngx/defaults/main.yml

@@ -0,0 +1,66 @@
+---
+paperless_ngx_enabled: false
+paperless_ngx_available_externally: false
+# !!IMPORTANT!!
+# when **enabling** traefik set the secret key to a long random string; you don't have to remember it.
+# If not set, default value(which is well known) will be used
+# user for example https://numbergenerator.org/randomnumbergenerator/ascii
+# or
+# https://numbergenerator.org/hex-code-generator#!numbers=1&length=128&addfilters=
+paperless_ngx_secret_key: "very_long-string!-09skjlOJIOKSN-ofrandonm-charcters!_?"
+
+# admin user: override these values to automatically create an admin user
+# This will not change an existing [super]user's password, nor will it recreate a user that already exists.
+# You can leave this throughout the lifecycle of the containers.
+paperless_ngx_admin_user: ""
+paperless_ngx_admin_password: ""
+paperless_ngx_admin_mail: ""
+
+
+# directories
+paperless_ngx_config_directory: "{{ docker_home }}/paperless_ngx"
+paperless_ngx_files_directory: "{{ documents_root }}/paperless"
+paperless_ngx_postgres_directory: "{{ paperless_ngx_config_directory }}/postgres"
+paperless_ngx_data_directory: "{{ paperless_ngx_config_directory }}/data"
+paperless_ngx_export_directory: "{{ paperless_ngx_config_directory }}/export"
+paperless_ngx_media_directory: "{{ paperless_ngx_files_directory }}/media"
+paperless_ngx_consume_directory: "{{ paperless_ngx_files_directory }}/consume"
+
+# network
+paperless_ngx_port: "16922"
+paperless_ngx_hostname: "paperless"
+
+# postgres
+paperless_ngx_postgres_db: "paperless"
+paperless_ngx_postgres_user: "paperless"
+paperless_ngx_postgres_password: "paperless"
+
+# mariadb
+# mariadb is not an option yet
+# MARIADB_HOST: paperless
+# MARIADB_DATABASE: paperless
+# MARIADB_USER: paperless
+# MARIADB_PASSWORD: paperless
+# MARIADB_ROOT_PASSWORD: paperless
+
+# container names
+paperless_ngx_container_network_name: "paperless_ngx_network"
+paperless_ngx_container_name_redis: "paperless_ngx_redis"
+paperless_ngx_container_name_postgres: "paperless_ngx_postgres"
+paperless_ngx_container_name_gotenberg: "paperless_ngx_gotenberg"
+paperless_ngx_container_name_tika: "paperless_ngx_tika"
+paperless_ngx_container_name_uiserver: "paperless_ngx_uiserver"
+
+# uid/guid
+paperless_ngx_user_id: "1000"
+paperless_ngx_group_id: "1000"
+
+# settings
+paperless_ngx_languages: "eng"
+
+# specs
+paperless_ngx_ui_memory: 1g
+paperless_ngx_postgres_memory: 1g
+paperless_ngx_redis_memory: 1g
+paperless_ngx_tika_memory: 0
+paperless_ngx_gotenberg_memory: 1g

roles/paperless_ngx/docs/paperless_ngx.md

@@ -0,0 +1,55 @@
+---
+title: "Paperless-ngx"
+---
+
+Homepage: <https://docs.paperless-ngx.com/>
+
+Paperless is an application by Daniel Quinn and [contributors](https://github.com/paperless-ngx/paperless-ngx/graphs/contributors) that indexes your scanned documents and allows you to easily search for documents and store metadata alongside your documents.
+
+Paperless-ngx has been actively developed for years (stand Feb. 2023) and is a fork of paperless-ng, which was archived since January 2023, which itself forked the original project, adding a new interface and many other changes under the hood
+
+## Usage
+
+Set `paperless_ngx_enabled: true` in your `inventories/<your_inventory>/nas.yml` file.
+
+The paperless-ngx web interface can be found at <http://ansible_nas_host_or_ip:16922>.
+
+### Enable traefik as proxy
+
+- Set `paperless_ngx_available_externally: true` and
+
+- Set `paperless_ngx_secret_key: "to a very_long  string!-09skjlOJIOKSN-of randonm-charcters !_?"`
+in your `inventories/<your_inventory>/nas.yml` file.
+
+You don't have to remember `paperless_ngx_secret_key` and you can leave it set if you run the playbook again. **Don't** leave it empty, because this value is known from the source code. You can use <https://numbergenerator.org/hex-code-generator#!numbers=1&length=128&addfilters=> to generate a long random string
+
+**Exposing paperless with sensible data to the Internet is dangerous. Use strong passwords.**
+
+### Create superuser
+
+To be able to login, you will need a super user.
+
+#### 1. Set superuser and password in playbook
+
+- override these values in your `inventories/<your_inventory>/nas.yml` file to automatically create an admin user
+
+```yml
+paperless_ngx_admin_user: ""
+paperless_ngx_admin_password: ""
+paperless_ngx_admin_mail: ""
+```
+
+- This will not change an existing [super]user's password, nor will it recreate a user that already exists.
+
+- You can leave this throughout the lifecycle of the containers.
+
+#### 2. Alternatively: Create the superuser from the command line
+
+To create it, execute the following command:
+
+```bash
+docker exec -it paperless_ngx_uiserver python manage.py createsuperuser
+```
+replace `paperless_ngx_uiserver` with the name you set in `main.yml`
+
+This will prompt you to set a username, an optional e-mail address and finally a password (at least 8 characters).

roles/paperless_ngx/molecule/default/molecule.yml

@@ -0,0 +1,6 @@
+---
+provisioner:
+  inventory:
+    group_vars:
+      all:
+        paperless_ngx_enabled: true

roles/paperless_ngx/molecule/default/side_effect.yml

@@ -0,0 +1,10 @@
+---
+- name: Stop
+  hosts: all
+  become: true
+  tasks:
+    - name: "Include {{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') | basename }} role"
+      include_role:
+        name: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') | basename }}"
+      vars:
+        paperless_ngx_enabled: false

roles/paperless_ngx/molecule/default/verify.yml

@@ -0,0 +1,61 @@
+---
+# This is an example playbook to execute Ansible tests.
+
+- name: Verify
+  hosts: all
+  gather_facts: false
+  tasks:
+    - name: Include vars
+      include_vars:
+        file: ../../defaults/main.yml
+
+    # 1. webserver
+    - name: Get container state for paperless_ngx webserver
+      docker_container:
+        name: "{{ paperless_ngx_container_name_uiserver }}"
+      register: result_webserver
+
+    # 2. tika
+    - name: Get container state for paperless_ngx tika
+      docker_container:
+        name: "{{ paperless_ngx_container_name_tika }}"
+      register: result_tika
+
+    # 3. gotenberg
+    - name: Get container state for paperless_ngx gotenberg
+      docker_container:
+        name: "{{ paperless_ngx_container_name_gotenberg }}"
+      register: result_gotenberg
+
+    # 4. Postgres database
+    - name: Get container state for paperless_ngx postgres
+      docker_container:
+        name: "{{ paperless_ngx_container_name_postgres }}"
+      register: result_postgres
+
+    # 5. paperless_ngx redis broker
+    - name: Get container state for paperless_ngx redis broker
+      docker_container:
+        name: "{{ paperless_ngx_container_name_redis }}"
+      register: result_redis
+
+    # 6. Docker network for paperless_ngx
+    - name: Get paperless_ngx network status
+      docker_network_info:
+        name: "{{ paperless_ngx_container_network_name }}"
+      register: result_network
+
+    - name: Check if all paperless_ngx containers are running and network was created
+      assert:
+        that:
+          - result_webserver.container['State']['Status'] == "running"
+          - result_webserver.container['State']['Restarting'] == false
+          - result_tika.container['State']['Status'] == "running"
+          - result_tika.container['State']['Restarting'] == false
+          - result_gotenberg.container['State']['Status'] == "running"
+          - result_gotenberg.container['State']['Restarting'] == false
+          - result_postgres.container['State']['Status'] == "running"
+          - result_postgres.container['State']['Restarting'] == false
+          - result_redis.container['State']['Status'] == "running"
+          - result_redis.container['State']['Restarting'] == false
+          - result_network.exists == true

roles/paperless_ngx/molecule/default/verify_stopped.yml

@@ -0,0 +1,61 @@
+---
+# This is a playbook for paperless_ngx to execute Ansible tests.
+
+- name: Verify
+  hosts: all
+  gather_facts: false
+  tasks:
+    - name: Include vars
+      include_vars:
+        file: ../../defaults/main.yml
+
+    # 1. webserver
+    - name: Try and stop paperless_ngx webserver
+      docker_container:
+        name: "{{ paperless_ngx_container_name_uiserver }}"
+        state: absent
+      register: result_webserver
+
+    # 2. tika
+    - name: Try and stop paperless_ngx tika Docker container
+      docker_container:
+        name: "{{ paperless_ngx_container_name_tika }}"
+        state: absent
+      register: result_tika
+
+    # 3. gotenberg
+    - name: Try and stop paperless_ngx gotenberg Docker Container
+      docker_container:
+        name: "{{ paperless_ngx_container_name_gotenberg }}"
+        state: absent
+      register: result_gotenberg
+
+    # 4. Postgres database
+    - name: Try and stop paperless_ngx postgres Docker Container
+      docker_container:
+        name: "{{ paperless_ngx_container_name_postgres }}"
+        state: absent
+      register: result_postgres
+
+    # 5. paperless_ngx redis broker
+    - name: Try and stop paperless_ngx redis broker
+      docker_container:
+        name: "{{ paperless_ngx_container_name_redis }}"
+        state: absent
+      register: result_redis
+
+    # 6. Docker network for paperless_ngx
+    - name: Try and remove paperless_ngx network
+      docker_network_info:
+        name: "{{ paperless_ngx_container_network_name }}"
+      register: result_network
+
+    - name: Check paperless_ngx containers and network are stopped
+      assert:
+        that:
+          - not result_webserver.changed
+          - not result_tika.changed
+          - not result_gotenberg.changed
+          - not result_postgres.changed
+          - not result_redis.changed
+          - not result_network.exists