deploy-felhom-compose/CONTEXT.md

CONTEXT.md — Project Memory

This file serves as persistent project memory across Claude Code sessions. It replaces the auto-generated "Memory" from the claude.ai Project. Update this file at the end of each working session with current state, recent decisions, and anything the next session needs to know.

Ask Claude Code: "Please update CONTEXT.md with what we did today"

Last updated: 2026-02-14

---

About Viktor (project owner)

• Works at Magyar Telekom (Budapest), building Felhom as a side business
• Felhom: managed home-server service for Hungarian households
• Technical but prefers pragmatic solutions over over-engineering
• Runs all infrastructure on Gitea (gitea.dooplex.hu), k3s cluster for management
• Customer deployments use Docker Compose (not Kubernetes) for simplicity

Current project state

felhom-controller (this repo)

• Version: v0.2.1
• Phase 1: ✅ COMPLETE — Stack Manager + Deploy Flow
• First app deployed: Paperless-ngx on demo-felhom.eu (2026-02-13)
• Running on: demo-felhom (N100 mini PC) at 192.168.0.162:8080
• All Phase 1 features working: deploy, start/stop/restart/update, logs, health-aware states, auth

What was just completed (2026-02-13/14)

• Built the entire felhom-controller from scratch (Go, no frameworks)
• Debugged and fixed 7 issues during first real deployment:
  1. Password validation (empty passwords accepted)
  2. In-memory Deployed flag not updating after deploy
  3. Health-aware state parsing (starting/unhealthy detection)
  4. Random card ordering (Go map iteration)
  5. "Részletek" button redirect for deployed apps
  6. Paperless OCR language installation (LANGUAGES vs LANGUAGE env var)
  7. Documentation: restart vs up -d for image updates
• Controller image builds via build.sh, pushes to Gitea container registry

What's next (priorities)

1. Deploy a second app (e.g., Immich, Jellyfin) to validate the template system
2. Test on Raspberry Pi (pi-customer-1)
3. Phase 2: Monitoring & Healthchecks integration
4. Phase 3: Backup system (DB dumps + restic)
5. Dashboard dark theme (align with felhom.eu website)

Architecture decisions

Decision	Rationale
Go stdlib for web (no Gin/Echo)	Minimal dependencies, single binary, easy to embed templates
Templates as Go string constants	Zero runtime file dependencies, everything in the binary
Docker Compose for customers (not k8s)	Simpler troubleshooting, customers don't need k8s knowledge
k3s for management infra only	Viktor's own services (gitea, monitoring, website) run on k3s
Cloudflare Tunnel for remote access	No port forwarding needed, works behind any NAT
app.yaml per stack	Separates deploy config from compose files, survives git pulls
Password fields require explicit input	Prevents accidental empty-password deployments
Health-aware state from Docker Status field	Docker's State says "running" even for unhealthy containers

Key file locations on demo-felhom

/opt/docker/felhom-controller/         # Controller compose + config
  ├── controller.yaml                  # Customer config (domain, auth, paths)
  ├── docker-compose.yml               # Controller's own compose
  └── .env                             # DOMAIN=demo-felhom.eu

/opt/docker/stacks/                    # All app stacks
  ├── traefik/                         # Reverse proxy (protected)
  ├── cloudflared/                     # Tunnel (protected)
  ├── paperless-ngx/                   # First deployed app ✅
  │   ├── docker-compose.yml
  │   ├── .felhom.yml                  # App metadata
  │   └── app.yaml                     # Deploy config (env vars, locked fields)
  └── whoami/                          # Test stack (not deployed)

/mnt/hdd_placeholder/storage/          # HDD storage for apps
  └── paperless/
      ├── consume/                     # Drop files here for OCR
      ├── media/                       # Processed documents
      └── export/                      # Backup exports

Related repositories and their state

Repository	Status	Notes
deploy-felhom-compose	Active	This repo. Controller code + deploy scripts
app-catalog-felhom.eu	Active	49 app templates, needs PAPERLESS_OCR_LANGUAGES fix
felhom.eu	Stable	Website live, SEO indexed, email working
homelab-manifests	Stable	k3s cluster running (dooplex.hu services)
misc-scripts	Utility	collect-repo.sh, backup helpers

Gotchas & lessons learned

• docker compose restart ≠ docker compose up -d — restart doesn't pick up new images
• Go maps have random iteration order — always sort slices before displaying
• Docker .State="running" doesn't mean healthy — check .Status for "(health: starting)" / "(unhealthy)"
• Paperless-ngx needs PAPERLESS_OCR_LANGUAGES (plural) to install language packs, PAPERLESS_OCR_LANGUAGE (singular) to select
• After deploying a stack, update the in-memory Deployed flag immediately — RefreshStatus() only reads docker ps
• Cloudflare Tunnel handles *.demo-felhom.eu → Traefik handles Host()-based routing to containers
• BIOS "AC Power Recovery" must be enabled on N100 for auto-restart after power outage