app-catalog-felhom.eu/templates/paperless-ngx/.felhom.yml

# =============================================================================
# .felhom.yml — App metadata for felhom-controller
# =============================================================================
# Place alongside docker-compose.yml in each stack directory:
#   /opt/docker/stacks/paperless-ngx/.felhom.yml
#
# This file defines:
#   1. Display info (name, description, icon)
#   2. Deploy fields (what the user fills in during first deployment)
#   3. Asset references (logos, screenshots loaded from felhom.eu)
#   4. Resource hints (RAM, Pi compatibility)
# =============================================================================

# --- Display info (shown on dashboard) ---
display_name: "Paperless-ngx"
description: "Dokumentumok digitalizálása és rendszerezése"
category: "productivity"              # productivity, media, finance, security, tools
subdomain: "paperless"                # -> paperless.<domain>

# --- Asset slug ---
# Used to construct URLs for logo and screenshots from felhom.eu:
#   Logo:        {assets.base_url}/assets/{slug}-logo.webp
#   Screenshot:  {assets.base_url}/assets/{slug}-screenshot-{n}.webp
#   App page:    {assets.base_url}/alkalmazasok#{slug}
# Falls back to directory name if not set.
slug: "paperless-ngx"
# catalog_since: the date THIS repo last changed this app's pinned images. Any commit that
# changes an image: line must set this to the same day (see CLAUDE.md).
catalog_since: "2026-07-18"

# --- Resource hints (displayed on deploy screen) ---
resources:
  mem_request: "500M"                  # Expected memory usage (display hint)
  mem_limit: "1664M"                   # Total enforced limit across all containers (1280+256+128) — R-514
  pi_compatible: true                  # Runs on Raspberry Pi 3B+
  needs_hdd: true                      # Needs external storage for user data

# --- Backup classification (referential coupling; see felhom.eu documentation/audits/SPIKE-backup-classification-2026-07-14.md) ---
backup:
  hdd:
    - path: appdata/paperless/media
      class: mandatory        # document originals+archive — DB hashes/paths reference them
    - path: appdata/paperless/export
      class: excluded          # transient export target
  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.
#
# Field types:
#   domain    - Auto-filled from controller config, read-only
#   secret    - Auto-generated, hidden (user sees "Generated ✓")
#   password  - Auto-generated but shown, user can override
#   path      - Filesystem path (validated for existence)
#   text      - Free text input
#   select    - Dropdown with predefined options
#   boolean   - Toggle switch
#
# Generator types (for secret/password):
#   password:N  - N chars alphanumeric
#   hex:N       - N bytes hex-encoded
#   static:VAL  - Fixed value

deploy_fields:
  - env_var: DOMAIN
    label: "Domain"
    type: domain
    description: "A szerver domain neve"
    locked_after_deploy: true

  - env_var: SUBDOMAIN
    label: "Aldomain"
    type: subdomain
    default: "paperless"
    required: true
    locked_after_deploy: true
    description: "Az alkalmazás aldomainje"

  - env_var: DB_PASSWORD
    label: "Adatbázis jelszó"
    type: secret
    generate: "password:24"
    locked_after_deploy: true

  - env_var: PAPERLESS_SECRET_KEY
    label: "Titkosítási kulcs"
    type: secret
    generate: "hex:32"
    locked_after_deploy: true

  - env_var: PAPERLESS_ADMIN_USER
    label: "Admin felhasználónév"
    type: text
    default: "admin"
    locked_after_deploy: false

  - env_var: PAPERLESS_ADMIN_PASSWORD
    label: "Admin jelszó"
    type: password
    generate: "password:16"
    description: "Első bejelentkezéshez. Utána a webes felületen módosítható."
    locked_after_deploy: false

  - env_var: HDD_PATH
    label: "Adattárolási útvonal"
    type: path
    required: true
    placeholder: "/mnt/felhom-drives/hdd_1"
    description: "A külső merevlemez elérési útja, ahol a dokumentumok tárolódnak"
    locked_after_deploy: true

  - env_var: PAPERLESS_OCR_LANGUAGE
    label: "OCR nyelv"
    type: select
    default: "hun+eng"
    options:
      - value: "hun"
        label: "Magyar"
      - value: "eng"
        label: "Angol"
      - value: "hun+eng"
        label: "Magyar + Angol"
      - value: "deu+eng"
        label: "Német + Angol"
    description: "Dokumentum felismerés nyelve"
    locked_after_deploy: false

