PengyOS / Docs / Recipes / Containers with podman

Containers with podman

Server and Desktop ship rootless podman: containers run as your user, with no daemon and no root. If you know docker, you know podman. The commands are the same.

ServerDesktop

Basics

nginx: serve a folder

mkdir -p ~/www && echo '<h1>Hello from PengyOS</h1>' > ~/www/index.html

podman run -d --name web \
  -p 8080:80 \
  -v ~/www:/usr/share/nginx/html:ro \
  docker.io/library/nginx:stable

curl http://localhost:8080

Edit files in ~/www and reload the page. Your own nginx.conf mounts the same way: -v ~/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro.

MongoDB with persistent data

Keep the database in a named volume, so you can recreate the container (to upgrade it, say) without losing data:

podman volume create mongo-data

podman run -d --name mongo \
  -p 127.0.0.1:27017:27017 \
  -v mongo-data:/data/db \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD='change-me' \
  docker.io/library/mongo:8

podman exec -it mongo mongosh -u admin -p   # a shell in the database

Several containers together: pods

A pod is a group of containers that share one network. Inside it they reach each other on localhost, and the pod publishes the ports. Here is a web app and its database:

podman pod create --name app -p 8080:80        # ports go on the pod

podman run -d --pod app --name app-db \
  -v mongo-data:/data/db \
  -e MONGO_INITDB_ROOT_USERNAME=admin -e MONGO_INITDB_ROOT_PASSWORD='change-me' \
  docker.io/library/mongo:8

podman run -d --pod app --name app-web \
  -v ~/www:/usr/share/nginx/html:ro \
  docker.io/library/nginx:stable
# app-web reaches the database at mongodb://admin:change-me@localhost:27017

podman pod ps                    # the pod and its state
podman pod stop app              # stop / start / rm the whole group

The other way is a user-defined network (podman network create appnet, then --network appnet on each container). There, containers reach each other by name (mongodb://…@app-db:27017) and each one publishes its own ports. Create the network first. A container already started on the default network can't join one later.

Releases before 26.10.0 lack podman's rootlessport helper, so publishing a port from a user-defined network fails there with could not find "rootlessport". Use a pod, or update.

Start containers at boot

Rootless containers don't restart on their own after a reboot. Give each one a small systemd user service, and let your user's services run without you logging in (lingering):

sudo loginctl enable-linger "$USER"    # once per user
mkdir -p ~/.config/systemd/user

Create ~/.config/systemd/user/web.service (shown for the nginx example; change the name and the podman run options for others):

[Unit]
Description=nginx in podman

[Service]
Type=notify
NotifyAccess=all
ExecStart=/usr/bin/podman run --rm --replace --name web \
    --sdnotify=conmon --cgroups=no-conmon -d \
    -p 8080:80 -v %h/www:/usr/share/nginx/html:ro \
    docker.io/library/nginx:stable
ExecStop=/usr/bin/podman stop --ignore -t 10 web
Restart=on-failure

[Install]
WantedBy=default.target
podman rm -f web                        # the service owns it from now on
systemctl --user daemon-reload
systemctl --user enable --now web.service
systemctl --user status web.service
journalctl --user -u web.service        # its log

%h is your home directory. --replace clears a leftover container with the same name, and --rm removes it when it stops, so the unit always starts from the image. Named volumes like mongo-data are kept. Copy the file once per container.

Reach a container from your network

The firewall drops inbound connections except SSH, so localhost:8080 works but another computer can't connect yet. Open the port in /etc/nftables.conf (how):

        tcp dport 8080 ct state new accept
sudo nft -c -f /etc/nftables.conf && sudo systemctl restart nftables

Compose files

podman-compose runs compose.yml / docker-compose.yml files. It's a Python program, so install it with uv:

uv tool install podman-compose
cd ~/myapp && podman-compose up -d     # or: podman compose up -d
podman-compose logs -f
podman-compose down

Compose puts each project on its own network, so services with ports: need PengyOS 26.10.0 or newer (see above).

Updating and cleaning up

podman pull docker.io/library/nginx:stable   # newer image
systemctl --user restart web.service         # recreated from it (or podman rm -f + run again)

podman system df                             # what is using space
podman image prune                           # drop unused images
podman system prune                          # + stopped containers, unused networks
← The dev boxPython with uv →