Felhom App Catalog

Central repository for Felhom customer application templates.

Architecture

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:

1. Controller periodically pulls this repo (configurable interval, default 15m)
2. Copies docker-compose.yml and .felhom.yml from templates/<app>/ to /opt/docker/stacks/<app>/
3. Never overwrites app.yaml (deployed config/secrets) or .env files
4. Only copies files if content has actually changed (SHA-256 comparison)
5. After sync, triggers a stack rescan so new/updated apps appear on the dashboard
6. 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

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

Related Repositories

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