# 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) |