# --- App info (info page content) ---
app_info:
  tagline: 'Digitális irattár - szkennelés, OCR és automatikus rendszerezés'
  docs_url: 'https://docs.paperless-ngx.com/'

  use_cases:
    - 'Papír dokumentumok digitalizálása és rendszerezése'
    - 'Automatikus OCR szövegfelismerés szkennelt dokumentumokon'
    - 'Intelligens automatikus kategorizálás és címkézés'
    - 'Teljes szöveges keresés az összes dokumentumban'
    - 'Email-ből érkező dokumentumok automatikus feldolgozása'

  first_steps:
    - 'Nyisd meg a paperless.DOMAIN címet a böngészőben'
    - 'Lépj be: felhasználó "admin", a jelszó a Beállítások oldalon található (Automatikusan generált értékek)'
    - 'Tölts fel egy dokumentumot a webfelületen, VAGY dobd a Fájlkezelőben (FileBrowser) az import/paperless mappába — onnan automatikusan beolvassa és OCR-rel feldolgozza. A Fájlkezelő belépése a Fájlkezelő alkalmazás oldalán található'
    - 'Sok dokumentumot egyszerre is feltölthetsz: egyenként dolgozza fel őket, egy nagyobb köteg néhány percig tart'
    - 'Hozz létre címkéket és levelezőket az automatikus rendszerezéshez'

  prerequisites:
    - 'Külső HDD ajánlott a dokumentumok tárolásához'
    - 'Legalább 1 GB szabad RAM (OCR feldolgozáshoz)'

# --- Controller-side health probe ---
healthcheck:
  # container: no container is called `paperless-ngx` and none even begins with it, so the probe had NEVER
  # run on this app on any box — and `verifying` then waited out the full health timeout and
  # STOPPED a working app (R-630, measured 2026-09-22: failed at +313.0 s, front door 404 after)
  container: paperless-webserver
  checks:
    - type: http
      port: 8000

# --- English copy (localisation slice 5, R-560) --------------------------------------------
# The Hungarian above is UNCHANGED. A box on English reads this block field by field; a missing
# field shows the Hungarian one; a controller older than 0.257.0 ignores the block entirely.
i18n:
  en:
    description: "Digitise your documents and keep them in order"

    data_paths:
      - path: paperless
        label: "Documents to read in"

    deploy_fields:
      - env_var: DOMAIN
        label: "Domain"
        description: "The server domain name"

      - env_var: SUBDOMAIN
        label: "Subdomain"
        description: "The subdomain this app answers on"

      - env_var: DB_PASSWORD
        label: "Database password"

      - env_var: PAPERLESS_SECRET_KEY
        label: "Encryption key"

      - env_var: PAPERLESS_ADMIN_USER
        label: "Admin user name"

      - env_var: PAPERLESS_ADMIN_PASSWORD
        label: "Admin password"
        description: "For the first sign-in. You can change it in the app afterwards."

      - env_var: HDD_PATH
        label: "Data storage path"
        placeholder: "/mnt/felhom-drives/hdd_1"
        description: "The path to the external hard drive where the documents are kept"

      - env_var: PAPERLESS_OCR_LANGUAGE
        label: "OCR language"
        description: "The language the text recognition reads"
        options:
          - value: "hun"
            label: "Hungarian"
          - value: "eng"
            label: "English"
          - value: "hun+eng"
            label: "Hungarian + English"
          - value: "deu+eng"
            label: "German + English"

    app_info:
      tagline: 'A digital filing cabinet - scanning, OCR and automatic sorting'

      use_cases:
        - 'Turn paper documents into files and keep them in order'
        - 'Automatic OCR text recognition on scanned documents'
        - 'Smart automatic sorting and tagging'
        - 'Full text search across every document'
        - 'Documents that arrive by e-mail are processed automatically'

      first_steps:
        - 'Open paperless.DOMAIN in your browser'
        - 'Sign in: user "admin". The password is on the Settings page, under Automatically generated values'
        - 'Upload a document in the app, OR drop it into the import/paperless folder in the File manager (FileBrowser) - it is read in and processed with OCR from there. The File manager sign-in is on the File manager app page'
        - 'You can upload many documents at once: they are processed one by one, and a larger batch takes a few minutes'
        - 'Create tags and correspondents so new documents sort themselves'

      prerequisites:
        - 'An external hard drive is recommended to keep the documents on'
        - 'At least 1 GB of free RAM (for the OCR work)'