likwid/docs/admin/opensuse-operator-kit.md

openSUSE Operator Kit (container-first)

This guide describes a practical, operator-first way to run Likwid on openSUSE Leap using Podman (rootless) and a reverse proxy that is already present.

Assumptions

• You have an SSH-accessible server running openSUSE Leap.
• You run Likwid as a dedicated non-root user (recommended: deploy).
• A reverse proxy (Caddy/nginx) terminates TLS and forwards:
  • / to the frontend
  • /api to the backend
• You operate via podman compose.

Recommended directory layout

Use a predictable directory layout under the deploy user:

• ~/likwid/ (git checkout)
• ~/likwid/compose/.env.production (production env)
• ~/likwid/compose/.env.demo (demo env)
• ~/likwid/backups/ (operator-managed backups)

Install required packages (openSUSE)

Install Podman and Git:

sudo zypper in -y podman git

Verify podman compose is available:

podman compose version

If your Podman build does not provide podman compose, install the compose integration package available for your openSUSE release.

Initial bootstrap (production)

1. Clone the repository as the deploy user:

git clone https://codeberg.org/likwid/likwid.git ~/likwid

1. Create the production env file:

cp ~/likwid/compose/.env.production.example ~/likwid/compose/.env.production

1. Edit ~/likwid/compose/.env.production:

• POSTGRES_PASSWORD
• JWT_SECRET
• API_BASE (should be your public URL, e.g. https://your.domain)
• TRUSTED_PROXY_IPS (if your reverse proxy does not connect from loopback)

1. Start services:

cd ~/likwid
podman compose --env-file compose/.env.production -f compose/production.yml up -d --build

1. Create the first admin and complete setup:

• Register the first user at /register (first user becomes platform admin)
• Complete /setup

Demo deployment on the VPS

If you operate the public demo style deployment:

cd ~/likwid
podman compose --env-file compose/.env.demo -f compose/demo.yml -f compose/demo.vps.override.yml up -d --build

Health check (backend):

curl -fsS http://127.0.0.1:3001/health

Upgrade procedure (safe, repeatable)

Use a fetch + hard reset strategy to keep the server in a known state:

cd ~/likwid
git fetch origin
git reset --hard origin/main
podman compose --env-file compose/.env.demo -f compose/demo.yml -f compose/demo.vps.override.yml up -d --build

For production deployments, swap the compose files/env file accordingly.

Rollback to a known commit

If an upgrade fails, roll back to a previously known-good commit:

cd ~/likwid
git fetch origin
git reset --hard <KNOWN_GOOD_COMMIT>
podman compose --env-file compose/.env.demo -f compose/demo.yml -f compose/demo.vps.override.yml up -d --build

Log inspection

Container logs:

podman logs -f likwid-demo-backend
podman logs -f likwid-demo-frontend
podman logs -f likwid-demo-db

Container status:

podman ps

Firewall and port exposure

• Prefer binding backend/frontend ports to 127.0.0.1 and letting your reverse proxy access them locally.
• Publicly expose only 80/tcp and 443/tcp.
• If your compose file binds services on 0.0.0.0, restrict access via firewall rules.

Start services on boot (systemd user service)

Podman is most reliable on openSUSE when managed as a rootless user service.

1. Enable lingering for the deploy user so services can run without an active SSH session:

sudo loginctl enable-linger deploy

1. Create a systemd user unit:

• File: ~/.config/systemd/user/likwid-demo.service

• Template: systemd/likwid-demo.service (from this repo)

[Unit]
Description=Likwid demo (podman compose)
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=%h/likwid
ExecStart=/usr/bin/podman compose --env-file compose/.env.demo -f compose/demo.yml -f compose/demo.vps.override.yml up -d
ExecStop=/usr/bin/podman compose --env-file compose/.env.demo -f compose/demo.yml -f compose/demo.vps.override.yml down
TimeoutStartSec=0

[Install]
WantedBy=default.target

1. Enable and start it:

systemctl --user daemon-reload
systemctl --user enable --now likwid-demo.service

1. Inspect service logs:

journalctl --user -u likwid-demo.service -f

For production, create a separate unit (for example likwid-prod.service) with the production env file and compose file.

Smoke test

After deploy/update, run:

• ./scripts/smoke-test.sh demo