# Podman deployment (rootless, no docker daemon)

Hosts without a docker daemon (like `devplace`) run the stack with the Python
`podman-compose` plus the `docker-compose.podman.yml` overlay. The base
`docker-compose.yml` is unchanged and stays the file rootful `docker compose`
uses; the overlay only adjusts what rootless podman needs.

## Commands

Always go through the make targets - they pin both `-f` files. A bare
`podman-compose up -d` drops the overlay and recreates a crashing app (see
"Why the overlay exists").

```bash
make podman-build           # build images (only when pyproject/Dockerfiles change)
make podman-up              # start (also warns if user linger is off)
make podman-reload          # restart workers on new code (bind-mounted, no rebuild)
make podman-ps              # container status
make podman-logs            # tail output
make podman-down            # stop
```

Open `http://<host>:${PORT}` (default 10500, published on 127.0.0.1 for the
front proxy). Source-only changes need just `make podman-reload`.

## Why the overlay exists

The base file runs the app as `user: 1000:1000`, which is correct for rootful
docker (container uid 1000 == host uid 1000). Under **rootless** podman the
default userns instead maps container uid 1000 to a subordinate host uid
(100999), which cannot write the bind-mounted checkout (owned by host uid
1000) - uvicorn dies on startup with
`PermissionError: ... '/app/data/locks/devplace-init.lock'`, the app never
turns healthy, and nginx (which waits on `service_healthy`) never starts.

The overlay sets `user: "0:0"` for the app: container root maps back to the
invoking host user under rootless, restoring write access while staying
unprivileged on the host. (`userns_mode: keep-id` would also fix the mapping
but podman rejects `--userns` together with `--pod`, and podman-compose puts
all services in one pod.)

## One compose tool only

Use the Python `podman-compose` (`/usr/bin/podman-compose`) for this stack,
never mix it with native `podman compose` in the same project directory. They
use different container names (`devplace_app_1` vs `devplace-app-1`) and would
create a second stack fighting over port 10500.

## Surviving reboots

Both services use `restart: unless-stopped`, but rootless containers only
restart after a reboot if the host user's systemd linger is enabled:

```bash
loginctl show-user "$(id -un)" | grep Linger   # want: Linger=yes
sudo loginctl enable-linger "$(id -un)"        # fix if off
```

`make podman-up` prints a warning when linger is off.

## Known differences from docker

- The admin-only **Container Manager** needs the docker socket, which does not
  exist on podman hosts. The `[containers] docker ps failed: [Errno 2]` lines
  in the app log are expected noise, not an error; serving the site is
  unaffected.
- `make docker-attach` / the containers overlay do not apply here.

## Troubleshooting

- `PermissionError ... /app/data/...` on boot: the app was (re)created
  without the overlay. Run `make podman-up` (it recreates with the fix).
- `up` hangs with no output: it is waiting on the app healthcheck. In another
  shell run `podman logs devplace_app_1` - a crash loop there is the cause.
- `Error: --userns and --pod cannot be set together`: a `userns_mode`
  override is in play; remove it, this stack relies on `user: "0:0"`.
- Port 10500 already in use: a second stack (other compose tool, or bare-metal
  `make prod`) is running. `podman ps -a` plus `ss -tlnp` show the conflict.