restructured files, and updated for build outside
This commit is contained in:
+120
-151
@@ -1,160 +1,121 @@
|
||||
# Building & Publishing felhom-controller
|
||||
|
||||
## Prerequisites
|
||||
## Repository layout
|
||||
|
||||
- Docker installed on your build machine
|
||||
- Docker Buildx plugin (for multi-arch builds — included with Docker Desktop, may need install on Linux)
|
||||
- Access to Gitea at gitea.dooplex.hu
|
||||
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)
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
Gitea has a built-in container registry. Check if it's enabled:
|
||||
Check if Gitea's package registry is enabled:
|
||||
|
||||
```bash
|
||||
# SSH into your k3s node or wherever Gitea runs
|
||||
# Check Gitea config (app.ini)
|
||||
# Look for [packages] section in Gitea config
|
||||
kubectl exec -it -n <namespace> deploy/gitea -- cat /data/gitea/conf/app.ini | grep -A5 '\[packages\]'
|
||||
```
|
||||
|
||||
If the `[packages]` section is missing or `ENABLED=false`, add/update:
|
||||
If missing or `ENABLED=false`, add to `app.ini`:
|
||||
|
||||
```ini
|
||||
[packages]
|
||||
ENABLED = true
|
||||
```
|
||||
|
||||
Then restart Gitea:
|
||||
Restart Gitea, then verify:
|
||||
|
||||
```bash
|
||||
kubectl rollout restart deploy/gitea -n <namespace>
|
||||
```
|
||||
|
||||
**Verify it works:**
|
||||
|
||||
```bash
|
||||
# Login to the registry (use your Gitea username + password or access token)
|
||||
docker login gitea.dooplex.hu
|
||||
# Username: admin
|
||||
# Password: <your-gitea-password-or-token>
|
||||
```
|
||||
|
||||
If login succeeds, the registry is working. The image URL pattern is:
|
||||
`gitea.dooplex.hu/<owner>/<image>:<tag>`
|
||||
|
||||
## Step 2: Sync app assets before building
|
||||
|
||||
The container image includes app logos and screenshots. Sync them from
|
||||
the felhom.eu website repo before building:
|
||||
## Step 2: Build the image
|
||||
|
||||
```bash
|
||||
# If the website repo is checked out alongside this repo:
|
||||
make sync-assets
|
||||
cd ~/build/felhom-controller
|
||||
|
||||
# Or specify the path explicitly:
|
||||
make sync-assets WEBSITE_ASSETS_DIR=/home/admin/repos/felhom.eu/website/assets
|
||||
# Local build (quick test, current arch only)
|
||||
./build.sh 0.1.0
|
||||
|
||||
# Verify
|
||||
ls assets/*.webp
|
||||
# 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
|
||||
```
|
||||
|
||||
If you skip this step, the dashboard will work but show no app logos/screenshots
|
||||
(the `onerror` handler hides broken images gracefully).
|
||||
### What the build script does
|
||||
|
||||
## Step 3: Build for single architecture (quick test)
|
||||
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:
|
||||
|
||||
```bash
|
||||
cd ~/repos/deploy-felhom-compose
|
||||
|
||||
# Build for your current architecture
|
||||
docker build \
|
||||
--build-arg VERSION=$(git describe --tags --always 2>/dev/null || echo "0.1.0") \
|
||||
--build-arg GIT_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown") \
|
||||
-t gitea.dooplex.hu/admin/felhom-controller:latest \
|
||||
-t gitea.dooplex.hu/admin/felhom-controller:0.1.0 \
|
||||
.
|
||||
|
||||
# Push
|
||||
docker push gitea.dooplex.hu/admin/felhom-controller:latest
|
||||
docker push gitea.dooplex.hu/admin/felhom-controller:0.1.0
|
||||
REPO_DIR="/home/kisfenyo/git/deploy-felhom-compose"
|
||||
CONTROLLER_SRC="${REPO_DIR}/controller"
|
||||
WEBSITE_ASSETS_DIR="/home/kisfenyo/git/felhom.eu/website/assets"
|
||||
```
|
||||
|
||||
## Step 4: Build for both architectures (production)
|
||||
|
||||
You need both amd64 (N100 mini PCs) and arm64 (Raspberry Pi). Use Docker Buildx:
|
||||
## Step 3: Deploy on a customer node
|
||||
|
||||
```bash
|
||||
# One-time: Create a buildx builder that supports multi-arch
|
||||
docker buildx create --name felhom-builder --use --bootstrap
|
||||
|
||||
# Verify it supports the architectures we need
|
||||
docker buildx inspect felhom-builder
|
||||
# Should show: linux/amd64, linux/arm64 in Platforms
|
||||
|
||||
# Build + push multi-arch image in one step
|
||||
docker buildx build \
|
||||
--platform linux/amd64,linux/arm64 \
|
||||
--build-arg VERSION=0.1.0 \
|
||||
--build-arg GIT_COMMIT=$(git rev-parse --short HEAD) \
|
||||
-t gitea.dooplex.hu/admin/felhom-controller:latest \
|
||||
-t gitea.dooplex.hu/admin/felhom-controller:0.1.0 \
|
||||
--push \
|
||||
.
|
||||
```
|
||||
|
||||
**Note:** `--push` is required with multi-arch builds because buildx doesn't store
|
||||
multi-platform images in the local Docker cache. It pushes directly to the registry.
|
||||
|
||||
### If buildx multi-arch doesn't work (missing QEMU)
|
||||
|
||||
On Linux you might need QEMU for cross-compilation:
|
||||
|
||||
```bash
|
||||
# Install QEMU user-mode emulation
|
||||
sudo apt-get install -y qemu-user-static binfmt-support
|
||||
|
||||
# Register QEMU with Docker
|
||||
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
|
||||
|
||||
# Verify
|
||||
docker buildx ls
|
||||
```
|
||||
|
||||
### Alternative: Build natively on each architecture
|
||||
|
||||
If you don't want to cross-compile, build on each machine:
|
||||
|
||||
```bash
|
||||
# On the N100 (amd64):
|
||||
docker build -t gitea.dooplex.hu/admin/felhom-controller:latest-amd64 .
|
||||
docker push gitea.dooplex.hu/admin/felhom-controller:latest-amd64
|
||||
|
||||
# On the Pi (arm64):
|
||||
docker build -t gitea.dooplex.hu/admin/felhom-controller:latest-arm64 .
|
||||
docker push gitea.dooplex.hu/admin/felhom-controller:latest-arm64
|
||||
|
||||
# Then create a manifest list to combine them:
|
||||
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
|
||||
```
|
||||
|
||||
## Step 5: Deploy on a customer node
|
||||
|
||||
On the customer's machine, the docker-compose.yml for the controller references
|
||||
the image from the registry:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
felhom-controller:
|
||||
image: gitea.dooplex.hu/admin/felhom-controller:latest
|
||||
# ...
|
||||
```
|
||||
|
||||
Pull and start:
|
||||
|
||||
```bash
|
||||
# Login to registry on the customer node (one-time)
|
||||
# Login to registry (one-time)
|
||||
docker login gitea.dooplex.hu
|
||||
|
||||
# Start the controller
|
||||
@@ -167,60 +128,68 @@ docker compose logs -f
|
||||
curl -s http://localhost:8080/api/health
|
||||
```
|
||||
|
||||
## Step 6: Updating the controller
|
||||
|
||||
When you release a new version:
|
||||
## Step 4: Updating the controller
|
||||
|
||||
```bash
|
||||
# On your build machine:
|
||||
docker buildx build \
|
||||
--platform linux/amd64,linux/arm64 \
|
||||
--build-arg VERSION=0.2.0 \
|
||||
-t gitea.dooplex.hu/admin/felhom-controller:latest \
|
||||
-t gitea.dooplex.hu/admin/felhom-controller:0.2.0 \
|
||||
--push .
|
||||
# On build machine: build new version
|
||||
cd ~/build/felhom-controller
|
||||
./build.sh 0.2.0 --push # or --multiarch
|
||||
|
||||
# On the customer node (manually for now; auto-update comes in Phase 5):
|
||||
# On customer node: pull and restart
|
||||
cd /opt/docker/felhom-controller
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Makefile shortcuts
|
||||
## Multi-arch notes
|
||||
|
||||
The Makefile has convenience targets:
|
||||
### QEMU setup (if cross-compiling on amd64)
|
||||
|
||||
```bash
|
||||
make docker-build # Build for current platform
|
||||
make docker-buildx # Build multi-arch + push
|
||||
make docker-push # Push current platform image
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
docker logout gitea.dooplex.hu
|
||||
docker login gitea.dooplex.hu
|
||||
docker logout gitea.dooplex.hu && docker login gitea.dooplex.hu
|
||||
```
|
||||
|
||||
### Gitea registry not accessible
|
||||
Check if Gitea's HTTPS is working and the domain resolves:
|
||||
### Gitea registry not reachable
|
||||
```bash
|
||||
curl -v https://gitea.dooplex.hu/v2/
|
||||
# Should return: {"errors":[{"code":"UNAUTHORIZED",...}]}
|
||||
```
|
||||
|
||||
### Build fails on arm64 via QEMU (too slow or errors)
|
||||
Cross-compiling Go via QEMU can be slow. Since the Go binary itself is cross-compiled
|
||||
(CGO_ENABLED=0), only the Debian packages in the runtime stage need QEMU.
|
||||
Alternative: build the Go binary natively, then build only the runtime Docker layer
|
||||
via buildx.
|
||||
### Structure check fails
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
### Image too large
|
||||
Expected sizes:
|
||||
### Expected image size
|
||||
- Go binary: ~15-20 MB
|
||||
- Runtime image (debian-slim + docker-cli + restic + pg_dump): ~250-350 MB
|
||||
|
||||
To reduce: consider Alpine instead of Debian slim, but test pg_dump/mysqldump
|
||||
compatibility first.
|
||||
- Runtime (debian-slim + docker-cli + restic + pg_dump): ~250-350 MB
|
||||
- Assets (logos + screenshots): ~20-30 MB
|
||||
- **Total: ~300-400 MB**
|
||||
Reference in New Issue
Block a user