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"

# --- Resource hints (displayed on deploy screen) ---
resources:
  mem_request: "500M"                  # Expected memory usage (display hint)
  mem_limit: "1152M"                   # Total enforced limit across all containers (768+256+128)
  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'
  default_creds: 'admin / admin'
  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'
    - 'Jelentkezz be: admin / admin'
    - 'Változtasd meg azonnal a jelszót'
    - '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'
    - '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:
  checks:
    - type: http
      port: 8000