Skip to content
Hands-on IT IT Drills

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 podman call 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.conf

Expected:

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.conf defines which registries Podman searches for names without a registry. On Ubuntu the list is empty.
  • shortnames.conf contains fixed aliases for well-known images. golang, node and python are in it, nginx and postgres are 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.conf

Expected (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 conmon

Expected (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
  • HUSER is the user on the host. root in the container is ubuntu (UID 1000), user nginx (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 -a

Expected:

web
web
CONTAINER ID  IMAGE       COMMAND     CREATED     STATUS      PORTS       NAMES

Tip: The Ubuntu package podman-docker creates /usr/bin/docker as a redirect to podman. Useful for scripts that have docker hard-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-api

Expected (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 build is built-in Buildah (Day 5). It understands --mount=type=cache, --link and $BUILDPLATFORM just 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 golang via 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-api

Expected (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 -1

Expected (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-alpine

Expected (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; echo

Expected:

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-api

Expected:

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-registries stays empty in production. Aliases, if at all, are distributed centrally in /etc/containers/registries.conf.d/.
  • Instead of docker.io directly: an internal pull-through cache or mirror via a [[registry]] entry with mirror in registries.conf – then Docker Hub rate limits and outages do not hit you.
  • Build images with HEALTHCHECK in Docker format or specify the healthcheck at start (--health-cmd, Quadlet HealthCmd=, 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.