app-catalog-felhom.eu/          <- This repo (source of truth)
├── templates.json              # Portainer App Templates index (LEGACY — Portainer-only setups)
├── templates/                  # Docker Compose templates with ${VAR} env var syntax
│   ├── actualbudget/
│   │   ├── docker-compose.yml
│   │   └── .felhom.yml         # App metadata for felhom-controller
│   ├── docmost/
│   ├── filebrowser/
│   ├── homebox/
│   ├── immich/
│   ├── mealie/
│   ├── paperless-ngx/
│   ├── romm/
│   ├── stirling-pdf/
│   └── vaultwarden/
└── scripts/
    └── generate-customer.sh    # LEGACY — generates customer-specific templates for Portainer

How It Works (Controller-based deployments)

The felhom-controller syncs directly from this repo:

Controller periodically pulls this repo (configurable interval, default 15m)
Copies docker-compose.yml and .felhom.yml from templates/<app>/ to /opt/docker/stacks/<app>/
Never overwrites app.yaml (deployed config/secrets) or .env files
Only copies files if content has actually changed (SHA-256 comparison)
After sync, triggers a stack rescan so new/updated apps appear on the dashboard
Manual sync available via "Sablonok frissítése" button on the Alkalmazások page

Controller git config (in controller.yaml)

git:
  repo_url: "https://gitea.dooplex.hu/admin/app-catalog-felhom.eu.git"
  branch: "main"
  sync_interval: "15m"
  username: ""     # Optional, for private repos
  token: ""        # Optional, for private repos

.felhom.yml Format

Each app template has a .felhom.yml metadata file that the controller uses for:

Display info on the dashboard (name, description, category, subdomain)
Resource hints (memory request/limit, Pi compatibility, HDD requirement)
Deploy fields (what the user fills in during first deployment)

Field types

Type	Description
`domain`	Auto-filled from controller config, read-only
`secret`	Auto-generated, hidden from user (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 fields)

Generator	Description
`password:N`	N chars alphanumeric
`hex:N`	N bytes hex-encoded
`static:VAL`	Fixed value

Example .felhom.yml

display_name: "Paperless-ngx"
description: "Dokumentumok digitalizálása és rendszerezése"
category: "productivity"
subdomain: "paperless"
slug: "paperless-ngx"
resources:
  mem_request: "500M"
  mem_limit: "1152M"
  pi_compatible: true
  needs_hdd: true
deploy_fields:
  - env_var: DOMAIN
    label: "Domain"
    type: domain
    locked_after_deploy: true
  - env_var: DB_PASSWORD
    label: "Adatbázis jelszó"
    type: secret
    generate: "password:24"
    locked_after_deploy: true
  - env_var: HDD_PATH
    label: "Adattárolási útvonal"
    type: path
    required: true
    placeholder: "/mnt/hdd_1"
    locked_after_deploy: true

App Catalog

App	DB Type	RAM (request / limit)	Pi	HDD Data	Subdomain
ActualBudget	None (file)	50M / 256M	yes	--	budget.*
Docmost	PostgreSQL + Redis	200M / 768M	no	--	docs.*
FileBrowser	None (file)	30M / 128M	yes	`${HDD_PATH}/storage/filebrowser/`	files.*
Homebox	None (SQLite)	50M / 256M	yes	--	inventory.*
Immich	PostgreSQL + Redis	2048M / 4096M	no	`${HDD_PATH}/storage/immich/`	photos.*
Mealie	None (SQLite)	200M / 1000M	yes	--	recipes.*
Paperless-ngx	PostgreSQL + Redis	500M / 1152M	yes	`${HDD_PATH}/storage/paperless/`	paperless.*
ROMM	MariaDB + Redis	300M / 1024M	no	`${HDD_PATH}/storage/romm/`	arcade.*
Stirling-PDF	None	200M / 512M	yes	--	pdf.*
Vaultwarden	None (SQLite)	50M / 256M	yes	--	vault.*

Variable types per app

App	DOMAIN	HDD_PATH	Secrets
ActualBudget	yes	--	--
Docmost	yes	--	APP_SECRET, DB_PASSWORD
FileBrowser	yes	yes	--
Homebox	yes	--	--
Immich	yes	yes	DB_PASSWORD
Mealie	yes	--	--
Paperless-ngx	yes	yes	PAPERLESS_SECRET_KEY, DB_PASSWORD, PAPERLESS_ADMIN_USER, PAPERLESS_ADMIN_PASSWORD
ROMM	yes	yes	DB_PASSWORD, MYSQL_ROOT_PASSWORD, ROMM_AUTH_SECRET_KEY
Stirling-PDF	yes	--	--
Vaultwarden	yes	--	ADMIN_TOKEN

Storage strategy

HDD host paths (${HDD_PATH}/storage/...): Large user data — photos, documents, ROMs
Named Docker volumes (on internal SSD): Databases, app config, caches — need fast I/O
Templates without ${HDD_PATH} work without an external HDD (e.g., ActualBudget, Mealie)

Docker Compose template standards

All templates follow these standards (enforced via audit):

${DOMAIN} variable syntax for all domain references (not hardcoded)
deploy.resources.limits.memory on every service container
Healthchecks on every service (appropriate for service type)
restart: unless-stopped on every service
TZ=Europe/Budapest on every service
traefik-public external network + internal network for DB services
Explicit container_name: on every service
Header comment block with: app name, domain, DB type, RAM, Pi compatibility
depends_on with condition: service_healthy for DB/Redis dependencies

Legacy: Portainer-based deployments

The generate-customer.sh script and templates.json are kept for Portainer-only setups where the felhom-controller is not used. For controller-based deployments, these are not needed.

Legacy workflow

# Generate customer templates (on your workstation)
./scripts/generate-customer.sh --customer demo-felhom \
    --domain demo-felhom.eu --hdd-path /mnt/hdd_1 --push

Adding a New App

Create templates/<appname>/docker-compose.yml following the template standards above
Create templates/<appname>/.felhom.yml following the metadata format
Commit and push — the controller will pick it up on next sync
(Legacy) If also needed for Portainer: add entry to templates.json and generate-customer.sh

Repository	Purpose
app-catalog-felhom.eu	This repo — templates + metadata
deploy-felhom-compose	felhom-controller + deploy scripts
felhom.eu	Website + k3s manifests

README.md

Felhom App Catalog

Architecture