feat(run-spaceapp): support rootless Podman as container engine (fixes #63)

.github/workflows/platform-matrix.yml

@@ -57,3 +57,41 @@ jobs:
       - run: npm run check -w run-spaceapp
       - run: npm run pack:dry-run -w run-spaceapp
       - run: node packages/run-spaceapp/bin/spaceapp.mjs --version
+
+  podman-rootless:
+    name: Rootless Podman E2E / ubuntu-latest
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "22.23.0"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install SpaceApp with Podman
+        run: >-
+          node packages/run-spaceapp/bin/spaceapp.mjs install --engine podman --profile small --non-interactive
+          --answers '{"confirm":true,"profile":"small","access":"isolated","companions":false,"telemetry":false,"open":false}'
+
+      - name: Run doctor check
+        run: node packages/run-spaceapp/bin/spaceapp.mjs doctor
+
+      - name: Verify /readyz endpoint
+        run: curl --fail --retry 15 --retry-delay 2 http://127.0.0.1:4911/readyz
+
+      - name: Test backup
+        run: node packages/run-spaceapp/bin/spaceapp.mjs backup
+
+      - name: Test uninstall and purge
+        run: echo DELETE | node packages/run-spaceapp/bin/spaceapp.mjs uninstall --purge-data
+
+      - name: Ensure no containers running
+        run: test -z "$(podman ps -q)"
+

README.md

@@ -92,7 +92,7 @@ Coordinate multi-step tasks conversationally through the Room Agent or speak nat
 - **Hardware**:
   - Minimum (`small` profile): 4 CPU cores, 8 GB-class RAM (at least 7 GiB reported by the operating system), 6.5 GiB free disk.
   - `large` profile (adds the managed browser): 8 CPU cores, 15 GiB RAM, 11 GiB free disk.
-- **Docker**: If Docker is not installed, the installer automatically installs official Docker Desktop (Windows/macOS) or Docker Engine (Linux).
+- **Container Engine**: Docker by default, or rootless Podman (Podman ≥ 5 with compose provider) on Linux and macOS (`--engine podman`). If Docker is not installed, the installer automatically installs official Docker Desktop (Windows/macOS) or Docker Engine (Linux). If only Podman is present on Linux, SpaceApp offers Podman instead of installing Docker.
 
 ### Run the Installation Command
 

docs/getting-started.md

@@ -53,6 +53,18 @@ its code signature, installs it, starts it, and waits until it is ready. Docker
 Desktop uses its managed lightweight Linux environment. Apple Silicon uses the
 native `linux/arm64` images and Intel Macs use `linux/amd64`.
 
+## Rootless Podman (Linux & macOS)
+
+SpaceApp supports rootless Podman as an alternative container engine on Linux and macOS:
+
+```bash
+npx --yes run-spaceapp@latest install --engine podman --profile small
+```
+
+- **Linux**: Requires Podman ≥ 5 with compose provider (`podman-compose` or `docker-compose` v2) and cgroup v2. All workspace bind mounts automatically apply SELinux `:z` volume flags, allowing seamless read-write access on SELinux enforcing distributions like Fedora and RHEL. If Docker is missing and Podman is present on Linux, the launcher offers Podman (or picks it with `--non-interactive`) instead of installing Docker.
+- **macOS**: Runs via `podman machine`. SpaceApp verifies that the VM has sufficient CPU cores, memory, and disk space for the chosen profile, and prints resize instructions (`podman machine set`) if resources need adjusting.
+- **Limits**: Container engines cannot be switched on an existing installation without reinstalling (Docker volumes are not shared with Podman). `--access host-root` is not supported with Podman.
+
 ## Windows 11 — Command Prompt
 
 Enable hardware virtualization and install Node.js 20.11 or newer. Open

packages/run-spaceapp/README.md

@@ -62,6 +62,19 @@ before pausing writers. Existing data is kept in place; the launcher never delet
 images, backups or volumes to free space. Separate Docker disk capacity is checked
 when measurable and its availability is reported.
 
+### Container Engine: Docker and Rootless Podman
+
+SpaceApp defaults to Docker (`--engine docker`). On Linux and macOS, you can also run SpaceApp on rootless Podman:
+
+```bash
+npx --yes run-spaceapp@latest install --engine podman --profile small
+```
+
+- **Linux**: Requires Podman ≥ 5 with compose provider (`podman-compose` or `docker-compose` v2) and cgroup v2. Bind mounts for registered workspaces use SELinux `:z` volume flags for compatibility with SELinux enforcing hosts (e.g. Fedora, RHEL). If Docker is missing and Podman is present on Linux, the launcher offers Podman (or picks it with `--non-interactive`) instead of installing Docker.
+- **macOS**: Runs via `podman machine`. The launcher checks machine sizing against profile requirements and advises resize commands if resources are insufficient.
+- **Data Safety & Limits**: Switching container engines on an existing installation is blocked to protect persistent volumes. `--access host-root` is not supported on Podman.
+- **Diagnostics**: `spaceapp doctor` reports engine details, rootless status, cgroup version, and resource limits delegation. `spaceapp support-bundle` includes engine facts without secrets.
+
 ### Telemetry
 
 Telemetry is off unless you turn it on. The install wizard lists what is sent