Teststand

deploy/quadlet/README.md

@@ -0,0 +1,102 @@
+# Quadlet Templates (AlmaLinux + Podman)
+
+Files:
+- `kubeviz.container`: system-level Quadlet unit template
+- `kubeviz-traefik.container`: direct Traefik-label variant (shared Podman network)
+- `traefik.network`: optional shared network Quadlet
+- `kubeviz.env.example`: optional external environment file
+
+## 1. Install template
+
+```bash
+sudo mkdir -p /etc/containers/systemd
+sudo cp deploy/quadlet/kubeviz.container /etc/containers/systemd/kubeviz.container
+```
+
+Alternative (Traefik-label mode):
+
+```bash
+sudo cp deploy/quadlet/traefik.network /etc/containers/systemd/traefik.network
+sudo cp deploy/quadlet/kubeviz-traefik.container /etc/containers/systemd/kubeviz.container
+```
+
+Optional env file:
+
+```bash
+sudo mkdir -p /etc/kubeviz
+sudo cp deploy/quadlet/kubeviz.env.example /etc/kubeviz/kubeviz.env
+# then uncomment EnvironmentFile in kubeviz.container
+```
+
+## 2. Set real image
+
+Edit `/etc/containers/systemd/kubeviz.container` and replace:
+- `ghcr.io/REPLACE_ME/kubeviz:v0.1.0`
+
+For Gitea CI/CD without external registry, use a stable local tag:
+
+```ini
+Image=localhost/kubeviz:prod
+Pull=never
+```
+
+## 3. Start service
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now kubeviz.service
+sudo systemctl status kubeviz.service
+sudo journalctl -u kubeviz.service -f
+```
+
+## 4. Update rollout
+
+```bash
+sudo systemctl restart kubeviz.service
+```
+
+Because `Pull=always` is set, Podman will pull the latest image for the configured tag on restart.
+
+## 5. Traefik integration
+
+Route `kubeviz.valtrix.systems` to `http://127.0.0.1:18080`.
+Keep `COOKIE_SECURE=true` in production.
+
+If you use `kubeviz-traefik.container`, Traefik discovers KubeViz via labels and the shared `traefik` network instead of localhost port mapping.
+
+## 6. Gitea pipeline (direct deploy on server)
+
+Workflow template is included at:
+- `.gitea/workflows/deploy-kubeviz.yml`
+- `scripts/deploy-with-podman.sh`
+
+The deploy script builds with Podman, tags `localhost/kubeviz:prod`, and restarts `kubeviz.service`.
+
+Required sudo permissions for the Gitea runner user (example):
+
+```text
+gitea-runner ALL=(root) NOPASSWD:/usr/bin/podman build *,/usr/bin/podman tag *,/usr/bin/systemctl restart kubeviz.service,/usr/bin/systemctl is-active kubeviz.service
+```
+
+The user must be the one that executes the Gitea Actions runner service (often `gitea-runner`).
+Check it with:
+
+```bash
+systemctl cat gitea-runner | grep -E '^User='
+```
+
+For BasicAuth labels, use htpasswd hashes (not plain passwords), for example:
+
+```bash
+htpasswd -nB smb
+```
+
+Then set the generated value in:
+- `traefik.http.middlewares.kubeviz-auth.basicauth.users=smb:<hash>`
+
+After updating sudoers:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart gitea-runner
+```