From 4252121519758d21f0033e7eef69bc56c2f28723 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sun, 26 Jul 2026 08:17:55 +0200 Subject: [PATCH] R-75: ingest binds move to ${IMPORT_PATH}; data_paths annotation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit paperless-ngx and calibre-web are the only two catalog apps with a drop-zone, and each has exactly ONE ingest bind. Both move from ${USERDATA_PATH}/import/ to ${IMPORT_PATH}/ — the canonical root on the system drive — so a multi-drive box has one drop-zone instead of one real folder plus a dead lookalike on every other drive (and import/* is class: excluded, so files stranded in a dead one would never be backed up either). The matching backup: entries move to the new `import:` list IN THE SAME COMMIT. This is not cosmetic: ValidateBackupSpec rejects an entry matching no compose bind, and the rejection is WHOLE-BLOCK, so a stale `userdata: import/paperless` would have discarded paperless's `hdd: appdata/paperless/media class: mandatory` too and silently degraded the customer's document originals to legacy handling. Both classes stay `excluded` — the move must not change data handling. New data_paths: blocks on paperless-ngx, calibre-web and romm — role + Hungarian label over paths that already exist as compose binds. Covers all three roles and the multi-entry case. Requires controller v0.172.0 (deployed to both demo boxes before this push, since ${IMPORT_PATH} is unset on older controllers). Storage-layout header comments updated in both composes — they are the only in-repo documentation of the layout. --- templates/calibre-web/.felhom.yml | 14 +++++++++++++- templates/calibre-web/docker-compose.yml | 6 ++++-- templates/paperless-ngx/.felhom.yml | 13 +++++++++++-- templates/paperless-ngx/docker-compose.yml | 8 ++++++-- templates/romm/.felhom.yml | 7 +++++++ 5 files changed, 41 insertions(+), 7 deletions(-) diff --git a/templates/calibre-web/.felhom.yml b/templates/calibre-web/.felhom.yml index bd20943..17d4aa9 100644 --- a/templates/calibre-web/.felhom.yml +++ b/templates/calibre-web/.felhom.yml @@ -21,9 +21,21 @@ backup: userdata: - path: media/books class: mandatory # metadata.db lives INSIDE the tree — DB and books are one unit - - path: import/calibre + import: + - path: calibre class: excluded # ingest inbox, transient +# --- Customer-facing folder annotation (R-75) --- +data_paths: + - path: calibre + root: import + role: import + label: "Beolvasandó e-könyvek" + - path: media/books + root: userdata + role: library + label: "E-könyvtár" + # --- Deploy fields (first deployment only) --- deploy_fields: - env_var: DOMAIN diff --git a/templates/calibre-web/docker-compose.yml b/templates/calibre-web/docker-compose.yml index d9e469d..61c118b 100644 --- a/templates/calibre-web/docker-compose.yml +++ b/templates/calibre-web/docker-compose.yml @@ -6,11 +6,13 @@ # Environment variables: # DOMAIN - Your domain (e.g., demo-felhom.eu) # USERDATA_PATH - Ügyfél-tartalom gyökér (/userdata) +# IMPORT_PATH - KANONIKUS beolvasási gyökér a rendszerlemezen (R-75) — NEM az app lemezén # # Storage layout (felhom userdata convention): # App config/DB → calibre_web_config (named volume, NVMe) # Calibre library → ${USERDATA_PATH}/media/books (browsable, írható) -# Book ingest → ${USERDATA_PATH}/import/calibre (drop-zone — processed and removed) +# Book ingest → ${IMPORT_PATH}/calibre (drop-zone — processed and removed) +# ^ CANONICAL: one import root for the whole box, on the SYSTEM drive — NOT per data drive. # Run-identity: PUID/PGID 1000 (shared content group); UMASK=002 so output is group-writable. # # First-time setup: @@ -28,7 +30,7 @@ services: - UMASK=002 volumes: - calibre_web_config:/config - - ${USERDATA_PATH}/import/calibre:/cwa-book-ingest + - ${IMPORT_PATH}/calibre:/cwa-book-ingest - ${USERDATA_PATH}/media/books:/calibre-library networks: - traefik-public diff --git a/templates/paperless-ngx/.felhom.yml b/templates/paperless-ngx/.felhom.yml index bf5be0b..d8faf17 100644 --- a/templates/paperless-ngx/.felhom.yml +++ b/templates/paperless-ngx/.felhom.yml @@ -39,10 +39,19 @@ backup: class: mandatory # document originals+archive — DB hashes/paths reference them - path: appdata/paperless/export class: excluded # transient export target - userdata: - - path: import/paperless + import: + - path: paperless class: excluded # consume inbox — deleted after ingest by contract +# --- Customer-facing folder annotation (R-75) --- +# ANNOTATES paths that already exist as compose binds above; never declares a new one. +# role: import | library | export (unknown role → that entry is simply not shown) +data_paths: + - path: paperless + root: import + role: import + label: "Beolvasandó dokumentumok" + # --- Deploy fields --- # Shown to the user during first deployment. # After deployment, values are saved to app.yaml in the stack directory. diff --git a/templates/paperless-ngx/docker-compose.yml b/templates/paperless-ngx/docker-compose.yml index 8d6669f..7ca5904 100644 --- a/templates/paperless-ngx/docker-compose.yml +++ b/templates/paperless-ngx/docker-compose.yml @@ -7,13 +7,17 @@ # DOMAIN - Your domain (e.g., demo-felhom.eu) # HDD_PATH - Drive namespace root (managed media/export under appdata) # USERDATA_PATH - Ügyfél-tartalom gyökér (/userdata) +# IMPORT_PATH - KANONIKUS beolvasási gyökér a rendszerlemezen (R-75) — NEM az app lemezén # PAPERLESS_SECRET_KEY - Random secret (auto-generated) # DB_PASSWORD - PostgreSQL password (auto-generated) # PAPERLESS_ADMIN_USER - Initial admin username (default: admin) # PAPERLESS_ADMIN_PASSWORD - Initial admin password # # Storage layout (felhom userdata convention): -# Consume drop-zone → ${USERDATA_PATH}/import/paperless (browsable — drop files here via FileBrowser) +# Consume drop-zone → ${IMPORT_PATH}/paperless (browsable — drop files here via FileBrowser) +# ^ CANONICAL: one import root for the whole box, on the SYSTEM drive — NOT per data drive. +# Each drop-zone app has exactly ONE ingest bind, so a per-drive import/ would put a folder +# that looks like a drop-zone on every drive while only one of them does anything. # Document media → ${HDD_PATH}/appdata/paperless/media (app-managed originals + archive) # Export folder → ${HDD_PATH}/appdata/paperless/export (app-managed backups) # App data/index → paperless_data (named volume, NVMe) @@ -63,7 +67,7 @@ services: volumes: - paperless_data:/usr/src/paperless/data - ${HDD_PATH}/appdata/paperless/media:/usr/src/paperless/media - - ${USERDATA_PATH}/import/paperless:/usr/src/paperless/consume + - ${IMPORT_PATH}/paperless:/usr/src/paperless/consume - ${HDD_PATH}/appdata/paperless/export:/usr/src/paperless/export networks: - traefik-public diff --git a/templates/romm/.felhom.yml b/templates/romm/.felhom.yml index 250c82f..3d7d9aa 100644 --- a/templates/romm/.felhom.yml +++ b/templates/romm/.felhom.yml @@ -25,6 +25,13 @@ backup: - path: appdata/romm/resources class: excluded # scraper cache, re-derivable +# --- Customer-facing folder annotation (R-75) --- +data_paths: + - path: roms + root: userdata + role: library + label: "ROM gyűjtemény" + # --- Deploy fields (first deployment only) --- deploy_fields: - env_var: DOMAIN