deploy-felhom-compose/controller/BUILDING.md

Building & Publishing felhom-controller

Repository layout

Source lives in the controller/ subfolder of the deploy-felhom-compose repo:

https://gitea.dooplex.hu/admin/deploy-felhom-compose
└── controller/
    ├── cmd/controller/main.go
    ├── internal/
    │   ├── config/config.go
    │   ├── stacks/{manager,metadata,deploy}.go
    │   ├── api/router.go
    │   └── web/{server,templates}.go
    ├── configs/
    ├── scripts/
    ├── assets/            ← logos + screenshots (gitignored, synced at build)
    ├── Dockerfile
    ├── go.mod
    └── Makefile

Important: Go files must be in their package subdirectories. If all .go files are flat in controller/, run the restructure script first (see Step 0).

Build setup

Git repo: /home/kisfenyo/git/deploy-felhom-compose Build dir: /home/kisfenyo/build/felhom-controller/ (outside the repo — keeps it clean)

# One-time: create build directory and copy the build script
mkdir -p ~/build/felhom-controller
cp build.sh ~/build/felhom-controller/
chmod +x ~/build/felhom-controller/build.sh

Step 0: Fix directory structure (one-time, if files are flat)

If all .go files are in controller/ without subdirectories:

cd ~/git/deploy-felhom-compose/controller
bash restructure.sh
# Verify it compiles
go mod tidy && go build ./cmd/controller/
# Commit the restructured layout
git add -A
git commit -m "Restructure controller into Go package directories"
git push
# Clean up
rm restructure.sh

Step 1: Enable Gitea Container Registry

Check if Gitea's package registry is enabled:

# Look for [packages] section in Gitea config
kubectl exec -it -n <namespace> deploy/gitea -- cat /data/gitea/conf/app.ini | grep -A5 '\[packages\]'

If missing or ENABLED=false, add to app.ini:

[packages]
ENABLED = true

Restart Gitea, then verify:

docker login gitea.dooplex.hu
# Username: admin
# Password: <your-gitea-password-or-token>

Step 2: Build the image

cd ~/build/felhom-controller

# Local build (quick test, current arch only)
./build.sh 0.1.0

# Build + push to Gitea registry
./build.sh 0.1.0 --push

# Build for both amd64 (N100) + arm64 (Pi) and push
./build.sh 0.1.0 --multiarch

What the build script does

1. Copies controller/ from the git repo into workspace/ (temp directory)
2. Verifies Go package directory structure
3. Syncs app assets (logos, screenshots) from felhom.eu/website/assets/
4. Runs go mod tidy if Go is installed locally
5. Runs docker build (or docker buildx build for multi-arch)

Build artifacts live in ~/build/felhom-controller/workspace/ — your git repo stays clean.

Configuration

Edit the top of build.sh if your paths differ:

REPO_DIR="/home/kisfenyo/git/deploy-felhom-compose"
CONTROLLER_SRC="${REPO_DIR}/controller"
WEBSITE_ASSETS_DIR="/home/kisfenyo/git/felhom.eu/website/assets"

Step 3: Deploy on a customer node

# Login to registry (one-time)
docker login gitea.dooplex.hu

# Start the controller
cd /opt/docker/felhom-controller
docker compose pull
docker compose up -d

# Verify
docker compose logs -f
curl -s http://localhost:8080/api/health

Step 4: Updating the controller

# On build machine: build new version
cd ~/build/felhom-controller
./build.sh 0.2.0 --push   # or --multiarch

# On customer node: pull and restart
cd /opt/docker/felhom-controller
docker compose pull
docker compose up -d

Multi-arch notes

QEMU setup (if cross-compiling on amd64)

sudo apt-get install -y qemu-user-static binfmt-support
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
docker buildx ls   # should show linux/amd64, linux/arm64

Alternative: build natively on each architecture

# On N100 (amd64):
./build.sh 0.1.0 --push

# On Pi (arm64):
./build.sh 0.1.0 --push

# Then create manifest:
docker manifest create gitea.dooplex.hu/admin/felhom-controller:latest \
    gitea.dooplex.hu/admin/felhom-controller:latest-amd64 \
    gitea.dooplex.hu/admin/felhom-controller:latest-arm64
docker manifest push gitea.dooplex.hu/admin/felhom-controller:latest

Troubleshooting

"unauthorized" when pushing

docker logout gitea.dooplex.hu && docker login gitea.dooplex.hu

Gitea registry not reachable

curl -v https://gitea.dooplex.hu/v2/
# Should return: {"errors":[{"code":"UNAUTHORIZED",...}]}

Structure check fails

# The build script verifies package dirs exist. If it fails:
cd ~/git/deploy-felhom-compose/controller
ls -la cmd/controller/ internal/config/ internal/stacks/ internal/api/ internal/web/
# If these don't exist, run restructure.sh first

Expected image size

• Go binary: ~15-20 MB
• Runtime (debian-slim + docker-cli + restic + pg_dump): ~250-350 MB
• Assets (logos + screenshots): ~20-30 MB
• Total: ~300-400 MB