Rootless Podman prerequisites
This page lists the prerequisites for hosting Steampunk Spotter with the rootless Podman deployment.
The installer includes portable Podman binaries, so installing a distribution
podman package is not required. The requirements below are for the host,
the user running Spotter, and the installer configuration.
Mandatory prerequisites
The following requirements must be satisfied for a functional Steampunk Spotter runtime:
| Requirement | Details |
|---|---|
| A non-root Spotter user | Run the installer as the Spotter user who will own and run the rootless containers. The installer refuses to run as root. However, if any optional system-level changes need to be performed by the installer, this user must be able to perform sudo. |
| A custom Ansible variables file | Set SPOTTER_INSTALLER_CUSTOM_VARS_FILE to an existing, readable, absolute-path file. The file must define secrets_encryption_key. |
| A rootless UID/GID mapping | The Spotter user must have entries in /etc/subuid and /etc/subgid. The installer can add the range 100000-165535 when run with sufficient superuser privileges. If this range is taken, manually choose the next range possible (ie. 165535-231070). |
newuidmap and newgidmap |
These helpers are required by rootless containers. On RHEL-like systems they are provided by shadow-utils; on Debian-like systems by uidmap. |
iptables |
Podman rootless mode requires iptables for container networking. |
| A usable installation path | The selected installation location must be an absolute path and must be writable by the Spotter user, or creatable with sudo then chowned to the Spotter user. The installer attempts to create the path directory. |
| HTTP and HTTPS listener ports | By default, Spotter uses TCP ports 80 and 443. Either the host must permit unprivileged users to bind those ports, or custom ports at or above /proc/sys/net/ipv4/ip_unprivileged_port_start must be configured. |
The installer can automatically install newuidmap/newgidmap and
iptables on Debian-like and RHEL-like distributions, but the corresponding
system package repositories and superuser access must be available.
Conditional prerequisites
These requirements apply only in the relevant host configuration:
| Condition | Requirement |
|---|---|
| SELinux is enabled on a RHEL-like host | Install the container-selinux package so the system has the required container policies. The installer can install it with yum when it is missing. |
Default ports 80 and 443 are retained |
Set net.ipv4.ip_unprivileged_port_start to 80 (the installer can configure this temporarily and persist it in /etc/sysctl.d/70-steampunk-spotter-unprivileged-port-start.conf), or ensure an equivalent host configuration already exists. |
Optional prerequisites and features
The following are not required for containers to run, but enable specific installation or operational features:
| Optional item | Purpose and requirement |
|---|---|
| A systemd login session | Required to configure the systemd user service for automatic startup. Without XDG_RUNTIME_DIR, the installer warns and autostart setup cannot succeed. Log in through SSH, machinectl shell, or another method that creates a systemd user session. |
systemd-logind lingering for the installation user |
Keeps the user service and its containers running after the user logs out. The installer can enable it with loginctl enable-linger. It is recommended when Spotter should remain available without an active login session. |
| A systemd user unit and autostart | Starts Spotter automatically after reboot. The installer can install and enable steampunk-spotter.service; this is separate from merely running the containers manually. |
| Persistent systemd journal storage | Preserves startup logs for the user service across reboots. The installer can set Storage=persistent in /etc/systemd/journald.conf. |
| A custom CA certificate file | Add private or enterprise CA certificates for Spotter's outbound connections. Provide an absolute, readable file; its certificates are merged with the default trust store. |
| CA certificate monitoring | When a custom CA file is supplied, the installer can configure automatic synchronization when the source file changes. Without this, updates to the original file are not copied automatically. |
| A system package manager with repositories | Needed only if the installer is asked to remediate missing host packages or configuration. Automatic package installation supports Debian-like (apt-get) and RHEL-like (yum) systems. |
sudo or equivalent superuser access |
Needed only for installer actions that modify system files, install packages, configure port binding, enable lingering, or adjust journald. |
| PATH modification | Optional convenience: the installer can add the Spotter binary directory to $HOME/.bash_profile so commands such as podman-portable are available without their full path. |
Pre-installation checklist
Before running the installer, verify at least by invoking in the target host's bash shell as Spotter user:
test "$(id -u)" -ne 0
id
grep "$(id -un)" /etc/subuid /etc/subgid
command -v newuidmap
command -v newgidmap
PATH="/usr/sbin:$PATH" command -v iptables
cat /proc/sys/net/ipv4/ip_unprivileged_port_start
test -n "${XDG_RUNTIME_DIR:-}" # required only for systemd autostart
If a UID/GID mapping or host package is missing, either allow the installer to prepare the supported remediation with superuser access or prepare it before running the installer.