paperless: Improve documentation

ansible/roles/paperless/handlers/main.yml

@@ -1,2 +0,0 @@
----
-# handlers file for paperless

ansible/roles/paperless/vars/main.yml

@@ -1,2 +0,0 @@
----
-# vars file for paperless

arr/arr.yml

@@ -1,172 +0,0 @@
-version: "3"
-services:
-  sonarr:
-    container_name: sonarr
-    image: lscr.io/linuxserver/sonarr:latest
-    ports:
-      - 8989:8989
-    environment:
-      - PUID=${PUID}
-      - PGID=${PGID}
-      - UMASK_SET=022
-      - TZ=${TZ}
-    volumes:
-      - "./config/sonarr:/config"
-      - "CHANGE_TO_COMPOSE_DATA_PATH:/data"
-    restart: unless-stopped
-  radarr:
-    container_name: radarr
-    image: lscr.io/linuxserver/radarr:latest
-    ports:
-      - 7878:7878
-    environment:
-      - PUID=${PUID}
-      - PGID=${PGID}
-      - UMASK_SET=022
-      - TZ=${TZ}
-    volumes:
-      - "./config/radarr:/config"
-      - "CHANGE_TO_COMPOSE_DATA_PATH:/data"
-    restart: unless-stopped
-  lidarr:
-    container_name: lidarr
-    image: lscr.io/linuxserver/lidarr:latest
-    ports:
-      - 8686:8686
-    environment:
-      - PUID=${PUID}
-      - PGID=${PGID}
-      - UMASK_SET=022
-      - TZ=${TZ}
-      - DOCKER_MODS=linuxserver/mods:universal-docker
-    volumes:
-      - "./config/lidarr:/config"
-      - "CHANGE_TO_COMPOSE_DATA_PATH:/data"
-      - "/var/run/docker.sock:/var/run/docker.sock:ro"
-    restart: unless-stopped
-  readarr:
-    container_name: readarr
-    image: lscr.io/linuxserver/readarr:develop
-    ports:
-      - 8787:8787
-    environment:
-      - PUID=${PUID}
-      - PGID=${PGID}
-      - UMASK_SET=022
-      - TZ=${TZ}
-    volumes:
-      - "./config/readarr:/config"
-      - "CHANGE_TO_COMPOSE_DATA_PATH:/data"
-    restart: unless-stopped
-  prowlarr:
-    container_name: prowlarr
-    image: lscr.io/linuxserver/prowlarr:develop
-    environment:
-      - PUID=${PUID}
-      - PGID=${PGID}
-      - UMASK_SET=022
-      - TZ=${TZ}
-    volumes:
-      - "./config/prowlarr:/config"
-    ports:
-      - 9696:9696
-    restart: unless-stopped
-  sabnzbd:
-    container_name: sabnzbd
-    image: lscr.io/linuxserver/sabnzbd:latest
-    environment:
-      - PUID=${PUID}
-      - PGID=${PGID}
-      - TZ=${TZ}
-    volumes:
-      - "./config/sabnzbd:/config"
-      - "CHANGE_TO_COMPOSE_DATA_PATH/usenet:/data/usenet:rw"
-    ports:
-      - 8080:8080
-    restart: unless-stopped
-  pia-qbittorrent:
-    image: j4ym0/pia-qbittorrent
-    container_name: pia-qbittorrent
-    cap_add:
-      - NET_ADMIN
-    environment:
-      - UID=${PUID}
-      - GID=${PGID}
-      - TZ=${TZ}
-      - REGION=Netherlands
-      - USER=${PIA_USER}
-      - PASSWORD=${PIA_PASS}
-    volumes:
-      - "./config/piaqbit:/config"
-      - "CHANGE_TO_COMPOSE_DATA_PATH/torrent:/downloads:rw"
-    ports:
-      - "8888:8888"
-    restart: unless-stopped
-  jellyfin:
-    image: lscr.io/linuxserver/jellyfin:latest
-    container_name: jellyfin
-    environment:
-      - PUID={$PUID}
-      - PGID={$PGID}
-      - TZ=${TZ}
-      #- JELLYFIN_PublishedServerUrl=192.168.0.5 #optional
-    volumes:
-      - ".config/jellyfin:/config"
-      - "CHANGE_TO_COMPOSE_DATA_PATH/media:/data"
-    ports:
-      - 8096:8096
-      - 7359:7359/udp #optional - network discovery
-      - 1900:1900/udp #optional - dlna discovery
-    restart: unless-stopped
-  audiobookshelf:
-    container_name: audiobookshelf
-    image: ghcr.io/advplyr/audiobookshelf:latest
-    environment:
-      - PUID=${PUID}
-      - PGID=${PGID}
-      - UMASK_SET=022
-      - TZ=${TZ}
-    ports:
-      - 13378:80
-    volumes:
-      - "CHANGE_TO_COMPOSE_DATA_PATH/media/audio/books:/audiobooks"
-      - "CHANGE_TO_COMPOSE_DATA_PATH/media/audio/podcasts:/podcasts"
-      - ".config/audiobookshelf:/config"
-      - ".metadata/audiobookshelf:/metadata"
-    restart: unless-stopped
-  jellyseerr:
-    image: fallenbagel/jellyseerr:latest
-    container_name: jellyseerr
-    environment:
-      - TZ=${TZ}
-    ports:
-      - 5055:5055
-    volumes:
-      - "./config/jellyseerr:/app/config"
-    restart: unless-stopped
-  beets:
-    image: lscr.io/linuxserver/beets:latest
-    container_name: beets
-    environment:
-      - PUID=${PUID}
-      - PGID=${PGID}
-      - TZ=${TZ}
-    volumes:
-      - "./config/beets:/config"
-      - "CHANGE_TO_COMPOSE_DATA_PATH/media/audio/music:/music"
-      - "CHANGE_TO_COMPOSE_DATA_PATH/media/audio/music-unsorted:/downloads"
-      - "CHANGE_TO_COMPOSE_DATA_PATH:/data"
-    ports:
-      - 8337:8337
-    restart: unless-stopped
-  homarr:
-    image: ghcr.io/ajnart/homarr:latest
-    container_name: homarr
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock # Optional, only if you want docker integration
-      - ./config/homarr/configs:/app/data/configs
-      - ./config/homarr/icons:/app/public/icons
-      - ./config/homarr/data:/data
-    ports:
-      - '80:7575'
-    restart: unless-stopped

