felhom.eu/CLAUDE.md

CLAUDE.md — Project Instructions for Claude Code

This file is read automatically by Claude Code at the start of every session. It replaces the "Instructions" panel from the claude.ai Project. Keep it updated as the project evolves.

Project overview

This repo (felhom.eu) contains:

• Website (website/) — Static HTML pages at felhom.eu, served via k3s nginx + git-sync sidecar
• Hub (hub/) — Go application (felhom-hub) — centralized dashboard for monitoring customer controllers, runs on k3s at hub.felhom.eu
• K8s manifests (manifests/) — k3s deployment manifests for all felhom-system services

See README.md for full architecture, DNS, email, and SEO documentation. See TASK.md for the current task to implement (if it exists).

Code quality rules

• Always double-check generated code for bugs, logic issues, syntax errors
• Handle edge cases without overcomplicating the script/program
• Add debug capabilities (logging, verbose output) for easier troubleshooting
• If you need more input or troubleshooting command output, ask first — don't guess

Workspace layout

E:\git\felhom.eu\                  (or /e/git/felhom.eu/ in Git Bash)
├── hub/                           # felhom-hub Go application
│   ├── cmd/hub/                   # Entry point (main.go)
│   ├── internal/
│   │   ├── api/                   # Report ingestion API
│   │   ├── store/                 # SQLite storage + queries
│   │   └── web/                   # Dashboard UI
│   │       ├── server.go          # Server, routing, template funcs
│   │       ├── embed.go           # go:embed for templates
│   │       └── templates/         # HTML templates + CSS
│   ├── configs/                   # Example config files
│   ├── Dockerfile
│   ├── Makefile
│   └── go.mod
├── manifests/                     # k3s deployment manifests
│   ├── hub.yaml                   # Hub deployment (hub.felhom.eu)
│   ├── webpage.yaml               # Website + FileBrowser + git-sync
│   ├── contact-mailer.yaml        # Contact form email sender
│   ├── healthchecks.yaml          # Healthchecks (status.felhom.eu)
│   └── umami.yaml                 # Analytics (stats.felhom.eu)
├── website/                       # Static HTML pages (felhom.eu)
│   ├── index.html
│   ├── alkalmazasok.html
│   ├── ... (all Hungarian, UTF-8 with BOM)
│   └── assets/                    # Logos, screenshots, OG images
├── CLAUDE.md                      # This file
├── README.md                      # Full project documentation
└── TASK.md                        # Current task (if exists)

Related repos (same parent directory):

E:\git\deploy-felhom-compose\     # felhom-controller Go app + deploy scripts
E:\git\app-catalog-felhom.eu\     # Docker Compose templates per app
E:\git\homelab-manifests\         # k3s cluster manifests (dooplex.hu services)
E:\git\misc-scripts\              # Helper scripts (build scripts, repo collector)

All repos hosted at gitea.dooplex.hu/admin/.

SSH access

SSH key-based authentication configured. No password prompts.

Host	IP	User	Role
Build server (k3s node)	192.168.0.180	kisfenyo	Build + push images, kubectl
Demo node	192.168.0.162	kisfenyo	Test deployment (demo-felhom.eu)

Note: kubectl on the build server requires sudo (k3s kubeconfig permissions).

Build & deploy workflow — Hub

After making code changes to hub/, you MUST build, push, and deploy the new image. Do NOT leave code changes uncommitted or undeployed.

Step 1: Commit and push changes

cd /e/git/felhom.eu
git add -A && git commit -m "<descriptive message>" && git push

Step 2: Build + push the container image on the build server

The build server (192.168.0.180) has the build toolchain. The build script lives at ~/build/felhom-hub/build.sh on the build server (NOT in this repo).

First, check the current running version:

ssh kisfenyo@192.168.0.180 "sudo kubectl get deploy -n felhom-system hub -o jsonpath='{.spec.template.spec.containers[0].image}'"

Then build with the next version (e.g., if current is 0.1.2, use 0.1.3):

ssh kisfenyo@192.168.0.180 "cd ~/build/felhom-hub && ./build.sh <NEW_VERSION> --push"

The build script:

• Pulls latest code from Gitea (git pull on the felhom.eu repo)
• Copies hub/ source to a clean build workspace
• Builds Docker image with version + build-time ldflags
• Pushes to gitea.dooplex.hu/admin/felhom-hub:<VERSION> and :latest

Step 3: Deploy to k3s

ssh kisfenyo@192.168.0.180 "sudo kubectl set image -n felhom-system deploy/hub hub=gitea.dooplex.hu/admin/felhom-hub:<NEW_VERSION>"

Step 4: Verify the deployment

ssh kisfenyo@192.168.0.180 "sudo kubectl get pods -n felhom-system -l app=hub && echo '---' && sudo kubectl logs -n felhom-system -l app=hub --tail 10"

Should show pod Running and [INFO] felhom-hub <VERSION> starting in logs.

Build workflow summary

Step	Command	Where
1. Commit + push	git add -A && git commit && git push	Local (this repo)
2. Build + push image	ssh 192.168.0.180 "cd ~/build/felhom-hub && ./build.sh <VER> --push"	Build server
3. Deploy	ssh 192.168.0.180 "sudo kubectl set image -n felhom-system deploy/hub hub=...:<VER>"	Build server (kubectl)
4. Verify	ssh 192.168.0.180 "sudo kubectl get pods -n felhom-system -l app=hub"	Build server

Build & deploy workflow — Website

The website auto-deploys via git-sync sidecar. Just push to main:

cd /e/git/felhom.eu
git add -A && git commit -m "<message>" && git push

Changes are live within 1-2 minutes. No build step needed.

For emergency edits, use FileBrowser at https://files.felhom.eu.

Build & deploy workflow — K8s Manifests

Manifests are applied manually:

ssh kisfenyo@192.168.0.180 "sudo kubectl apply -f /home/kisfenyo/git/felhom.eu/manifests/<manifest>.yaml"

Remember to git pull on the build server first if you pushed changes locally.

Tech stack (Hub)

• Language: Go 1.24+
• Web framework: stdlib net/http + html/template
• Database: SQLite via modernc.org/sqlite (pure Go, no CGo)
• Auth: bcrypt password hash + basic auth
• Deployment: Docker container on k3s (felhom-system namespace)
• Storage: Longhorn PVC at /data/ (SQLite DB)
• Config: YAML file mounted via k8s ConfigMap at /etc/felhom-hub/hub.yaml

Key patterns

• Hub receives reports from customer controllers via POST /api/v1/report (Bearer token auth)
• Dashboard shows all customers in a table with status, CPU, memory, disk, containers, backup age
• Customer detail page shows system info, report history, full JSON report
• Status logic: OK (report < 30m), WARN (30m-1h or health=warn), DOWN (> 1h or health=fail)
• SQLite timestamps may vary in format — use parseSQLiteTime() for robust parsing
• Auto-refresh: dashboard and detail pages refresh every 60 seconds via <meta http-equiv="refresh">
• Geo-restricted to Hungary via nginx ingress annotation

File encoding

All HTML files in website/ are UTF-8 with BOM. Ensure your editor preserves this. Hub Go source files are standard UTF-8 (no BOM).