added app-catalog

2026-02-11 20:27:53 +01:00
commit 82a8c8b6cf
14 changed files with 1230 additions and 0 deletions
@@ -0,0 +1,90 @@
+# 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
+
+1. **Templates** contain Docker Compose files with `{{DOMAIN}}` placeholders
+2. **Customer configs** define which apps each customer gets + any version overrides
+3. **render.sh** generates per-customer Gitea repos with domain-substituted compose files
+4. **Portainer GitOps** on each customer node pulls from their repo and deploys
+
+## Workflow
+
+### Adding a new app to the catalog
+1. Create `templates/<appname>/docker-compose.yml` using `{{DOMAIN}}` placeholder
+2. Add to relevant customer configs in `customers/`
+3. Run `./scripts/render.sh` to regenerate customer repos
+
+### Updating an app version
+1. Edit the image tag in `templates/<appname>/docker-compose.yml`
+2. Run `./scripts/render.sh` — skips customers with version overrides
+3. Portainer auto-detects git changes and redeploys (if polling enabled)
+
+### Adding a new customer
+1. Create `customers/<customer-id>.yaml`
+2. Create the Gitea repo: `customers/<customer-id>-stacks`
+3. Run `./scripts/render.sh --customer <customer-id>`
+4. Set up Portainer GitOps stacks on the customer node
+
+## Portainer Stack Setup (per app)
+
+On the customer's Portainer:
+1. **Stacks → Add Stack → Repository**
+2. Repository URL: `https://gitea.felhom.eu/customers/<customer-id>-stacks`
+3. Compose path: `<appname>/docker-compose.yml`
+4. Add environment variables (secrets — DB passwords, API keys, etc.)
+5. Enable **GitOps auto-update** (optional, 5-minute polling)
+6. 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:
+
+```yaml
+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) |