Deploy Roxy-WI with Podman Quadlet

The controller profile runs Web, Scheduler, Service Events, Operations, RabbitMQ and a local HTTPS endpoint. It uses SQLite with one Web deployment. This helper does not migrate an existing package/Compose installation or provision MariaDB.

• Linux with systemd, cgroup v2, Python 3.10+ and Podman 4.9+ with Quadlet.
• A working container init helper; minimal Debian installations may need catatonit.
• GnuPG and an encryption-capable GPG key for the same account that owns Podman. The pass secret driver must decrypt noninteractively, including after reboot.
• A source checkout and build/download access. Rootless deployment also needs working subordinate IDs, networking and a user manager.

Choose root for system units or an ordinary login account for rootless user units. Keep the same owner and state paths for every command. The helper does not generate/unlock GPG keys or silently replace missing secrets.

From a checkout containing Roxy-WI 10.0, run the following as the rootless owner. Replace GPG_FINGERPRINT with the full fingerprint of that owner's encryption-capable key.

python3 podman/deploy.py prepare --build --gpg-fingerprint GPG_FINGERPRINT
python3 podman/deploy.py start
python3 podman/deploy.py password

For a system deployment, prefix all three commands with sudo and use root's GPG key. prepare builds and pins the application image and writes units/state without starting the application. Review generated files before start.

Open https://localhost:8443 and sign in as admin with the generated password. The endpoint binds to loopback by default and uses a local evaluation CA. The helper verifies its own HTTPS/readiness checks but does not modify client trust stores. For a remote host, use an SSH tunnel such as ssh -L 8443:127.0.0.1:8443 USER@HOST.

For rootless boot startup, an administrator can enable lingering for the intended account with sudo loginctl enable-linger USER. Verify the owner's network and GPG access after reboot. Generated units already have boot targets; do not enable generated services manually.

python3 podman/deploy.py status
python3 podman/deploy.py logs
python3 podman/deploy.py stop
python3 podman/deploy.py start

Use sudo consistently for a system deployment. Logs come from the owning systemd journal. Controller lifecycle belongs to systemd; it is not managed through the Roxy-WI tools page. Stopping preserves volumes and secrets. Ordinary startup reuses the pinned application image.

Before upgrading, stop the controller, back up persistent volumes and private state together, and retain the previous image. From the updated checkout, run:

python3 podman/deploy.py upgrade --build

Upgrade pins the new image, stops application roles, applies the database migration and verifies startup. Plan downtime. Use upgrade for changed images or options; an ordinary start does not replace an active deployment. Startup failure preserves state and does not automatically reverse a database migration.

Back up the state directory, Podman secret metadata/encrypted storage, volumes and the owner's GPG recovery material together. Volumes are roxywi-app-data, roxywi-broker-data, roxywi-tls-data and roxywi-tls-config. Retain the original application encryption secret, owner and state-directory path.

secrets.json is a metadata manifest; encrypted values use native Podman secrets. Missing or undecipherable secrets on an initialized installation are refused rather than regenerated. Restore the original metadata/key material instead of deleting state and starting again. Recovering an older schema needs the matching database backup and image.

For startup failures inspect status and logs, the init helper, user runtime, GPG decryption and network/firewall setup. The helper does not alter host firewall policy or kernel networking prerequisites. Existing plaintext evaluation deployments require an explicit migration preserving their application key.

For alternative deployments, see packages, Compose and Helm. For remote proxies managed through the GUI, use managed containers.