admin/deploy-felhom-compose
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated CLAUDE.md and TASK.md

Browse Source
This commit is contained in:
authentik Default Admin
2026-02-14 20:00:24 +01:00
parent a8096faf59
commit 528f64cab7
2 changed files with 1041 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+107 -31
View File
@@ -12,6 +12,7 @@ Compose stacks on customer hardware via a Hungarian-language web dashboard.
See `controller/README.md` for full architecture and status.
See `CONTEXT.md` for current project state, recent work, and decisions (update after each session).
See `TASK.md` for the current task to implement (if it exists).
Claude in Chrome extension is available — can be used to test web UI on demo-felhom.eu or verify dashboard deployments in browser.
@@ -22,37 +23,49 @@ Claude in Chrome extension is available — can be used to test web UI on demo-f
- Add debug capabilities (logging, verbose output) for easier troubleshooting
- If you need more input or troubleshooting command output, ask first — don't guess
## Repository structure
## Workspace layout
This repo has two main parts:
Claude Code runs on Windows. The working directory is `E:\git\` (mapped as `/e/git/` in Git Bash).
This repo is at:
```
deploy-felhom-compose/
├── controller/ # Go application (this is the main codebase)
│ ├── cmd/controller/ # Entry point (main.go)
E:\git\deploy-felhom-compose\ (or /e/git/deploy-felhom-compose/ in Git Bash)
├── controller/ # Go application (main codebase)
│ ├── cmd/controller/ # Entry point (main.go)
│ ├── internal/
│ │ ├── config/ # YAML config loading
│ │ ├── stacks/ # Docker Compose operations, deploy flow
│ │ ├── sync/ # Git sync — periodic pull of app catalog repo
│ │ ├── api/ # REST API endpoints
│ │ ├── system/ # System info (memory, disk)
│ │ └── web/ # Dashboard UI (embedded HTML/CSS templates)
│ │ ├── config/ # YAML config loading
│ │ ├── stacks/ # Docker Compose operations, deploy flow
│ │ ├── sync/ # Git sync — periodic pull of app catalog repo
│ │ ├── api/ # REST API endpoints
│ │ ├── system/ # System info (memory, disk)
│ │ └── web/ # Dashboard UI (embedded HTML/CSS templates)
│ ├── Dockerfile
│ ├── Makefile
│ └── go.mod
├── scripts/ # Setup scripts for customer nodes
├── CLAUDE.md # This file
└── CONTEXT.md # Project memory / state
├── scripts/ # Setup scripts for customer nodes
├── CLAUDE.md # This file
├── CONTEXT.md # Project memory / state
└── TASK.md # Current task (if exists)
```
## Related repositories (not in this repo)
Related repos (same parent directory):
```
E:\git\app-catalog-felhom.eu\ # Docker Compose templates + .felhom.yml metadata per app
E:\git\felhom.eu\ # Website (htmls) + k3s manifests
E:\git\homelab-manifests\ # k3s cluster manifests (dooplex.hu services)
E:\git\misc-scripts\ # Helper scripts
```
- **app-catalog-felhom.eu** — Docker Compose templates + .felhom.yml metadata per app
- **felhom.eu** — Website (htmls) + k3s manifests for the web server
- **homelab-manifests** — Viktor's k3s cluster manifests (dooplex.hu services)
- **misc-scripts** — Helper scripts for daily tasks
All repos hosted at `gitea.dooplex.hu/admin/`. Git credentials are stored (`git config credential.helper store`).
All hosted at `gitea.dooplex.hu/admin/`
## SSH access
SSH key-based authentication is configured and working. No password prompts.
| Host | IP | User | Role |
|------|----|------|------|
| Build server | 192.168.0.180 | kisfenyo | Build + push container images |
| Demo node | 192.168.0.162 | kisfenyo | Test deployment (demo-felhom.eu) |
## Test environments
@@ -64,20 +77,73 @@ All hosted at `gitea.dooplex.hu/admin/`
- Pi-hole DNS on local network forwards `*.demo-felhom.eu` → 192.168.0.162
- External access via Cloudflare Tunnel → Traefik reverse proxy
## Build & deploy workflow
## Build & deploy workflow — MANDATORY
After making code changes to the controller, you **MUST** build, push, and deploy the new image.
Do NOT leave code changes uncommitted or undeployed. The full cycle is:
### Step 1: Commit and push changes
Code is edited locally on Windows. Build happens on the server via SSH.
```bash
# Push changes
git add -A && git commit -m "..." && git push
# Build + push image on server
ssh kisfenyo@192.168.0.180 "cd ~/build/felhom-controller && git -C ~/git/deploy-felhom-compose pull && ./build.sh --push"
# Deploy on demo node
ssh kisfenyo@192.168.0.162 "cd /opt/docker/felhom-controller && docker pull gitea.dooplex.hu/admin/felhom-controller: && docker compose up -d"
cd /e/git/deploy-felhom-compose
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 version tag should be incremented
from the current running version.
First, check the current running version:
```bash
ssh kisfenyo@192.168.0.162 "docker ps --filter name=felhom-controller --format '{{.Image}}'"
```
Then build with the next version (e.g., if current is 0.2.10, use 0.2.11):
```bash
ssh kisfenyo@192.168.0.180 "cd ~/build/felhom-controller && git -C ~/git/deploy-felhom-compose pull && ./build.sh <NEW_VERSION> --push"
```
The build script:
- Pulls latest code from Gitea
- Builds a multi-arch Docker image (amd64 + arm64) if `--multiarch`, or current arch if `--push`
- Pushes to `gitea.dooplex.hu/admin/felhom-controller:<VERSION>`
- Expects the version as first argument (e.g., `0.2.11`)
### Step 3: Deploy on the demo node
```bash
ssh kisfenyo@192.168.0.162 "cd /opt/docker/felhom-controller && docker pull gitea.dooplex.hu/admin/felhom-controller:<NEW_VERSION> && sed -i 's|felhom-controller:[^ ]*|felhom-controller:<NEW_VERSION>|' docker-compose.yml && docker compose up -d"
```
### Step 4: Verify the deployment
```bash
ssh kisfenyo@192.168.0.162 "docker ps --filter name=felhom-controller --format '{{.Image}} {{.Status}}'"
```
Should show the new version and "Up" status. Also check logs for startup errors:
```bash
ssh kisfenyo@192.168.0.162 "docker logs felhom-controller --tail 20"
```
### Build workflow summary
| Step | Command | Where |
|------|---------|-------|
| 1. Commit + push | `git add -A && git commit -m "..." && git push` | Local (this repo) |
| 2. Build + push image | `ssh 192.168.0.180 "... ./build.sh <VER> --push"` | Build server |
| 3. Deploy | `ssh 192.168.0.162 "... docker compose up -d"` | Demo node |
| 4. Verify | `ssh 192.168.0.162 "docker ps ..."` | Demo node |
**IMPORTANT:** If you make changes to the app-catalog-felhom.eu repo, commit and push those too:
```bash
cd /e/git/app-catalog-felhom.eu
git add -A && git commit -m "<message>" && git push
```
The controller's git sync will pick up catalog changes within 15 minutes, or you can trigger it
manually via the dashboard "Sablonok frissítése" button.
## Tech stack
- **Language:** Go 1.22+
@@ -143,4 +209,14 @@ Key patterns used in `internal/stacks/`:
5. In-memory `Deployed` flag must be set BEFORE `docker compose up -d` (not after) — compose can take 30-60s for image pulls; revert both in-memory and disk on failure
6. `docker compose up -d` returns exit 0 even when containers crash-loop — post-start status check is essential for detecting failures
7. Mealie image has no wget/curl — use Python TCP socket check for healthcheck; set `start_period: 60s` for DB migration time
8. Always verify container images have the healthcheck tool (`wget`, `curl`, etc.) before using it — Alpine has BusyBox wget, Python images have `python3`
8. Always verify container images have the healthcheck tool (`wget`, `curl`, etc.) before using it — Alpine has BusyBox wget, Python images have `python3`
## End-of-session checklist
Before ending a session, always:
1. **Commit and push** all code changes
2. **Build, push, and deploy** the new controller image (if controller code changed)
3. **Update CONTEXT.md** with what was done, decisions made, and what's next
4. **Update controller/README.md** if architecture or features changed
5. **Verify** the deployment is working (check `docker ps` and logs)