feat(run-spaceapp): support rootless Podman and Podman machine container engine (closes #63)

.github/workflows/platform-matrix.yml

@@ -57,3 +57,19 @@ 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-linux:
+    name: Launcher / Podman rootless (ubuntu-latest)
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    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
+      - run: npm ci
+      - run: npm test -w run-spaceapp
+      - run: node packages/run-spaceapp/bin/spaceapp.mjs --plan install --engine podman --profile small --non-interactive --answers '{"confirm":true}'

docs/getting-started.md

@@ -334,3 +334,14 @@ Then set a new `SPACEAPP_HOME` and follow `init → doctor → workspace add →
 pull. This proves a source build; it does **not** prove the public npm tarball
 or GHCR manifests. Follow [Clean-room testing](clean-room-testing.md) for the
 complete acceptance checklist.
+
+
+## Rootless Podman Support
+
+SpaceApp also supports **rootless Podman** on Linux (Podman >= 5 with cgroup v2 and `docker-compose` v2 as the `podman compose` provider) and **Podman machine** on macOS:
+
+```bash
+npx --yes run-spaceapp@latest install --engine podman --profile small
+```
+
+The selected engine (`docker` or `podman`) is stored in `config.json` and used automatically by `up`, `down`, `status`, `logs`, `doctor`, `backup`, `restore`, `update`, `rollback`, and `uninstall`. Switching engines on an existing installation is refused to protect existing volumes; use `backup` and `restore` when migrating between engines. `--access host-root` is not supported on Podman.

packages/run-spaceapp/README.md

@@ -183,3 +183,14 @@ npx --yes run-spaceapp@latest uninstall      # Stop and remove containers (prese
 Uninstall retains data by default and prints the separate
 `npm uninstall -g run-spaceapp` command for removing an optional global
 launcher.
+
+
+## Rootless Podman Support
+
+SpaceApp also supports **rootless Podman** on Linux (Podman >= 5 with cgroup v2 and `docker-compose` v2 as the `podman compose` provider) and **Podman machine** on macOS:
+
+```bash
+npx --yes run-spaceapp@latest install --engine podman --profile small
+```
+
+The selected engine (`docker` or `podman`) is stored in `config.json` and used automatically by `up`, `down`, `status`, `logs`, `doctor`, `backup`, `restore`, `update`, `rollback`, and `uninstall`. Switching engines on an existing installation is refused to protect existing volumes; use `backup` and `restore` when migrating between engines. `--access host-root` is not supported on Podman.

packages/run-spaceapp/src/index.mjs

@@ -129,8 +129,10 @@ const CONFIG_KEYS = new Set([
   "companionsEnabled",
   "optionalModules",
   "installId",
-  "users"
+  "users",
+  "engine"
 ]);
+export const SUPPORTED_ENGINES = Object.freeze(["docker", "podman"]);
 
 // Multi-user (SpaceApp accounts with SPACE_MULTI_USER_ENABLED): every user's CLIs run in their own container, with
 // their own keys, logins, memory and workspaces; the core starts each pane in its owner's container.
@@ -184,6 +186,16 @@ export function resolveInstallProfile(requestedProfile, resources) {
   return "small";
 }
 
+export function resolveInstallEngine(requestedEngine, existingEngine = "docker") {
+  if (requestedEngine === undefined) {
+    return existingEngine;
+  }
+  if (requestedEngine === "docker" || requestedEngine === "podman") {
+    return requestedEngine;
+  }
+  throw new Error("Container engine must be docker or podman.");
+}
+
 export function resolveInstallAccessMode(requestedMode, existingMode = "isolated") {
   if (requestedMode === undefined) {
     return existingMode;
@@ -308,13 +320,18 @@ export function createDefaultConfig({
   version,
   profile = "light",
   accessMode = "isolated",
-  companionsEnabled = false
+  companionsEnabled = false,
+  engine
 }) {
   assertVersion(version);
   if (!INSTALL_PROFILES.includes(profile)) {
     throw new Error("Default config requires a resolved installation profile.");
   }
   const resolvedAccessMode = resolveInstallAccessMode(accessMode);
+  const resolvedEngine = resolveInstallEngine(engine);
+  if (resolvedEngine === "podman" && resolvedAccessMode === "host-root") {
+    throw new Error("Host-root access (--access host-root) is not supported on Podman. Use --access isolated.");
+  }
   return {
     schemaVersion: CONFIG_SCHEMA_VERSION,
     version,
@@ -326,7 +343,8 @@ export function createDefaultConfig({
     accessMode: resolvedAccessMode,
     companionsEnabled,
     optionalModules: "none",
-    workspaces: []
+    workspaces: [],
+    ...(engine !== undefined ? { engine: resolvedEngine } : {})
   };
 }
 
@@ -364,6 +382,12 @@ export function validateConfig(config) {
   if (config.accessMode !== "isolated" && config.accessMode !== "host-root") {
     throw new Error("accessMode must be isolated or host-root.");
   }
+  if (config.engine !== undefined && !SUPPORTED_ENGINES.includes(config.engine)) {
+    throw new Error("engine must be docker or podman.");
+  }
+  if (config.engine === "podman" && config.accessMode === "host-root") {
+    throw new Error("Host-root access (--access host-root) is not supported on Podman. Use --access isolated.");
+  }
   if (typeof config.companionsEnabled !== "boolean") {
     throw new Error("companionsEnabled must be boolean.");
   }
@@ -673,17 +697,30 @@ const CLI_SANDBOX_OPTIONS = ["    security_opt:", "      - seccomp=./seccomp-cli
 
 export function renderWorkspaceCompose(config, { cliSandbox = false } = {}) {
   validateConfig(config);
+  const isPodman = config.engine === "podman";
   const mounts = config.workspaces.flatMap((workspace) => [
     "      - type: bind",
     `        source: ${JSON.stringify(workspace.hostPath)}`,
     `        target: ${JSON.stringify(workspace.containerPath)}`,
-    `        read_only: ${workspace.readOnly}`
+    `        read_only: ${workspace.readOnly}`,
+    ...(isPodman ? ["        bind:", "          selinux: z"] : [])
   ]);
+  const podmanUserns = isPodman ? ['    userns_mode: "keep-id:uid=10001,gid=10001"'] : [];
   const service = mounts.length > 0
     ? ["    volumes:", ...mounts]
     : ["    volumes: []"];
   if (config.users === undefined) {
-    return ["services:", "  spaceapp-core:", ...service, "  spaceapp-cli:", ...service, ...(cliSandbox ? CLI_SANDBOX_OPTIONS : []), ""].join("\n");
+    return [
+      "services:",
+      "  spaceapp-core:",
+      ...podmanUserns,
+      ...service,
+      "  spaceapp-cli:",
+      ...podmanUserns,
+      ...service,
+      ...(cliSandbox ? CLI_SANDBOX_OPTIONS : []),
+      ""
+    ].join("\n");
   }
   // "user enable": accounts are on, and the core starts a USER's CLIs only in that user's own container.
   const users = config.users;
@@ -692,12 +729,14 @@ export function renderWorkspaceCompose(config, { cliSandbox = false } = {}) {
     "      - type: bind",
     `        source: ${JSON.stringify(workspace.hostPath)}`,
     `        target: ${JSON.stringify(workspace.containerPath)}`,
-    `        read_only: ${workspace.readOnly}`
+    `        read_only: ${workspace.readOnly}`,
+    ...(isPodman ? ["        bind:", "          selinux: z"] : [])
   ];
   const userServices = users.flatMap((user) => {
     const slug = userSlug(user.id);
     return [
       `  spaceapp-cli-${slug}:`,
+      ...podmanUserns,
       // The owner's pinned CLI image (runtime.env sets the digest; 1.1.7 review: a moved tag cannot change a user's).
       "    image: ghcr.io/oll4com/spaceapp-cli:${SPACEAPP_IMAGE_TAG}${SPACEAPP_CLI_IMAGE_DIGEST:-}",
       "    restart: unless-stopped",
@@ -726,6 +765,7 @@ export function renderWorkspaceCompose(config, { cliSandbox = false } = {}) {
   return [
     "services:",
     "  spaceapp-core:",
+    ...podmanUserns,
     "    environment:",
     '      SPACE_MULTI_USER_ENABLED: "true"',
     "      SPACE_CLI_HOST_SOCKETS_FILE: /etc/spaceapp/cli-hosts.json",
@@ -734,6 +774,7 @@ export function renderWorkspaceCompose(config, { cliSandbox = false } = {}) {
     "      - ./cli-hosts.json:/etc/spaceapp/cli-hosts.json:ro",
     ...users.map((user) => `      - spaceapp-cli-socket-${userSlug(user.id)}:/run/spaceapp-cli-users/${userSlug(user.id)}`),
     "  spaceapp-cli:",
+    ...podmanUserns,
     ...service,
     ...(cliSandbox ? CLI_SANDBOX_OPTIONS : []),
     ...userServices,
@@ -905,7 +946,8 @@ export function composeCommand(action, root, options = {}) {
   if (!selected) {
     throw new Error(`Unsupported Compose action "${action}".`);
   }
-  return { command: "docker", args: [...base, ...selected] };
+  const engine = resolveInstallEngine(options.engine);
+  return { command: engine, args: [...base, ...selected] };
 }
 
 export function composeProjectName(root) {
@@ -956,7 +998,8 @@ export async function prepareInstallation(root, {
   version,
   profile,
   accessMode,
-  companionsEnabled
+  companionsEnabled,
+  engine
 }) {
   validateHome(root);
   await mkdir(root, { recursive: true, mode: 0o700 });
@@ -969,8 +1012,10 @@ export async function prepareInstallation(root, {
     ? undefined
     : resolveInstallProfile(profile, profile === "auto" ? await inspectSystemResources(root) : totalmem());
   let config;
+  let existingLoaded = false;
   try {
     config = await loadConfig(root);
+    existingLoaded = true;
   } catch (error) {
     if (error?.code !== "ENOENT") {
       throw error;
@@ -979,9 +1024,22 @@ export async function prepareInstallation(root, {
       version,
       profile: resolvedProfile ?? "light",
       accessMode: resolveInstallAccessMode(accessMode),
-      companionsEnabled
+      companionsEnabled,
+      ...(engine !== undefined ? { engine } : {})
     });
   }
+  if (existingLoaded && engine !== undefined) {
+    const existingEngine = config.engine ?? "docker";
+    const targetEngine = resolveInstallEngine(engine, existingEngine);
+    if (existingEngine !== targetEngine) {
+      throw new Error(
+        `Cannot switch container engine from ${existingEngine} to ${targetEngine} on an existing installation (${existingEngine} volumes are not visible to ${targetEngine}). Run "${UNIVERSAL_COMMAND} backup", uninstall, and restore on the new engine.`
+      );
+    }
+    if (targetEngine === "podman" && config.engine !== "podman") {
+      config = { ...config, engine: "podman" };
+    }
+  }
   if (config.version !== version) {
     config = {
       ...config,

packages/run-spaceapp/src/prerequisites.mjs

@@ -654,7 +654,7 @@ async function dockerCliAndComposeAreAvailable(execute) {
   return true;
 }
 
-async function dockerIsReady(execute) {
+export async function dockerIsReady(execute) {
   for (const spec of [
     { command: "docker", args: ["--version"] },
     { command: "docker", args: ["compose", "version"] },
@@ -667,6 +667,48 @@ async function dockerIsReady(execute) {
   return true;
 }
 
+export async function podmanIsReady(execute) {
+  for (const spec of [
+    { command: "podman", args: ["--version"] },
+    { command: "podman", args: ["compose", "version"] },
+    { command: "podman", args: ["info"] }
+  ]) {
+    if (await execute(spec, { stdout: null, stderr: null }) !== 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export async function ensurePodmanAvailable({
+  platform = process.platform,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  execute
+}) {
+  if (platform === "win32") {
+    stderr.write("Podman engine support is available on Linux and macOS only.\n");
+    return { code: 1, reexecuted: false };
+  }
+  const cliOk = await execute({ command: "podman", args: ["--version"] }, { stdout: null, stderr: null }) === 0;
+  const composeOk = cliOk && await execute({ command: "podman", args: ["compose", "version"] }, { stdout: null, stderr: null }) === 0;
+  const infoOk = composeOk && await execute({ command: "podman", args: ["info"] }, { stdout: null, stderr: null }) === 0;
+  if (cliOk && composeOk && infoOk) {
+    return { code: 0, reexecuted: false };
+  }
+  const failedProbe = !cliOk
+    ? "podman --version"
+    : !composeOk
+      ? "podman compose version (run `podman compose version` to inspect the resolved Compose provider)"
+      : "podman info";
+  stderr.write(
+    platform === "darwin"
+      ? `Podman check failed at \`${failedProbe}\`. Podman (>= 5) and a Compose provider must be installed and your Podman machine must be running (\`podman machine init --cpus 4 --memory 8192 --disk-size 25 && podman machine start\`).\n`
+      : `Podman check failed at \`${failedProbe}\`. Rootless Podman (>= 5, cgroup v2) and \`podman compose\` must be installed and ready (verify with \`podman compose version\`).\n`
+  );
+  return { code: 1, reexecuted: false };
+}
+
 async function installLinuxDockerEngine({
   arch,
   release,

packages/run-spaceapp/src/storage.mjs

@@ -96,15 +96,16 @@ async function installedImageDigests(root, version) {
 }
 
 export async function inspectStoragePlan({ root, config, existingConfig, resources, execute, operation, fetch = globalThis.fetch }) {
-  const dockerInfo = await captureProbe(execute, { command: "docker", args: ["info", "--format", "{{json .}}"] });
+  const engineCmd = (config?.engine ?? existingConfig?.engine) === "podman" ? "podman" : "docker";
+  const dockerInfo = await captureProbe(execute, { command: engineCmd, args: ["info", "--format", "{{json .}}"] });
   let engine = null;
   try { engine = JSON.parse(dockerInfo); } catch { /* Conservative reserve when the engine is unavailable. */ }
   const cachedLayers = new Set();
   if (engine && existingConfig) {
     const existingDigests = await installedImageDigests(root, existingConfig.version);
     for (const type of ["core", "cli", "browser"]) {
       for (const ref of localImageRefs(type, existingConfig.version, existingDigests[type])) {
-        const output = await captureProbe(execute, { command: "docker", args: ["image", "inspect", "--format", "{{json .RootFS.Layers}}", ref] });
+        const output = await captureProbe(execute, { command: engineCmd, args: ["image", "inspect", "--format", "{{json .RootFS.Layers}}", ref] });
         try { for (const layer of JSON.parse(output)) cachedLayers.add(layer); break; } catch {}
       }
     }
@@ -126,15 +127,16 @@ export async function inspectStoragePlan({ root, config, existingConfig, resourc
     const refs = ["core", "cli", "browser"].includes(type) ? localImageRefs(type, config.version) : [image];
     let cached = null;
     for (const ref of refs) {
-      cached = await captureProbe(execute, { command: "docker", args: ["image", "inspect", "--format", "{{.Id}}", ref] });
+      cached = await captureProbe(execute, { command: engineCmd, args: ["image", "inspect", "--format", "{{.Id}}", ref] });
       if (/^sha256:[a-f0-9]{64}$/.test(cached ?? "")) break;
     }
     if (!/^sha256:[a-f0-9]{64}$/.test(cached ?? "")) {
       missingImages.push(image);
       let reserve = imageReserve[type] ?? GiB;
       if (engine && existingConfig && cachedLayers.size && typeof fetch === "function") {
         try {
-          const metadata = await registryLayers(image, /arm|aarch64/.test(engine.Architecture ?? "") ? "arm64" : "amd64", fetch);
+          const archStr = engine.Architecture ?? engine.host?.arch ?? "";
+          const metadata = await registryLayers(image, /arm|aarch64/.test(archStr) ? "arm64" : "amd64", fetch);
           if (metadata) { reserve = estimateMissingLayers(metadata.layers, metadata.diffIds, cachedLayers); sharedLayersEstimated = true; }
         } catch { /* Offline/private registry: retain the full conservative reserve. */ }
       }
@@ -155,15 +157,16 @@ export async function inspectStoragePlan({ root, config, existingConfig, resourc
     if (/^\d+$/.test(free ?? "")) dockerFreeDiskBytes = Number(free);
   }
   // Linux can measure the Docker filesystem directly even on a fresh install.
-  if (engine?.DockerRootDir && process.platform === "linux") {
+  const rootDir = engine?.DockerRootDir ?? engine?.store?.graphRoot;
+  if (rootDir && process.platform === "linux") {
     const { inspectSystemResources } = await import("./index.mjs");
-    try { dockerFreeDiskBytes = (await inspectSystemResources(engine.DockerRootDir)).freeDiskBytes; } catch {}
+    try { dockerFreeDiskBytes = (await inspectSystemResources(rootDir)).freeDiskBytes; } catch {}
   }
   return { ...plan, missingImages, sharedLayersEstimated, dockerFreeDiskBytes,
     resources: { ...resources,
       freeDiskBytes: dockerFreeDiskBytes === null ? resources.freeDiskBytes : Math.min(resources.freeDiskBytes, dockerFreeDiskBytes),
-      engineCpuCount: engine?.NCPU,
-      engineMemoryBytes: engine?.MemTotal
+      engineCpuCount: engine?.NCPU ?? engine?.host?.cpus,
+      engineMemoryBytes: engine?.MemTotal ?? engine?.host?.memTotal
     } };
 }