roles/grocy/defaults/main.yml

@@ -0,0 +1,8 @@
+---
+
+stack_grocy_env_dir: /opt/stack_grocy
+
+stack_grocy_puid: 1000
+stack_grocy_pgid: 100
+stack_grocy_tz: America/Chicago
+stack_grocy_umask_set: 022

roles/grocy/tasks/main.yml

@@ -0,0 +1,16 @@
+---
+- name: Create grocy stack environment directory
+  ansible.builtin.file:
+    state: directory
+    path: "{{ stack_grocy_env_dir }}"
+    owner: root
+    group: root
+    mode: 0700
+
+- name: Start the compose stack
+  community.docker.docker_compose_v2:
+    project_name: stack_grocy
+    definition: "{{ lookup('template', 'docker-compose.yaml.j2') | from_yaml }}"
+    remove_orphans: true
+    wait: true
+    wait_timeout: 60

roles/grocy/templates/docker-compose.yaml.j2

@@ -0,0 +1,24 @@
+services:
+  sonarr:
+    container_name: grocy
+    image: lscr.io/linuxserver/grocy:latest
+    networks:
+      - caddy
+    environment:
+      - PUID={{ stack_grocy_puid }}
+      - PGID={{ stack_grocy_pgid }}
+      - TZ={{ stack_grocy_tz }}
+      - UMASK_SET={{ stack_grocy_umask_set }}
+    volumes:
+      - "{{ arrstack_env_dir }}/config/grocy:/config"
+    restart: unless-stopped
+    labels:
+      caddy: "http://house.pichi.berlin"
+      caddy.reverse_proxy: "{{ '{{' }}upstreams 80{{ '}}'}}"
+
+networks:
+  caddy:
+    external: true
+
+volumes:
+  caddy_data: {}

roles/grocy/tests/test.yml

@@ -0,0 +1,5 @@
+---
+- hosts: localhost
+  remote_user: root
+  roles:
+    - grocy

roles/paperless/README.md

@@ -0,0 +1,46 @@
+Role Name
+=========
+
+Set up a docker-hosted paperless-ngx instance.
+
+Requirements
+------------
+
+The target server needs to be running a reasonably recent version of docker,
+which contains the `docker compose` (_not_ `docker-compose`) sub-command.
+
+Role Variables
+--------------
+
+All relevant variables reside in `defaults/main.yml`.
+<!-- TODO: Describe variables -->
+
+Dependencies
+------------
+
+Relies on the `caddy` role to be executed for caddy to pick up the container and proxy to it.
+
+Example Playbook
+----------------
+
+The role can easily be set up in the following way to deploy to any server:
+
+    - hosts: servers
+      roles:
+         - role: paperless
+
+An example scanning script is included which I wrote for my old printer and allows (relatively) rapid scanning by pushing a button,
+and automatically merging and sending the files to the consume folder.
+
+This will need to be adjusted for wherever you watch for the documents,
+but is a simple example of how it could be integrated into a scanning workflow.
+
+License
+-------
+
+MIT
+
+Author Information
+------------------
+
+Copyright (c) 2025 Marty Oehme. All Rights Reserved.

roles/paperless/meta/main.yml

@@ -0,0 +1,34 @@
+galaxy_info:
+  author: your name
+  description: your role description
+  company: your company (optional)
+
+  # If the issue tracker for your role is not on github, uncomment the
+  # next line and provide a value
+  # issue_tracker_url: http://example.com/issue/tracker
+
+  # Choose a valid license ID from https://spdx.org - some suggested licenses:
+  # - BSD-3-Clause (default)
+  # - MIT
+  # - GPL-2.0-or-later
+  # - GPL-3.0-only
+  # - Apache-2.0
+  # - CC-BY-4.0
+  license: license (GPL-2.0-or-later, MIT, etc)
+
+  min_ansible_version: 2.1
+
+  # If this a Container Enabled role, provide the minimum Ansible Container version.
+  # min_ansible_container_version:
+
+  galaxy_tags: []
+    # List tags for your role here, one per line. A tag is a keyword that describes
+    # and categorizes the role. Users find roles by searching for tags. Be sure to
+    # remove the '[]' above, if you add tags to this list.
+    #
+    # NOTE: A tag is limited to a single word comprised of alphanumeric characters.
+    #       Maximum 20 tags per role.
+
+dependencies: []
+  # List your role dependencies here, one per line. Be sure to remove the '[]' above,
+  # if you add dependencies to this list.

roles/paperless/scripts/scantopaperless.sh

@@ -24,5 +24,5 @@ if ! stat -t out*.png >/dev/null 2>&1; then
 fi
 
 magick out*.png out.pdf
-mv out.pdf "$HOME/documents/archive/consume/$(date +'%Y-%m-%dT%H-%M')_scan.pdf"
+mv out.pdf "$HOME/documents/consume/$(date +'%Y-%m-%dT%H-%M')_scan.pdf"
 rm out*.png

roles/paperless/tests/inventory

@@ -0,0 +1,2 @@
+localhost
+