79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
 
|
# 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.
|