Day 1: Podman
Goal: Use Podman like
docker– pull images, start containers, build the three notes images – and understand what short names, rootless and rootful mean. · Duration: approx. 75 min · Prerequisite: Day 0
Briefing
- Podman has no daemon. Every
podmancall is a process of its own; besides the container, only the small watchdog conmon stays around. - The commands have the same names as in Docker:
run,ps,logs,exec,build,images. - Rootless (as
ubuntu) and rootful (sudo podman) are two separate worlds with their own image storage, their own containers and their own network. - Podman resolves image names without a registry (short
names) only via aliases. That is why the book always writes
docker.io/library/….
ubuntu (rootless) root (sudo podman)
┌──────────────────────────────────┐ ┌──────────────────────────────┐
│ podman run ─► conmon ─► crun │ │ sudo podman run ─► conmon │
│ ~/.local/share/containers │ │ /var/lib/containers/storage │
│ UID 0 in container = ubuntu │ │ UID 0 in container = root │
│ Net: pasta │ │ Net: bridge podman0 │
└──────────────────────────────────┘ └──────────────────────────────┘
Drill 1: podman – profile and installation
| Profile | podman |
|---|---|
| Purpose | Start containers and pods, build, pull and manage images |
| Special feature | daemonless, rootless by default, pods, systemd integration (Quadlet) |
| Project | podman.io,
github.com/containers/podman |
| Version in the book | 5.7.0 (Ubuntu package podman) |
You installed Podman on Day 0. On its own, it looks like this:
sudo apt-get install -y podman
apt-cache policy podman | head -3
podman --version
dpkg -L podman | grep -E 'bin/|libexec/podman/'Expected:
podman:
Installed: 5.7.0+ds2-3build1
Candidate: 5.7.0+ds2-3build1
podman version 5.7.0
/usr/bin/podman
/usr/libexec/podman/podman-testing
/usr/libexec/podman/quadlet
/usr/libexec/podman/rootlessport
/usr/bin/podmansh
apt is idempotent here: if the package is already there
in this version, nothing happens. You need quadlet on Day
3.
How Podman works: podman run creates
the container, starts conmon and exits. conmon calls
the OCI runtime crun, which starts the process in its
own namespaces and cgroups, and stays around as a watchdog for logs and
exit code. There is no service like dockerd that owns all
containers.
Save your progress? Sign up for free
Drill 2: Short names and
registries.conf
With Docker, nginx always means
docker.io/library/nginx. Podman knows several registries
and does not guess:
podman pull nginx:1.30.6-alpine; echo "Exit: $?"
grep -n 'unqualified-search-registries' /etc/containers/registries.conf
ls /etc/containers/registries.conf.d/
grep -E '"(alpine|golang|node|python|nginx|postgres)"' \
/etc/containers/registries.conf.d/shortnames.confExpected:
Error: short-name "nginx:1.30.6-alpine" did not resolve to an alias and no unqualified-
search registries are defined in "/etc/containers/registries.conf"
Exit: 125
21:# unqualified-search-registries = ["example.com"]
shortnames.conf
"alpine" = "docker.io/library/alpine"
"golang" = "docker.io/library/golang"
"python" = "docker.io/library/python"
"node" = "docker.io/library/node"
registries.confdefines which registries Podman searches for names without a registry. On Ubuntu the list is empty.shortnames.confcontains fixed aliases for well-known images.golang,nodeandpythonare in it,nginxandpostgresare not.
Why so strict? If Podman searched for nginx in several
registries one after another, someone could place an image with the same
name in the first registry and sneak in code that way. A fully qualified
name leaves no doubt:
podman pull docker.io/library/nginx:1.30.6-alpine
podman images
podman image inspect docker.io/library/nginx:1.30.6-alpine \
--format '{{range .RepoDigests}}{{println .}}{{end}}'Expected (abridged, IDs and times will differ on your machine):
Trying to pull docker.io/library/nginx:1.30.6-alpine...
Getting image source signatures
Copying blob sha256:9f0afb44f10e…
…
Writing manifest to image destination
88f52f3d58a505b7e1ad96ca6969478517bcccb58418e75a54223271a64da7df
REPOSITORY TAG IMAGE ID CREATED SIZE
docker.io/library/nginx 1.30.6-alpine 88f52f3d58a5 8 days ago 63.7 MB
docker.io/library/nginx@sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d60947…
docker.io/library/nginx@sha256:…
The first digest belongs to the index (the list of all architectures) and is the same everywhere, the second one to the arm64 manifest of your VM. You can create your own alias per user – to try it out:
mkdir -p ~/.config/containers/registries.conf.d
cat > ~/.config/containers/registries.conf.d/50-lab.conf <<'EOF'
# ~/.config/containers/registries.conf.d/50-lab.conf – nur Tag 1
[aliases]
"nginx" = "docker.io/library/nginx"
EOF
podman run --rm nginx:1.30.6-alpine nginx -v
rm ~/.config/containers/registries.conf.d/50-lab.confExpected (abridged):
/docker-entrypoint.sh: Configuration complete; ready for start up
nginx version: nginx/1.30.6
The book still sticks with fully qualified names: they work on every machine, without anyone having to maintain aliases there.
Save your progress? Sign up for free
Drill 3: Like docker – run, ps, logs, exec
podman run -d --name web -p 127.0.0.1:8080:80 docker.io/library/nginx:1.30.6-alpine
podman ps
curl -sI http://127.0.0.1:8080 | head -2
podman logs --tail 1 web
podman exec web sh -c 'id; ps'Expected (abridged):
dc1bd37dac9b2950c303f8f03ceeb362867a9c053e0ae6b6ee0a959b1554780e
CONTAINER ID IMAGE COMMAND CREATED …
dc1bd37dac9b docker.io/library/nginx:1.30.6-alpine nginx -g daemon o... Less than…
HTTP/1.1 200 OK
Server: nginx/1.30.6
192.168.64.… - - [30/Oct/2026:19:18:20 +0000] "HEAD / HTTP/1.1" 200 0 "-" "curl/8.18.0"…
uid=0(root) gid=0(root) groups=0(root),1(bin),2(daemon),3(sys),4(adm),6(disk),10(wheel)…
PID USER TIME COMMAND
1 root 0:00 nginx: master process nginx -g daemon off;
25 nginx 0:00 nginx: worker process
26 nginx 0:00 nginx: worker process
27 root 0:00 ps
The log shows the VM’s address as the sender, not
127.0.0.1: in rootless mode, pasta
forwards the connection into the container (Day 2). And seen from
outside?
podman top web user huser pid hpid args
ps -o user,pid,ppid,comm -C conmonExpected (abridged, PIDs will differ):
USER HUSER PID HPID COMMAND
root 1000 1 12725 nginx: master process nginx -g daemon…
nginx 100100 25 12757 nginx: worker process
nginx 100100 26 12758 nginx: worker process
USER PID PPID COMMAND
ubuntu 61076 1 conmon
HUSERis the user on the host. root in the container isubuntu(UID 1000), usernginx(UID 101) becomes 100100. Day 2 explains the mapping.- conmon hangs directly off PID 1. There is no daemon whose crash takes all containers down with it.
podman stop web && podman rm web
podman ps -aExpected:
web
web
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
Tip: The Ubuntu package
podman-dockercreates/usr/bin/dockeras a redirect topodman. Useful for scripts that havedockerhard-wired – not needed in the book.
Save your progress? Sign up for free
Drill 4: Build the notes images
Start of the day with the state of Day 0:
source ~/ct-lab/setup/env.sh
mkdir -p ~/ct-lab/tag01 && cd ~/ct-lab/tag01
cp -R "$LAB/code/notes/." .
podman build -t localhost/notes-api:0.1.0 --build-arg VERSION=0.1.0 notes-apiExpected (abridged, takes 1–2 minutes):
[1/4] STEP 1/5: FROM --platform=linux/arm64 golang:1.27-alpine AS base
Resolved "golang" as an alias (/etc/containers/registries.conf.d/shortnames.conf)
Trying to pull docker.io/library/golang:1.27-alpine...
…
[4/4] STEP 1/10: FROM scratch AS final
…
[3/4] STEP 3/3: RUN --mount=type=cache,target=/go/pkg/mod --mount=type=cache,targe…
…
[4/4] STEP 8/10: HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-int…
time="…" level=warning msg="HEALTHCHECK is not supported for OCI image format and will
be ignored. Must use `docker` format"
…
[4/4] COMMIT localhost/notes-api:0.1.0
Successfully tagged localhost/notes-api:0.1.0
podman buildis built-in Buildah (Day 5). It understands--mount=type=cache,--linkand$BUILDPLATFORMjust like BuildKit.- Stage 2/4 (
test) is missing from the output: Buildah does not even build stages that the target does not need. - Podman resolves
golangvia the alias – that is why the build works despite the short name. - The warning is serious: the OCI image format has no
HEALTHCHECK. Podman builds OCI by default. With--format docker, the healthcheck stays in the image:
podman image inspect localhost/notes-api:0.1.0 --format '{{.Config.Healthcheck}}'
podman build --format docker -t localhost/notes-api:0.1.0 \
--build-arg VERSION=0.1.0 notes-api 2>&1 | tail -2
podman image inspect localhost/notes-api:0.1.0 \
--format '{{.Config.Healthcheck.Test}} {{.ManifestType}}'Expected (abridged):
<nil>
Successfully tagged localhost/notes-api:0.1.0
70cfecc8196f03af339c000a7937ce7ab16791c0225d3e63dc7535642ad9d32f
[CMD /notes-api healthcheck] application/vnd.docker.distribution.manifest.v2+json
The second run takes seconds, all steps come from the cache. Now web and worker, right away in Docker format:
podman build --format docker -t localhost/notes-web:0.1.0 notes-web
podman build --format docker -t localhost/notes-worker:0.1.0 notes-worker
podman image prune -f >/dev/null
podman images --filter reference='localhost/*'Expected (abridged):
[1/2] STEP 1/6: FROM node:26-alpine AS build
Resolved "node" as an alias (/etc/containers/registries.conf.d/shortnames.conf)
…
[1/2] STEP 2/7: COPY --from=ghcr.io/astral-sh/uv:0.13.6 /uv /uvx /bin/
Trying to pull ghcr.io/astral-sh/uv:0.13.6...
…
REPOSITORY TAG IMAGE ID CREATED SIZE
localhost/notes-worker 0.1.0 f44274688acd 15 seconds ago 131 MB
localhost/notes-web 0.1.0 71b442015094 43 seconds ago 187 MB
localhost/notes-api 0.1.0 70cfecc8196f About a minute ago 11.9 MB
localhost/ is Podman’s prefix for images without a
registry. Podman skips the --mount=type=secret in notes-web
without an error if no secret npmrc is passed.
image prune deletes only your user’s nameless intermediate
images (<none>).
Save your progress? Sign up for free
Drill 5: Start notes-api
podman run -d --name notes-api -p 127.0.0.1:8080:8080 \
-e NOTES_API_KEY=lab-api-key-123 localhost/notes-api:0.1.0
sleep 3
podman ps --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'
curl -s 127.0.0.1:8080/version; echo
curl -s -X POST 127.0.0.1:8080/notes -H 'X-API-Key: lab-api-key-123' \
-H 'Content-Type: application/json' -d '{"text":"Tag 1 mit Podman"}'; echo
podman logs notes-apiExpected (abridged):
d5bd47739ed5…
notes-api Up 3 seconds (healthy) 127.0.0.1:8080->8080/tcp
0.1.0
{"id":"268d5866-…","text":"Tag 1 mit Podman"}
time=… level=INFO msg="api key loaded" source=env
time=… level=INFO msg="store ready" store=memory
time=… level=INFO msg=listening addr=:8080 version=0.1.0 pid=1
(healthy) comes from the HEALTHCHECK in the
image. Without a daemon, Podman needs someone to run the check regularly
– that is a systemd timer of your user:
id=$(podman inspect -f '{{.Id}}' notes-api)
systemctl --user list-timers --no-pager | grep -c "$id"
podman healthcheck run notes-api && echo "gesund"
podman exec notes-api sh; echo "Exit: $?"Expected:
1
gesund
Error: crun: executable file `sh` not found in $PATH: No such file or directory: OCI
runtime attempted to invoke a command that was not found
Exit: 127
notes-api is a scratch image without a shell.
exec can only start what is in the image.
Save your progress? Sign up for free
Drill 6: Rootful versus rootless
sudo podman is a completely separate Podman – with its
own storage:
podman images --format '{{.Repository}}:{{.Tag}}' | grep nginx
sudo podman images
podman info --format '{{.Store.GraphRoot}}'
sudo podman info --format '{{.Store.GraphRoot}}'Expected:
docker.io/library/nginx:1.30.6-alpine
REPOSITORY TAG IMAGE ID CREATED SIZE
/home/ubuntu/.local/share/containers/storage
/var/lib/containers/storage
Root does not see your images, and you do not see its images. The same nginx, rootful:
sudo podman run -d --name web-root -p 127.0.0.1:81:80 \
docker.io/library/nginx:1.30.6-alpine
sudo podman top web-root user huser args
sudo podman inspect web-root --format '{{.NetworkSettings.IPAddress}}'
curl -sI http://127.0.0.1:81 | head -1Expected (abridged):
Trying to pull docker.io/library/nginx:1.30.6-alpine...
…
6a40e9e5dfc1…
USER HUSER COMMAND
root root nginx: master process nginx -g daemon off;
nginx messagebus nginx: worker process
nginx messagebus nginx: worker process
10.88.0.2
HTTP/1.1 200 OK
- In rootful mode, root in the container is real root
on the host. And on Ubuntu, UID 101 happens to be
messagebus– an escape would land with a real system user. - In rootful mode, the container gets an IP in the bridge
podman0(10.88.0.0/16), and port 81 is no problem. Rootless, that does not work this way (Day 2).
Clean up – rootful remains the exception in the book:
sudo podman rm -f web-root
sudo podman rmi docker.io/library/nginx:1.30.6-alpineExpected (abridged):
web-root
Untagged: docker.io/library/nginx:1.30.6-alpine
Deleted: 88f52f3d58a5…
Save your progress? Sign up for free
Drill 7: podman info
podman info tells you how your Podman is set up. The
most important fields:
podman info --format json | jq '{rootless: .host.security.rootless,
arch: .host.arch, cgroup: .host.cgroupVersion, runtime: .host.ociRuntime.name,
net: .host.networkBackend, rootlessNet: .host.rootlessNetworkCmd,
driver: .store.graphDriverName, graphRoot: .store.graphRoot,
runRoot: .store.runRoot, uidmap: .host.idMappings.uidmap}'Expected:
{
"rootless": true,
"arch": "arm64",
"cgroup": "v2",
"runtime": "crun",
"net": "netavark",
"rootlessNet": "pasta",
"driver": "overlay",
"graphRoot": "/home/ubuntu/.local/share/containers/storage",
"runRoot": "/run/user/1000/containers",
"uidmap": [
{
"container_id": 0,
"host_id": 1000,
"size": 1
},
{
"container_id": 1,
"host_id": 100000,
"size": 65536
}
]
}
| Field | Meaning |
|---|---|
runtime |
crun starts the containers (instead of runc) |
net, rootlessNet |
netavark for networks, pasta for the rootless network |
graphRoot |
images and container layers of your user |
runRoot |
runtime data in RAM, gone after a reboot |
uidmap |
UID 0 → 1000, UID 1… → 100000… (Day 2) |
This is configured via files in /etc/containers/
(system) and ~/.config/containers/ (user):
registries.conf, storage.conf,
containers.conf.
Save your progress? Sign up for free
Checkpoint
The three images are built:
cd ~/ct-lab/tag01
podman images --filter reference='localhost/notes-*:0.1.0' --format '{{.Repository}}'Expected:
localhost/notes-worker
localhost/notes-web
localhost/notes-api
The healthcheck is in the image, the container is healthy:
podman image inspect localhost/notes-api:0.1.0 --format '{{.Config.Healthcheck.Test}}'
podman ps --filter name=notes-api --format '{{.Status}}'Expected (time will differ):
[CMD /notes-api healthcheck]
Up 19 seconds (healthy)
/version returns 0.1.0:
curl -s 127.0.0.1:8080/version; echoExpected:
0.1.0
Rootful is cleaned up, your own alias is removed:
sudo podman ps -aq | wc -l
ls ~/.config/containers/registries.conf.d/Expected: no rootful container, the directory is empty.
0
Challenge
Get localhost/notes-api:0.1.0 into root’s storage,
without rebuilding and without a registry. The image ID must be the same
rootless and rootful.
Hint: podman save writes an image as an
archive to stdout, podman load reads it from stdin.
Solution
podman save localhost/notes-api:0.1.0 | sudo podman load
podman images --format '{{.ID}}' localhost/notes-api:0.1.0
sudo podman images --format '{{.ID}} {{.Repository}}:{{.Tag}}'Expected (abridged):
Copying blob sha256:bd1c1408ba45…
Copying blob sha256:eac76113fc08…
Copying config sha256:70cfecc8196f…
Writing manifest to image destination
Loaded image: localhost/notes-api:0.1.0
70cfecc8196f
70cfecc8196f localhost/notes-api:0.1.0
Same ID means same configuration and same layers. For copying between
hosts there is podman image scp, which works exactly like
this internally. Back to the state of the day:
sudo podman rmi localhost/notes-api:0.1.0
podman rm -f notes-apiExpected:
Untagged: localhost/notes-api:0.1.0
Deleted: 70cfecc8196f…
notes-api
Save your progress? Sign up for free
Enterprise Note
- Rootless is the right default for developers and most services. Rootful only where there is no other way (ports < 1024 without a sysctl, devices, certain networks).
unqualified-search-registriesstays empty in production. Aliases, if at all, are distributed centrally in/etc/containers/registries.conf.d/.- Instead of
docker.iodirectly: an internal pull-through cache or mirror via a[[registry]]entry withmirrorinregistries.conf– then Docker Hub rate limits and outages do not hit you. - Build images with
HEALTHCHECKin Docker format or specify the healthcheck at start (--health-cmd, QuadletHealthCmd=, Day 3). - Ubuntu LTS delivers Podman updates only as security backports. If you need new features, plan the move to the next LTS instead of mixing in third-party packages.