Felhom App Catalog

Central repository for all Felhom customer application deployments.

Architecture

felhom-app-catalog/
├── templates/              # Docker Compose templates ({{DOMAIN}} placeholder)
│   ├── actualbudget/
│   ├── docmost/
│   ├── filebrowser/
│   ├── homebox/
│   ├── immich/
│   ├── mealie/
│   ├── romm/
│   ├── stirling-pdf/
│   └── vaultwarden/
├── customers/              # Per-customer configuration
│   ├── demo-felhom.yaml
│   └── pi-customer-1.yaml
├── scripts/
│   └── render.sh           # Renders customer repos from templates
└── README.md

How It Works

Templates contain Docker Compose files with {{DOMAIN}} placeholders
Customer configs define which apps each customer gets + any version overrides
render.sh generates per-customer Gitea repos with domain-substituted compose files
Portainer GitOps on each customer node pulls from their repo and deploys

Workflow

Adding a new app to the catalog

Create templates/<appname>/docker-compose.yml using {{DOMAIN}} placeholder
Add to relevant customer configs in customers/
Run ./scripts/render.sh to regenerate customer repos

Updating an app version

Edit the image tag in templates/<appname>/docker-compose.yml
Run ./scripts/render.sh — skips customers with version overrides
Portainer auto-detects git changes and redeploys (if polling enabled)

Adding a new customer

Create customers/<customer-id>.yaml
Create the Gitea repo: customers/<customer-id>-stacks
Run ./scripts/render.sh --customer <customer-id>
Set up Portainer GitOps stacks on the customer node

Portainer Stack Setup (per app)

On the customer's Portainer:

Stacks → Add Stack → Repository
Repository URL: https://gitea.felhom.eu/customers/<customer-id>-stacks
Compose path: <appname>/docker-compose.yml
Add environment variables (secrets — DB passwords, API keys, etc.)
Enable GitOps auto-update (optional, 5-minute polling)
Deploy

Environment Variables

Secrets are never stored in Git. They live in Portainer's stack environment variables on each customer node. Each template documents required env vars in comments at the top of the compose file.

Version Pinning

In a customer YAML, you can pin specific app versions:

overrides:
  immich_version: "v2.4.1"    # Don't auto-update Immich for this customer
  auto_update: false            # Skip ALL updates for this customer

App Catalog

App	DB Type	RAM Usage	Pi-Compatible	Description
ActualBudget	None (file)	~50MB	✅	Personal finance / budgeting
Docmost	PostgreSQL + Redis	~200MB	⚠️ (heavy)	Wiki / documentation (Notion-like)
FileBrowser	None (file)	~30MB	✅	Web file manager
Homebox	None (SQLite)	~50MB	✅	Home inventory management
Immich	PostgreSQL + Redis	~4GB	❌	Photo & video management
Mealie	None (SQLite)	~200MB	✅	Recipe manager & meal planner
ROMM	MariaDB + Redis	~300MB	⚠️	ROM / game library manager
Stirling-PDF	None	~200MB	✅	PDF manipulation toolkit
Vaultwarden	None (SQLite)	~50MB	✅	Password manager (Bitwarden)

3.3 KiB Raw Blame History