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

sudo mkdir -p /etc/containers/systemd
sudo cp deploy/quadlet/kubeviz.container /etc/containers/systemd/kubeviz.container

Alternative (Traefik-label mode):

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:

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:

Image=localhost/kubeviz:prod
Pull=never

3. Start service

sudo systemctl daemon-reload
sudo systemctl enable --now kubeviz.service
sudo systemctl status kubeviz.service
sudo journalctl -u kubeviz.service -f

4. Update rollout

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. The workflow uses git checkout (no Node runtime dependency). For private repos, set Gitea secret CI_REPO_TOKEN. For private base images (for example dhi.io/golang:*), ensure the runner user is logged in with Podman and has an auth file at either:

$XDG_RUNTIME_DIR/containers/auth.json or
$HOME/.config/containers/auth.json

The deploy script forwards REGISTRY_AUTH_FILE to sudo podman automatically.

Required sudo permissions for the Gitea runner user (example):

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:

systemctl cat gitea-runner | grep -E '^User='

For BasicAuth labels, use htpasswd hashes (not plain passwords), for example:

htpasswd -nB smb

Then set the generated value in:

traefik.http.middlewares.kubeviz-auth.basicauth.users=smb:<hash>

After updating sudoers:

sudo systemctl daemon-reload
sudo systemctl restart gitea-runner

3.1 KiB Raw Blame History