docs: add openSUSE operator kit runbook

docs/README.md

@@ -5,6 +5,7 @@ Welcome to the Likwid documentation. This guide covers everything you need to kn
 ## Documentation Structure
 
 ### For Users
+
 - [Getting Started](user/getting-started.md) - First steps with Likwid
 - [Communities](user/communities.md) - Creating and participating in communities
 - [Proposals & Voting](user/voting.md) - Understanding the decision-making process
@@ -12,14 +13,17 @@ Welcome to the Likwid documentation. This guide covers everything you need to kn
 - [Account Settings](user/settings.md) - Managing your account
 
 ### For System Administrators
+
 - [Installation](admin/installation.md) - Deploying Likwid
 - [Configuration](admin/configuration.md) - Server and instance settings
 - [Database](admin/database.md) - PostgreSQL setup and maintenance
 - [Plugins](admin/plugins.md) - Managing plugins and voting methods
 - [Security](admin/security.md) - Security best practices
 - [Backup & Recovery](admin/backup.md) - Data protection
+- [openSUSE Operator Kit](admin/opensuse-operator-kit.md) - openSUSE Leap deployment and operations (container-first)
 
 ### Reference
+
 - [API Reference](reference/api.md) - REST API documentation
 - [Voting Methods](reference/voting-methods.md) - Detailed voting algorithm explanations
 - [Glossary](reference/glossary.md) - Terms and definitions

docs/admin/opensuse-operator-kit.md

@@ -0,0 +1,177 @@
+# 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
+```
+
+2. Create the production env file:
+
+```bash
+cp ~/likwid/compose/.env.production.example ~/likwid/compose/.env.production
+```
+
+3. Edit `~/likwid/compose/.env.production`:
+
+- `POSTGRES_PASSWORD`
+- `JWT_SECRET`
+- `API_BASE` (should be your public URL, e.g. `https://your.domain`)
+
+4. Start services:
+
+```bash
+cd ~/likwid
+podman compose --env-file compose/.env.production -f compose/production.yml up -d --build
+```
+
+5. 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
+```
+
+2. Create a systemd user unit:
+
+- File: `~/.config/systemd/user/likwid-demo.service`
+
+```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 --build
+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
+```
+
+3. Enable and start it:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now likwid-demo.service
+```
+
+4. 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.