bug(docs): Podman gateway page lists too few causes of the --tls-cert startup error #5003

User Story

As someone running the OpenShell gateway as a rootless Podman container, I want the container deployment page to name every cause of the --tls-cert is required when TLS is enabled startup error, so I can fix the real cause instead of following the error message's --disable-tls hint.

Problem Statement

The Podman section of docs/how-it-works/gateways/container-deployment.mdx (added in #4977) says the --tls-cert is required when TLS is enabled error means OPENSHELL_LOCAL_TLS_DIR is unset or points at a directory without the generated certificates.

On v0.1.6 the same error also appears when the directory exists and holds valid certificates, but the container cannot read it:

• Without --userns=keep-id:uid=1000,gid=1000, the container user cannot read files owned by the host user.
• Without --security-opt label=type:container_runtime_t, SELinux blocks the container from reading the data directory.

The page describes the SELinux option only as needed for the Podman socket, and it does not connect the user mapping to reading the certificates. The error message's own hint is use --disable-tls to skip, which would remove authentication.

Impact / Why This Matters

A reader who follows the page, finds the variable set and the certificates generated, and still gets the error has nothing on the page that points at the real cause. They may follow the hint and turn TLS off, which removes authentication on a gateway that can start containers through the user's Podman socket. The current workaround is to know to check the user mapping and the SELinux label, which the page does not say.

Acceptance Criteria

• The page names the unreadable-directory causes of the --tls-cert error and the settings to check.
• The SELinux setting says the type is also needed to read the data directory.
• The page says that disabling TLS, as the error message suggests, would remove authentication.

Reproduction Steps

Setup: Fedora 44, rootless Podman 5.8.9, SELinux enforcing, v0.1.6 CLI and gateway image, with the commands from the page and generate-certs already run.

1. Start the gateway container with the page's podman run command but without --userns=keep-id:uid=1000,gid=1000. It exits at startup with --tls-cert is required when TLS is enabled.
2. Repeat with the userns option but without --security-opt label=type:container_runtime_t. It exits with the same error.
3. Repeat without HOME and XDG_DATA_HOME. It exits with a different error, about the credential key directory, which the page already covers.
4. Control: with all settings it starts and reports mTLS authentication.

Suggested UX (if applicable)

Extend the startup error note to say the certificates may be unreadable as well as missing, and name the settings to check. A fix is open in #5001.

Environment

• OS: Fedora Linux 44 Workstation, SELinux enforcing
• Podman 5.8.9, rootless
• OpenShell v0.1.6 (CLI and gateway image)

Logs

Error: × --tls-cert is required when TLS is enabled (use --disable-tls to skip)