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:

```bash
sudo zypper in -y podman git
```

Verify `podman compose` is available:

```bash
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:

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

1. Create the production env file:

```bash
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:

```bash
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:

```bash
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):

```bash
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:

```bash
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:

```bash
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:

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

Container status:

```bash
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:

```bash
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)

```ini
[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:

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

1. Inspect service logs:

```bash
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`