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
- Images, containers and volumes live in
~/.local/share/containers, on the data partition. They survive system updates. - Use full image names (
docker.io/library/nginx). Short names resolve against Docker Hub, but the full name says exactly what you're pulling. - As a regular user you can't publish ports below 1024. Publish
8080, not80, and put a reverse proxy in front if you need 80 or 443. podman ps,podman logs NAME,podman exec -it NAME shandpodman stop NAMEwork just like Docker's.- Containers stop when you log out. Rootless containers belong to your
login session. On a Server you reach over SSH, that means
podman run -dlasts only until you disconnect. Turn on lingering once and they keep running:sudo loginctl enable-linger "$USER". To start them at boot, give each one a service.
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
127.0.0.1:in-pkeeps the database reachable from programs on this machine only, which is the safe default for a database. Other containers can't reach it there. Put them in a pod together.- MongoDB 5 and newer needs a CPU with AVX. Every Intel Core/Ryzen of the last decade and the Intel N100 have it, but some old Atoms and Celerons don't.
- The same pattern works for PostgreSQL (
docker.io/library/postgres:17,-e POSTGRES_PASSWORD=…,-v pg-data:/var/lib/postgresql/data), Redis, MariaDB and so on.
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