From cf5474369d2f6b118f6b9d3b8eb9b514dd56d3d8 Mon Sep 17 00:00:00 2001
From: Fizzlepoof <admin@paccoco.com>
Date: Wed, 13 May 2026 17:06:52 +0000
Subject: [PATCH] docs(paperless): document Office ingestion support

Document Paperless Tika/Gotenberg sidecars, supported Office/OpenDocument ingestion formats, stack paths, validation/deploy procedure, and verification commands. Updates service inventory and architecture overview so PD docs match the deployed documents stack.
---
 docs/architecture/ARCHITECTURE_OVERVIEW.md |  2 +-
 docs/architecture/SERVICES_DIRECTORY.md    |  2 +-
 docs/operations/PAPERLESS.md               | 49 ++++++++++++++++++++++
 documents/README.md                        | 39 +++++++++++++++++
 4 files changed, 90 insertions(+), 2 deletions(-)
 create mode 100644 docs/operations/PAPERLESS.md
 create mode 100644 documents/README.md

diff --git a/docs/architecture/ARCHITECTURE_OVERVIEW.md b/docs/architecture/ARCHITECTURE_OVERVIEW.md
index d0e461c..f43bde2 100644
--- a/docs/architecture/ARCHITECTURE_OVERVIEW.md
+++ b/docs/architecture/ARCHITECTURE_OVERVIEW.md
@@ -41,7 +41,7 @@ Full homelab stack as of 2026-05-09. All 6 expansion phases are complete and dep
 
 ### Productivity Layer
 - **Immich** (2283) — photo management; library on Serenity NFS
-- **Paperless-NGX** (8083) — document management
+- **Paperless-NGX** (8083) — document management; uses internal Tika + Gotenberg sidecars for Office/OpenDocument text extraction and conversion
 - **Karakeep** (3100) — bookmarks / read-later
 - **n8n** (5678) — workflow automation
 - **KitchenOwl** (8086), **DoneTick** (2021) — household and task management
diff --git a/docs/architecture/SERVICES_DIRECTORY.md b/docs/architecture/SERVICES_DIRECTORY.md
index 38aa9c2..08a3583 100644
--- a/docs/architecture/SERVICES_DIRECTORY.md
+++ b/docs/architecture/SERVICES_DIRECTORY.md
@@ -55,7 +55,7 @@ All homelab services, their hosts, ports, and current status.
 | Service | Port | Status |
 |---------|------|--------|
 | Immich | 2283 | ✅ Active |
-| Paperless-NGX | 8083 | ✅ Active |
+| Paperless-NGX | 8083 | ✅ Active; DOCX/Office ingestion via internal Tika + Gotenberg sidecars |
 | Karakeep | 3100 | ✅ Active |
 | n8n | 5678 | ✅ Active |
 | KitchenOwl | 8086 | ✅ Active |
diff --git a/docs/operations/PAPERLESS.md b/docs/operations/PAPERLESS.md
new file mode 100644
index 0000000..c0fccde
--- /dev/null
+++ b/docs/operations/PAPERLESS.md
@@ -0,0 +1,49 @@
+# Paperless-NGX Operations
+
+## Stack Location
+
+- Compose path on PD: `/mnt/docker-ssd/docker/compose/documents/docker-compose.yaml`
+- Appdata: `/mnt/docker-ssd/docker/appdata/paperless/`
+- Consume source: `/mnt/unraid/data/paperless/consume`
+- Consume container path: `/usr/src/paperless/consume`
+
+## Office Document Ingestion
+
+Paperless-NGX uses internal-only Tika and Gotenberg sidecars:
+
+- Tika endpoint: `http://tika:9998`
+- Gotenberg endpoint: `http://gotenberg:3000`
+- Network: `documents_paperless_internal`
+- Host ports: none
+- Resource limits: Tika `512m`, Gotenberg `256m`
+
+This enables ingestion/extraction for Office and OpenDocument files such as:
+
+- `.docx`, `.doc`
+- `.pptx`, `.xlsx`
+- `.odt`, `.ods`, `.odp`
+
+## Deploy / Restart Procedure
+
+Validate before changing running containers:
+
+```bash
+cd /mnt/docker-ssd/docker/compose/documents
+docker compose --env-file .env config
+```
+
+Deploy with compose only:
+
+```bash
+docker compose --env-file .env down && docker compose --env-file .env up -d
+```
+
+Never use `systemctl restart docker` on PD for this stack.
+
+## Verification
+
+```bash
+docker compose --env-file .env ps
+docker logs paperless --tail 200 | grep -Ei 'tika|gotenberg'
+docker exec paperless sh -lc 'echo "$PAPERLESS_TIKA_ENABLED $PAPERLESS_TIKA_ENDPOINT $PAPERLESS_TIKA_GOTENBERG_ENDPOINT"; mount | grep /usr/src/paperless/consume'
+```
diff --git a/documents/README.md b/documents/README.md
new file mode 100644
index 0000000..e738e4e
--- /dev/null
+++ b/documents/README.md
@@ -0,0 +1,39 @@
+# Documents Stack
+
+Docker Compose stack for document and knowledge-capture services on PD.
+
+## Paperless-NGX
+
+- URL: `https://paperless.paccoco.com` / `http://pd:8083`
+- Compose service: `paperless`
+- Appdata: `/mnt/docker-ssd/docker/appdata/paperless/`
+- Consume folder: `/mnt/unraid/data/paperless/consume` → `/usr/src/paperless/consume`
+- Database: shared Postgres on `ix-databases_shared-databases`
+- Redis: shared Redis via `PAPERLESS_REDIS`
+
+Paperless has internal-only Tika and Gotenberg sidecars for Office/OpenDocument ingestion:
+
+- `tika` (`apache/tika`) at `http://tika:9998`, memory limit `512m`
+- `gotenberg` (`gotenberg/gotenberg`) at `http://gotenberg:3000`, memory limit `256m`
+- Both sidecars live only on `documents_paperless_internal` and expose no host ports.
+
+Required Paperless Tika env keys:
+
+```env
+PAPERLESS_TIKA_ENABLED=1
+PAPERLESS_TIKA_ENDPOINT=http://tika:9998
+PAPERLESS_TIKA_GOTENBERG_ENDPOINT=http://gotenberg:3000
+```
+
+Supported additional ingestion types include `.docx`, `.doc`, `.pptx`, `.xlsx`, and OpenDocument formats (`.odt`, `.ods`, `.odp`) in addition to the existing PDF/image OCR path.
+
+## Deploy
+
+From `/mnt/docker-ssd/docker/compose/documents` on PD:
+
+```bash
+docker compose --env-file .env config
+docker compose --env-file .env down && docker compose --env-file .env up -d
+```
+
+Do not restart Docker on PD; use stack-level compose commands only.