jpmschweitzer/portainer-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(stack): add Paperless-ngx document management system

Browse Source 
- Add paperless.yml stack (port 8091, documents.schweitz.net)
- Uses shared postgres (DB: paperless) and redis (DB 8)
- ClamAV installed on host for virus scanning (port 3310)
- Add Paperless integration to library-desk stack
- Update CONTAINERS.md with Paperless and ClamAV profiles
- Add Portainer and NPM API documentation to setup-new-host.md
- Update redis-shared.yml and postgres-shared.yml with Paperless refs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2025-12-25 00:36:15 +01:00
co-authored by Claude Opus 4.5
parent 7e06c915ad
commit 765818b4e9
7 changed files with 655 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTAINERS.md
+67 -5
View File
@@ -1,7 +1,7 @@
# Container Reference - tower-of-joy Infrastructure
> **Last Updated:** 2025-12-14
> **Total Services:** 24 containers across 19 stacks
> **Last Updated:** 2025-12-24
> **Total Services:** 26 containers across 20 stacks
> **System:** Intel i7-6700, RTX 2080 Ti (11GB VRAM), 16GB RAM, Zorin OS 16.3
---
@@ -34,6 +34,8 @@
| **Library Desk** | 8089 | http://192.168.86.149:8089 | LAN | No | 4 | ✅ Running (external) |
| **AMP (Game Server)** | Varies | http://192.168.86.149:8081 | LAN | No | - | ✅ Running |
| **Home Assistant** | 8123 | https://housekeeping.schweitz.net | Internet | No | - | ✅ Running |
| **Paperless-ngx** | 8091 | https://documents.schweitz.net | Internet | No | 8 | ✅ Running |
| **ClamAV** | 3310 | N/A (host service) | No | No | - | ✅ Running |
### External Domains (SSL via Let's Encrypt)
- **home.schweitz.net** → Organizr (Protected by Authentik SSO)
@@ -45,6 +47,7 @@
- **code.schweitz.net** → Code-Server (host service)
- **amp.schweitz.net** → AMP Game Server
- **housekeeping.schweitz.net** → Home Assistant
- **documents.schweitz.net** → Paperless-ngx
- **tatlock.schweitz.net** → (Reserved)
### External Repositories
@@ -122,8 +125,8 @@ PostgreSQL Shared is a centralized PostgreSQL 17 database server providing isola
| **Resource Limits** | None |
| **GPU Required** | No |
| **Dependencies** | docker-dataplane network |
| **Databases** | `authentik` (Authentik SSO), `gitea` (Git hosting), `organizr` (Organizr dashboard), `postgres` (default/admin) |
| **Database Users** | `authentik_user`, `gitea_user`, `organizr_user`, `postgres` (superuser) |
| **Databases** | `authentik` (Authentik SSO), `gitea` (Git hosting), `organizr` (Organizr dashboard), `paperless` (Document management), `postgres` (default/admin) |
| **Database Users** | `authentik_user`, `gitea_user`, `organizr_user`, `paperless_user`, `postgres` (superuser) |
| **Health Check** | `pg_isready -U postgres` (30s interval) |
| **Backup Strategy** | `/backups` volume for pg_dump exports |
@@ -158,7 +161,7 @@ Redis Shared is a centralized Redis 7 key-value store providing cache, session s
| **Resource Limits** | None |
| **GPU Required** | No |
| **Dependencies** | docker-dataplane network |
| **Database Allocation** | DB 0: Authentik, DB 1: Tatlock (memory), DB 2: Wiki.js, DB 3: Scheduler, DB 4: Library Desk, DB 5: SearXNG, DB 6: Tatlock (benchmarks), DB 7: Nextcloud, DB 8-15: Available |
| **Database Allocation** | DB 0: Authentik, DB 1: Tatlock (memory), DB 2: Wiki.js, DB 3: Scheduler, DB 4: Library Desk, DB 5: SearXNG, DB 6: Tatlock (benchmarks), DB 7: Nextcloud, DB 8: Paperless, DB 9-15: Available |
| **Persistence** | AOF (Append-Only File) enabled for durability |
| **Health Check** | `redis-cli ping` returns PONG (30s interval) |
| **Connection String** | `redis://redis-shared:6379/0` (DB 0), `redis://redis-shared:6379/1` (DB 1), etc. |
@@ -471,6 +474,65 @@ Home Assistant is an open-source smart home automation platform that integrates
---
### Paperless-ngx
Paperless-ngx is a document management system that transforms physical documents into a searchable online archive with automatic OCR text recognition, tagging, and full-text search. It provides a web interface for uploading, organizing, and retrieving documents with support for correspondents, document types, and custom fields. The service integrates with Library Desk for document indexing and uses ClamAV for virus scanning of uploaded files. Configs and database are stored on SSD (backed up), while documents are stored on HDD for capacity. Uses shared PostgreSQL for metadata and shared Redis (DB 8) for task queuing.
| Property | Value |
|----------|-------|
| **Image** | `ghcr.io/paperless-ngx/paperless-ngx:latest` |
| **Container Name** | `paperless` |
| **Access URL (LAN)** | http://192.168.86.149:8091 |
| **Access URL (Public)** | https://documents.schweitz.net |
| **External Access** | Yes (via NPM reverse proxy with SSL) |
| **Port Mapping** | 8091:8000 (HTTP) |
| **Network Mode** | Bridge (docker-dataplane) |
| **Restart Policy** | `unless-stopped` |
| **Volume Mounts** | SSD (backed up): `~/docker-data/paperless/data:/usr/src/paperless/data`; HDD: `/mnt/media/paperless/media:/usr/src/paperless/media`, `/mnt/media/paperless/consume:/usr/src/paperless/consume`, `/mnt/media/paperless/export:/usr/src/paperless/export` |
| **Environment** | `PAPERLESS_DBHOST=postgres-shared`, `PAPERLESS_REDIS=redis://redis-shared:6379/8`, `PAPERLESS_URL=https://documents.schweitz.net`, `TZ=Europe/Amsterdam` |
| **Resource Limits** | Memory: 4GB limit, 512MB reservation |
| **GPU Required** | No |
| **Dependencies** | PostgreSQL Shared, Redis Shared (DB 8), NPM (reverse proxy), ClamAV (host) |
| **Database** | PostgreSQL `paperless` on postgres-shared |
| **Health Check** | `curl -f http://localhost:8000` (30s interval) |
| **Features** | OCR (eng+nld), document tagging, full-text search, correspondents, custom fields, webhooks |
| **Integration** | Library Desk (webhook on document added), ClamAV (virus scanning) |
---
### ClamAV
ClamAV is an open-source antivirus engine running on the host OS, providing virus scanning capabilities for the entire server and accessible via TCP socket for container-based services like Paperless-ngx. It includes automatic virus definition updates via freshclam and can perform both on-demand and real-time scanning. Running on the host provides better security isolation than containerized scanning and allows scanning of the host filesystem directly.
| Property | Value |
|----------|-------|
| **Deployment Type** | Host-based systemd service (NOT containerized) |
| **Binary Location** | `/usr/bin/clamd`, `/usr/bin/clamdscan` |
| **Service Names** | `clamav-daemon.service`, `clamav-freshclam.service` |
| **Access URL** | N/A (TCP socket only) |
| **External Access** | No (internal service) |
| **Port Binding** | 0.0.0.0:3310 (TCP socket for remote scanning) |
| **Restart Policy** | `always` (systemd) |
| **Config Location** | `/etc/clamav/clamd.conf`, `/etc/clamav/freshclam.conf` |
| **Database Location** | `/var/lib/clamav/` (virus definitions) |
| **Resource Usage** | ~2-4GB RAM (virus definitions loaded in memory) |
| **GPU Required** | No |
| **Dependencies** | None (host service) |
| **Update Schedule** | Automatic via freshclam (checks multiple times daily) |
| **Connection String** | `clamav://192.168.86.149:3310` |
| **Features** | On-demand scanning, TCP socket API, automatic updates, host filesystem access |
**Usage from containers:**
```bash
# Test connectivity
nc -zv 192.168.86.149 3310
# Scan a file (from host)
clamdscan /path/to/file
```
---
### Samba
Samba provides SMB/CIFS network file sharing for seamless access to homelab storage from Windows, macOS, Linux, and mobile devices, exposing curated shares for media libraries, downloads, and backups with configurable read-only and read-write permissions. It runs as a single container on the samba_default network, serving three shares: Media (read-write access to Jellyfin content), Downloads (read-write for torrent clients), and Backups (read-only for safe data recovery). The service uses password authentication for the user jpmschweitzer and stores its minimal configuration on the SSD while directly mounting HDD paths for zero-copy file access with native performance.