bug(podman): container gateway example in the docs does not produce a working gateway on rootless Fedora #4972

User Story

As a Fedora user who wants to run the OpenShell gateway as a container, I want the "Using Podman" example in "Running the Gateway as a Container" to produce a working gateway, so that I can create my first sandbox without reverse-engineering the startup errors.

Problem Statement

The podman run example in docs/how-it-works/gateways/container-deployment.mdx ("Using Podman") does not produce a working gateway on a stock Fedora 44 workstation with rootless Podman and SELinux enforcing. The page is unchanged on main (e5adf6f48) since v0.1.5. The failures happen in sequence, and each fix exposes the next one:

1. The container exits at startup. failed to prepare default credential storage key-encryption key directory '/app/.local/state/openshell/gateway/credentials/key-encryption-key.bin'. The image runs as 1000:1000 and cannot write under /app. Running with --userns=keep-id:uid=1000,gid=1000 and setting HOME and XDG_DATA_HOME to a writable directory fixes it. The Compose example sets user: "0" and HOME/XDG_DATA_HOME; the Podman example sets neither.
2. SELinux blocks the Podman socket. connection error: /var/run/podman.sock: Permission denied. --security-opt label=type:container_runtime_t fixes it (label=type:spc_t also works, so label=disable is not needed).
3. openshell sandbox create fails with podman API error (500): statfs /var/openshell/openshell/podman-sandbox/<id>/openshell-sandbox: no such file or directory. The driver extracts the sandbox binary into the gateway data directory and asks the host Podman to bind-mount that path. The data directory therefore has to be mounted at the same absolute path on the host and in the container, which the Docker prerequisites already state. The named volume in the Podman example cannot satisfy this, and I could not find a driver setting that changes where the binary is extracted.
4. After that, sandbox create fails with Podman sandbox launch authentication is required. The gateway does not create its sandbox signing keys. The packaged systemd unit runs openshell-gateway generate-certs --output-dir ... before every start and sets OPENSHELL_LOCAL_TLS_DIR; the container example does neither. With keys generated and OPENSHELL_LOCAL_TLS_DIR pointing at them, no gateway_jwt section is needed. Because OPENSHELL_LOCAL_TLS_DIR also turns on user authentication, a local plaintext gateway then also needs allow_unauthenticated_users = true, or the CLI gets missing authorization header. The startup log only has the generic "no authentication mechanism" warning. This looks related to Validate sandbox launch-signing configuration before image preparation #3949, which fixed the equivalent message for the VM driver.
5. The host port must equal the container port unless grpc_endpoint is set. With -p 127.0.0.1:8090:8080, the driver logs Auto-detected gRPC endpoint http://127.0.0.1:8080, the host-network supervisor cannot connect, and the sandbox fails with ContainerExited and Startup configuration fetch failed ... failed to connect to OpenShell server. Setting grpc_endpoint under [openshell.drivers.podman] works.

Impact / Why This Matters

The page is the documented route for running the gateway without the system package manager, including on Silverblue and other immutable Fedora variants. A user who follows it gets a gateway that exits at startup or cannot create a sandbox, and the error text does not name the cause. The workaround is reading the Compose file, the Docker prerequisites, the packaged unit file, and the driver source. That is a poor first experience, and it is also the case where the example is the only guidance available.

Acceptance Criteria

• The "Using Podman" example creates a running gateway and a first sandbox on Fedora with rootless Podman and SELinux enforcing.
• The page states the writable state directory, SELinux, same-path data directory, signing key, and port requirements, and the settings that satisfy each.
• The example has been run on the current stable release.

Reproduction Steps

1. On Fedora 44, as a regular user: systemctl --user enable --now podman.socket.
2. Run the "Using Podman" command from the page exactly as written (image ghcr.io/nvidia/openshell/gateway:latest). The container exits with the error in failure 1.
3. Apply each fix above in order and retry. Failures 2, 3, 4, and 5 appear in that order. With all of them applied (writable state directory, SELinux type, same-path data directory, generated keys with OPENSHELL_LOCAL_TLS_DIR, allow_unauthenticated_users = true, matching ports), a sandbox runs.
4. On gateway:0.1.6-pre.5, failures 1, 3, 4, and 5 reproduce the same way. I observed the SELinux denial on 0.1.5 only.

Suggested UX (if applicable)

Update the example so it runs as written on rootless Podman with SELinux enforcing, and document the requirements above. Two optional product follow-ups, not required for the docs fix:

• Give the gateway image a writable default state directory.
• Fail early, with a clear message, when the data directory is not visible at the same path on the host, and when sandbox launch signing is not configured (the Podman equivalent of Validate sandbox launch-signing configuration before image preparation #3949).

Environment

• OS: Fedora Linux 44 Workstation, kernel 7.2.11-200.fc44.x86_64, SELinux enforcing
• Podman: 5.8.9, rootless, cgroups v2, netavark, pasta
• Gateway image: ghcr.io/nvidia/openshell/gateway:latest (0.1.5) and :0.1.6-pre.5
• CLI: 0.1.5 (release tarball)

Logs

Error: × configuration error: failed to prepare default credential storage key-encryption key directory '/app/.local/state/openshell/gateway/credentials/key-encryption-key.bin': failed to create /app/.local/state/openshell/gateway/credentials

WARN openshell_driver_podman::driver: Podman socket not ready, retrying ... error=connection error: /var/run/podman.sock: Permission denied (os error 13)

Error: × code: 'Internal error', message: "create sandbox failed: podman API error (500): statfs /var/openshell/openshell/podman-sandbox/<id>/openshell-sandbox: no such file or directory"

Error: × code: 'The system is not in a state required for the operation's execution', message: "Podman sandbox launch authentication is required"