Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Paperless ngx #652

Open
wants to merge 15 commits into
base: main
Choose a base branch
from
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions nas.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
39 changes: 0 additions & 39 deletions roles/paperless_ng/defaults/main.yml

This file was deleted.

67 changes: 0 additions & 67 deletions roles/paperless_ng/tasks/main.yml

This file was deleted.

66 changes: 66 additions & 0 deletions roles/paperless_ngx/defaults/main.yml
viktor-c marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -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
55 changes: 55 additions & 0 deletions roles/paperless_ngx/docs/paperless_ngx.md
Original file line number Diff line number Diff line change
@@ -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).
6 changes: 6 additions & 0 deletions roles/paperless_ngx/molecule/default/molecule.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
provisioner:
inventory:
group_vars:
all:
paperless_ngx_enabled: true
10 changes: 10 additions & 0 deletions roles/paperless_ngx/molecule/default/side_effect.yml
Original file line number Diff line number Diff line change
@@ -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
61 changes: 61 additions & 0 deletions roles/paperless_ngx/molecule/default/verify.yml
Original file line number Diff line number Diff line change
@@ -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
61 changes: 61 additions & 0 deletions roles/paperless_ngx/molecule/default/verify_stopped.yml
Original file line number Diff line number Diff line change
@@ -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
Loading