feat(paperless): add alternative Compose deployment

paperless/.env.example

@@ -0,0 +1,16 @@
+PAPERLESS_URL=https://papers.forust.xyz
+PAPERLESS_ALLOWED_HOSTS=papers.forust.xyz,papers.workstation.internal
+PAPERLESS_CSRF_TRUSTED_ORIGINS=https://papers.forust.xyz,https://papers.workstation.internal
+PAPERLESS_TIME_ZONE=Europe/Bratislava
+PAPERLESS_REDIS=redis://valkey:6379
+PAPERLESS_DBENGINE=postgresql
+PAPERLESS_DBHOST=homelab-postgres
+PAPERLESS_DBNAME=paperless
+PAPERLESS_DBUSER=paperless
+PAPERLESS_DBPASS=<SET_THE_SAME_VALUE_AS_SHARED_POSTGRES_PAPERLESS_DB_PASSWORD>
+PAPERLESS_OCR_LANGUAGE=rus+eng
+PAPERLESS_OCR_LANGUAGES=rus
+PAPERLESS_TASK_WORKERS=1
+PAPERLESS_ADMIN_USER=admin
+PAPERLESS_SECRET_KEY=<GENERATE_WITH_python3_-c_import_secrets;_print(secrets.token_urlsafe(64))>
+PAPERLESS_ADMIN_PASSWORD=<SET_A_LONG_UNIQUE_PASSWORD>

paperless/README.md

@@ -12,6 +12,34 @@ password authentication. OCR is configured for Russian and English documents.
 Keep `papers.forust.xyz` in the existing Cloudflare DDNS `DOMAINS` setting so
 the public record follows the workstation address.
 
+## Compose alternative
+
+`compose.yaml` is an alternative to the active Kubernetes deployment. Do not
+run both at the same time: they use the same Paperless database and route
+names, but have separate document volumes.
+
+The Compose variant uses the shared Compose PostgreSQL service on the
+`homelab-database` Docker network. It does not start a PostgreSQL container.
+The shared Compose database must be running and must have the `paperless`
+database and role. Set `PAPERLESS_DBPASS` to the same password as
+`PAPERLESS_DB_PASSWORD` in the shared PostgreSQL configuration.
+
+To prepare and start the Compose variant:
+
+```sh
+cp paperless/.env.example paperless/.env
+cd paperless
+docker compose -f compose.yaml config --quiet
+docker compose -f compose.yaml up -d
+```
+
+Create unique values for `PAPERLESS_SECRET_KEY` and
+`PAPERLESS_ADMIN_PASSWORD` in `.env`. This directory has no Compose `active`
+marker, so the repository deploy workflow does not start this alternative.
+Stop the Kubernetes Paperless deployment before switching to Compose. Back up
+and migrate the media files as well as the database; the Compose named volumes
+are separate from the Kubernetes PVC.
+
 ## Prepare the secret
 
 Create `k8s/secrets.yaml` on the workstation from

paperless/compose.yaml

@@ -0,0 +1,77 @@
+services:
+  paperless:
+    image: ghcr.io/paperless-ngx/paperless-ngx:3.2.1
+    container_name: paperless
+    restart: unless-stopped
+    env_file:
+      - .env
+    depends_on:
+      valkey:
+        condition: service_healthy
+    deploy:
+      resources:
+        limits:
+          cpus: "2.0"
+          memory: 2G
+        reservations:
+          cpus: "0.10"
+          memory: 512M
+    volumes:
+      - paperless-data:/usr/src/paperless/data
+      - paperless-media:/usr/src/paperless/media
+      - paperless-export:/usr/src/paperless/export
+      - paperless-consume:/usr/src/paperless/consume
+    networks:
+      - default
+      - proxy
+      - database
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=proxy"
+      - "traefik.http.services.paperless-compose.loadbalancer.server.port=8000"
+      - "traefik.http.routers.paperless-compose.rule=Host(`papers.forust.xyz`)"
+      - "traefik.http.routers.paperless-compose.entrypoints=websecure"
+      - "traefik.http.routers.paperless-compose.tls.certresolver=letsencrypt"
+      - "traefik.http.routers.paperless-compose-local.rule=Host(`papers.workstation.internal`)"
+      - "traefik.http.routers.paperless-compose-local.entrypoints=websecure"
+      - "traefik.http.routers.paperless-compose-local.tls=true"
+
+  valkey:
+    image: valkey/valkey:9.0.3-alpine
+    container_name: paperless-valkey
+    restart: unless-stopped
+    command:
+      - valkey-server
+      - --save
+      - ""
+      - --appendonly
+      - "no"
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    deploy:
+      resources:
+        limits:
+          cpus: "0.25"
+          memory: 256M
+        reservations:
+          cpus: "0.025"
+          memory: 64M
+    networks:
+      - default
+
+volumes:
+  paperless-data:
+  paperless-media:
+  paperless-export:
+  paperless-consume:
+
+networks:
+  default:
+  proxy:
+    external: true
+  database:
+    name: homelab-database
+    external: true

postgres/initdb/01-create-databases.sh

@@ -6,6 +6,7 @@ set -euo pipefail
 : "${NETBOX_DB_PASSWORD:?NETBOX_DB_PASSWORD is required}"
 : "${NETRONOME_DB_PASSWORD:?NETRONOME_DB_PASSWORD is required}"
 : "${PENPOT_DB_PASSWORD:?PENPOT_DB_PASSWORD is required}"
+: "${PAPERLESS_DB_PASSWORD:?PAPERLESS_DB_PASSWORD is required}"
 : "${STATUSPAGE_DB_PASSWORD:?STATUSPAGE_DB_PASSWORD is required}"
 
 create_role_and_database() {
@@ -27,4 +28,5 @@ create_role_and_database gitea gitea "$GITEA_DB_PASSWORD"
 create_role_and_database netbox netbox "$NETBOX_DB_PASSWORD"
 create_role_and_database netronome netronome "$NETRONOME_DB_PASSWORD"
 create_role_and_database penpot penpot "$PENPOT_DB_PASSWORD"
+create_role_and_database paperless paperless "$PAPERLESS_DB_PASSWORD"
 create_role_and_database statuspage statuspage "$STATUSPAGE_DB_PASSWORD"