Day 4: Socket, Compose and terminal UIs
Goal: Give Podman a Docker-compatible API, start notes with
podman composeand watch the containers with lazydocker, ctop andpodman stats/events. · Duration: approx. 60 min · Prerequisite: Day 3
Briefing
- Podman has no daemon – but, if you want, a socket.
systemd listens and only starts
podman system serviceon the first request. - The socket speaks the Docker API (and its own
libpod API). Tools built for Docker find it via
DOCKER_HOST. podman composeis just a wrapper: it callsdocker-composeorpodman-compose. You have to install one of them.- lazydocker and ctop are terminal
UIs on top of the Docker API. ctop has had no release since 2022 – its
successors are lazydocker and
podman stats.
lazydocker, ctop, docker-compose, curl
│ DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
▼
podman.socket ──(first request)──► podman.service ──► containers, pods, images
(podman system service)
podman compose ──► podman-compose ──► podman CLI (no socket)
Drill 1: The Podman socket
Start of the day with the state of Day 3 – the Quadlet pod is running:
source ~/ct-lab/setup/env.sh
mkdir -p ~/ct-lab/tag04 && cd ~/ct-lab/tag04
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag03/notes/." .
systemctl --user cat podman.socket --no-pager | grep -v -E '^#|^$'
systemctl --user enable --now podman.socket
systemctl --user status podman.socket --no-pager | sed -n 1,5p
ls -l "$XDG_RUNTIME_DIR/podman/podman.sock"Expected (abridged, times will differ on your machine):
[Unit]
Description=Podman API Socket
Documentation=man:podman-system-service(1)
[Socket]
ListenStream=%t/podman/podman.sock
SocketMode=0660
[Install]
WantedBy=sockets.target
Created symlink '/home/ubuntu/.config/systemd/user/sockets.target.wants/podman.socket' …
● podman.socket - Podman API Socket
Loaded: loaded (/usr/lib/systemd/user/podman.socket; enabled; preset: enabled)
Active: active (listening) since Fri 2026-10-30 19:07:21 UTC; 24ms ago
Invocation: 135b8d7ff0894925aa205b0507659c30
Triggers: ● podman.service
srw-rw---- 1 ubuntu ubuntu 0 Oct 30 19:07 /run/user/1000/podman/podman.sock
%t is $XDG_RUNTIME_DIR, so
/run/user/1000. The socket belongs to you, mode 0660: only
you (and root) talk to your Podman. Rootful, it would live at
/run/podman/podman.sock.
S="$XDG_RUNTIME_DIR/podman/podman.sock"
curl -s --unix-socket "$S" http://d/_ping; echo
curl -s --unix-socket "$S" http://d/version \
| jq '{Version, ApiVersion, MinAPIVersion, Arch, C: [.Components[].Name]}'
systemctl --user is-active podman.serviceExpected:
OK
{
"Version": "5.7.0",
"ApiVersion": "1.41",
"MinAPIVersion": "1.24",
"Arch": "arm64",
"C": [
"Podman Engine",
"Conmon",
"OCI Runtime (crun)"
]
}
active
ApiVersion 1.41 is the Docker API version that Podman
emulates. The hostname d in the URL is arbitrary – curl
needs one, the socket ignores it. The first request started
podman.service; after a few seconds without requests it
exits again.
Save your progress? Sign up for free
Drill 2: Docker API and
DOCKER_HOST
Two APIs on the same socket: /v1.41/… (Docker) and
/v5.0.0/libpod/… (Podman, knows pods):
curl -s --unix-socket "$S" http://d/v1.41/containers/json \
| jq -r '.[] | "\(.Names[0]) \(.State)"'
curl -s --unix-socket "$S" http://d/v5.0.0/libpod/pods/json \
| jq -r '.[] | "\(.Name) \(.Status) \(.Containers | length)"'
echo "export DOCKER_HOST=unix://\$XDG_RUNTIME_DIR/podman/podman.sock" >> ~/.bashrc
export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock"
podman --remote ps --format '{{.Names}}'Expected:
/notes-infra running
/notes-db running
/notes-api running
/notes-web running
notes Running 4
notes-infra
notes-db
notes-web
notes-api
podman --remote is Podman as a pure client over the
socket – that is exactly how Podman works on the Mac with its VM. From
now on, DOCKER_HOST is in ~/.bashrc; all tools
in this chapter read the variable.
Save your progress? Sign up for free
Drill 3: podman compose and its
provider
podman compose version 2>&1 | tail -3Expected:
* exec: "/usr/libexec/docker/cli-plugins/docker-compose": stat /usr/libexec/docker/c…
* exec: "docker-compose": executable file not found in $PATH
* exec: "podman-compose": executable file not found in $PATH
podman compose first looks for the Docker Compose plugin
(~/.docker/cli-plugins,
/usr/libexec/docker/cli-plugins …), then for
docker-compose and podman-compose in the
PATH. On Ubuntu 26.04 there are two packages:
apt-cache policy podman-compose docker-compose-v2 | grep -E '^[a-z]|Candidate'
apt-get install -s docker-compose-v2 | grep '^Inst' | cut -d' ' -f2Expected:
podman-compose:
Candidate: 1.5.0-2
docker-compose-v2:
Candidate: 2.40.3+ds1-0ubuntu1
pigz
bridge-utils
runc
containerd
dns-root-data
dnsmasq-base
docker-compose-v2
docker.io
ubuntu-fan
docker-compose-v2 pulls in the whole Docker Engine
including containerd – that would clash with Day 6. So
podman-compose it is, a Python program that translates
the Compose file into podman calls:
| Profile | podman-compose |
|---|---|
| Purpose | Run Compose files with Podman (provider for
podman compose) |
| Special feature | calls the podman CLI directly, needs no socket |
| Project | github.com/containers/podman-compose |
| Version in the book | 1.5.0 (Ubuntu package podman-compose) |
sudo apt-get install -y podman-compose
podman compose versionExpected (abridged):
>>>> Executing external compose provider "/usr/bin/podman-compose". Please see podman…
podman version 5.7.0
podman-compose version 1.5.0
You turn off the notice about the external provider in
containers.conf:
mkdir -p ~/.config/containers
cat > ~/.config/containers/containers.conf <<'EOF'
# ~/.config/containers/containers.conf – Stand Ende Tag 4
[engine]
compose_warning_logs = false
EOF
podman compose versionExpected:
podman version 5.7.0
podman-compose version 1.5.0
Save your progress? Sign up for free
Drill 4: notes with
podman compose
The same containers as the Quadlet pod, this time as a Compose file.
The volume is the one from Day 2 and 3 (external):
cat > compose.yaml <<'EOF'
# compose.yaml – Stand Ende Tag 4
name: notes
services:
db:
image: docker.io/library/postgres:18.6-alpine
environment:
POSTGRES_USER: notes
POSTGRES_DB: notes
POSTGRES_PASSWORD: lab-db-pw-123
volumes:
- pgdata:/var/lib/postgresql
healthcheck:
test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "notes", "-d", "notes"]
interval: 2s
retries: 30
migrate:
image: localhost/notes-api:0.1.0
command: ["migrate"]
environment:
NOTES_DB_URL: postgres://notes:lab-db-pw-123@db:5432/notes
depends_on:
db:
condition: service_healthy
api:
image: localhost/notes-api:0.1.0
environment:
NOTES_API_KEY: lab-api-key-123
NOTES_DB_URL: postgres://notes:lab-db-pw-123@db:5432/notes
ports:
- "127.0.0.1:8080:8080"
depends_on:
migrate:
condition: service_completed_successfully
web:
image: localhost/notes-web:0.1.0
environment:
NOTES_API_URL: http://api:8080
NOTES_API_KEY: lab-api-key-123
ports:
- "127.0.0.1:3000:3000"
depends_on: [api]
worker:
image: localhost/notes-worker:0.1.0
environment:
NOTES_API_URL: http://api:8080
NOTES_API_KEY: lab-api-key-123
depends_on: [api]
volumes:
pgdata:
external: true
name: notes-pgdata # dasselbe Volume wie der Quadlet-Pod (Tag 3)
EOF
systemctl --user stop notes-pod.service
sleep 3
podman compose up -d
sleep 3
podman ps -a --format '{{.Names}}\t{{.Status}}'
curl -s -X POST 127.0.0.1:3000/api/notes -H 'Content-Type: application/json' \
-d '{"text":"Tag 4 mit podman compose"}'; echo
sleep 10
podman compose logs worker | tail -1
podman pod ps --format '{{.Name}} {{.Status}} {{.NumberOfContainers}}'Expected (abridged):
e9f39aea43f8…
…
notes_db_1
notes_migrate_1
notes_api_1
notes_web_1
notes_worker_1
notes_db_1 Up 11 seconds (healthy)
notes_migrate_1 Exited (0) 4 seconds ago (stopped)
notes_api_1 Up 6 seconds (healthy)
notes_web_1 Up 5 seconds
notes_worker_1 Up 4 seconds
{"id":"f498e6c0-…","text":"Tag 4 mit podman compose"}
summary: 3 notes, 13 words
pod_notes Degraded 5
- The Quadlet pod has to go first: it occupies the same ports. The
three-second pause is needed until pasta has released the ports –
otherwise
upfails withinternal libpod error. - podman-compose 1.5 understands
depends_onwithservice_healthyandservice_completed_successfully– migrate runs only after the healthcheck, api only after migrate. - podman-compose names containers
<project>_<service>_1and puts them into a podpod_noteswithout an infra container.Degradedmeans: not all containers are running (migrate has finished).
Tear down and bring back the Quadlet pod:
podman compose down >/dev/null 2>&1
podman volume ls -q
systemctl --user start notes-pod.serviceExpected:
notes-pgdata
down leaves the external volume alone – you will see
today’s note in the Quadlet pod in a moment.
Save your progress? Sign up for free
Drill 5: lazydocker
| Profile | lazydocker |
|---|---|
| Purpose | Manage containers, images, volumes, networks and Compose projects in the terminal |
| Special feature | speaks only the Docker API; logs, stats and actions at a keystroke |
| Project | github.com/jesseduffield/lazydocker |
| Version in the book | 0.25.2 (release binary) |
Installed with the principle from Day 0 – download, verify, unpack, install:
mkdir -p /tmp/dl && cd /tmp/dl
B=https://github.com/jesseduffield/lazydocker/releases/download/v0.25.2
curl -fsSLO "$B/lazydocker_0.25.2_Linux_arm64.tar.gz"
curl -fsSLO "$B/checksums.txt"
sha256sum -c --ignore-missing checksums.txt
grep '^lazydocker arm64' ~/ct-lab/setup/tools.lock | awk '{print $4}'
tar -xzf lazydocker_0.25.2_Linux_arm64.tar.gz lazydocker
sudo install -m 0755 lazydocker /usr/local/bin/
cd ~ && rm -rf /tmp/dl
lazydocker --version | head -1Expected:
lazydocker_0.25.2_Linux_arm64.tar.gz: OK
005c38b685aaa557e7d646d83a3dadb5024340eeed8c6a2e1949eee6f530de23
Version: 0.25.2
The same checksum is in tools.lock; on Day 0 you already
installed lazydocker this way. How lazydocker works: it
reads containers, images, volumes and networks via
DOCKER_HOST, shows logs and statistics live and performs
actions as API calls. Start it:
lazydockerExpected (abridged, excerpt of the screen):
╭─[3]─Containers────────────────────╮╭─Logs - Stats - Env - Config - Top──────────────
│running (healthy) notes-api 0.00%││time=2026-10-30T19:10:24.645Z level=INFO msg="ap…
│running (healthy) notes-db 0.00%││source=env
│running notes-infra 0.00%││time=2026-10-30T19:10:24.688Z level=INFO msg="st…
│running notes-web 0.00%││store=postgres
╰───────────────────────────────────╯│
╭─[4]─Images────────────────────────╮│
│docker.io/library/golang 1.27-alp▐│
│docker.io/library/nginx 1.30.6-a▐│
╭─[5]─Volumes───────────────────────╮│
│local notes-pgdata ││
╭─[6]─Networks──────────────────────╮│
│bridge bridge ││
│bridge notes ││
PgUp/PgDn: scroll, b: view bulk commands, q: quit, x: menu, ← → ↑ ↓: navigate …
| Key | Effect |
|---|---|
1…6 |
Select panel (project, services, containers, images, volumes, networks) |
[ ] |
Switch tabs on the right: Logs, Stats, Env, Config, Top |
s r d |
Stop, restart, remove container |
E |
Shell in the container (not for notes-api: scratch) |
x |
Menu with all keys of the panel, q quits |
Select notes-db with 3 and the arrow keys,
then press ] twice: the Stats tab draws
CPU and memory as a graph. The network podman is called
bridge in the Docker API.
Warning: If you stop a Quadlet container in lazydocker, systemd does not restart it (
Restart=on-failure, a stop is not a failure) – and the pod counts as modified afterwards. You control services under systemd withsystemctl --user.
For Compose projects, lazydocker calls docker compose.
With Podman, you change that in the configuration:
mkdir -p ~/.config/lazydocker
cat > ~/.config/lazydocker/config.yml <<'EOF'
# ~/.config/lazydocker/config.yml – Stand Ende Tag 4
commandTemplates:
dockerCompose: podman compose
EOF
lazydocker -c | grep -E '^commandTemplates:|dockerCompose:'Expected:
commandTemplates:
dockerCompose: docker compose
lazydocker -c shows the default values
– useful for looking up keys. Your file overrides only what is in
it.
Save your progress? Sign up for free
Drill 6: ctop – briefly, and why it is outdated
| Profile | ctop |
|---|---|
| Purpose | top for containers: CPU, memory, network, I/O per
container |
| Special feature | very lean; last release March 2022, with the Docker client of that time |
| Project | github.com/bcicen/ctop |
| Version in the book | 0.7.7 (release binary, outdated) |
ctop ships a single binary and a sha256sums.txt:
mkdir -p /tmp/dl && cd /tmp/dl
B=https://github.com/bcicen/ctop/releases/download/v0.7.7
curl -fsSLO "$B/ctop-0.7.7-linux-arm64"
curl -fsSLO "$B/sha256sums.txt"
sha256sum -c --ignore-missing sha256sums.txt
sudo install -m 0755 ctop-0.7.7-linux-arm64 /usr/local/bin/ctop
cd ~ && rm -rf /tmp/dl
ctop -v
ctopExpected (abridged):
ctop-0.7.7-linux-arm64: OK
ctop version 0.7.7, build 11a1cb1 go1.18
ctop - 19:11:23 UTC 4 containers
NAME CID CPU MEM NET RX/TX IO R/W PIDS
☼ ⏵ notes-api f48edfd6bc33 0% 2M / 4G 2K / 768B 0B / 0B 8
☼ ⏵ notes-db 4cc55748f48a 0% 26M / 4G 2K / 768B 0B / 0B 10
⏵ notes-infra a257f0f173d1 0% 228K / 4G 2K / 768B 0B / 0B 1
⏵ notes-web ae2cdb9f404c 0% 20M / 4G 2K / 768B 0B / 0B 7
ctop runs against the Podman socket, q quits.
☼ marks containers with a healthcheck. Why only briefly,
then? There has been no release since version 0.7.7 (March 2022), built
with Go 1.18 – security fixes in Go and in the Docker client never
arrive, and it does not know new API fields. Besides
docker, ctop -h shows only the connector
runc. Everything ctop can do, lazydocker can do in its
Stats tab – or Podman itself.
Save your progress? Sign up for free
Drill 7: podman stats and
podman events
podman stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'
podman pod stats --no-stream --format '{{.Pod}} {{.Name}} {{.MemUsage}}'Expected (abridged, values will differ):
NAME CPU % MEM USAGE / LIMIT
notes-infra 0.01% 233.5kB / 4.199GB
notes-db 1.28% 27.01MB / 4.199GB
notes-api 0.26% 2.105MB / 4.199GB
notes-web 0.66% 20.46MB / 4.199GB
POD NAME MEM USAGE/ LIMIT
3e0841db589b notes-api 2.003MB / 4.199GB
3e0841db589b notes-infra 344.1kB / 4.199GB
3e0841db589b notes-db 25.31MB / 4.199GB
3e0841db589b notes-web 26.62MB / 4.199GB
Without --no-stream, the display refreshes like ctop.
Events tell you what happens – live in a second
terminal or in retrospect:
podman kill notes-api >/dev/null
sleep 15
podman events --since 30s --until 1s --filter container=notes-api \
--format '{{.Status}} {{.Name}}'
podman events --since 30s --until 1s --filter container=notes-api \
--filter event=died --format json | jq -c '{Name, ContainerExitCode}'Expected (abridged):
kill notes-api
died notes-api
remove notes-api
create notes-api
init notes-api
start notes-api
health_status notes-api
{"Name":"notes-api","ContainerExitCode":137}
The whole restart from Day 3 as events: killed, removed
(--rm), recreated, started, healthcheck. Without
--until, podman events keeps running and shows
new events until you stop it with Ctrl+C.
Save your progress? Sign up for free
Checkpoint
The Podman socket is enabled and responds:
cd ~/ct-lab/tag04
systemctl --user is-enabled podman.socket
curl -s --unix-socket "$XDG_RUNTIME_DIR/podman/podman.sock" http://d/_ping; echo
grep DOCKER_HOST ~/.bashrcExpected:
enabled
OK
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
Compose provider and a valid file:
podman compose version
podman compose config -q; echo "Exit: $?"Expected (abridged):
Docker Compose version v5.6.1
Exit: 0
The two TUIs:
lazydocker --version | head -1
ctop -vExpected:
Version: 0.25.2
ctop version 0.7.7, build 11a1cb1 go1.18
The Quadlet pod is running and has the note from Drill 4:
systemctl --user is-active notes-pod.service
curl -s 127.0.0.1:8080/notes | jq -r '.[].text'Expected:
active
Tag 2 im Pod
Tag 3 mit Quadlet
Tag 3 mit Quadlet
Tag 4 mit podman compose
Challenge
Start the same compose.yaml with the original
Docker Compose over the Podman socket – without a
Docker Engine and without docker-compose-v2 from apt.
Hint: Docker Compose is available as a single binary
at github.com/docker/compose/releases;
podman compose looks for it first in
~/.docker/cli-plugins/.
Solution
mkdir -p /tmp/dl && cd /tmp/dl
B=https://github.com/docker/compose/releases/download/v5.6.1
curl -fsSLO "$B/docker-compose-linux-aarch64"
curl -fsSLO "$B/checksums.txt"
sha256sum -c --ignore-missing checksums.txt
mkdir -p ~/.docker/cli-plugins
install -m 0755 docker-compose-linux-aarch64 ~/.docker/cli-plugins/docker-compose
cd ~/ct-lab/tag04 && rm -rf /tmp/dl
podman compose version
systemctl --user stop notes-pod.service
sleep 3
podman compose up -d 2>&1 | tail -3
sleep 2
podman ps -a --format '{{.Names}}\t{{.Status}}'Expected (abridged):
docker-compose-linux-aarch64: OK
Docker Compose version v5.6.1
Container notes-worker-1 Starting
Container notes-web-1 Started
Container notes-worker-1 Started
notes-db-1 Up 4 seconds (healthy)
notes-migrate-1 Exited (0) 3 seconds ago (starting)
notes-api-1 Up 3 seconds (healthy)
notes-worker-1 Up 2 seconds
notes-web-1 Up 2 seconds
Docker Compose talks to the socket via DOCKER_HOST and
names the containers as usual, notes-db-1. Back to the
state of the day – down twice because of the AppArmor trap
from Day 2 (custom network notes_default):
podman compose down 2>&1 | tail -1
podman compose down 2>&1 | tail -1
rm ~/.docker/cli-plugins/docker-compose
systemctl --user start notes-pod.service
podman compose version | tail -1Expected (abridged):
Error: executing /home/ubuntu/.docker/cli-plugins/docker-compose down: exit status 1
Network notes_default Removed
podman-compose version 1.5.0
Without the plugin, podman-compose is the provider again.
Save your progress? Sign up for free
Enterprise Note
- The socket is equivalent to root for the user who owns it: whoever reaches it can start arbitrary containers. Never expose it via TCP without mTLS, never mount it into containers that do not absolutely need it.
- For servers, Quadlet (Day 3) is the better way than Compose: systemd dependencies, restarts, logs in the journal, no additional Python program.
- Teams with existing
compose.yamlfiles usually get better compatibility with Docker Compose over the Podman socket than with podman-compose; the version then belongs in a lock file. - TUIs like lazydocker are tools for humans. For operations, metrics
belong in monitoring (Prometheus via
podman system serviceor cAdvisor) and events in central logging. - Tools without releases (ctop) get dropped from the lock file: a binary that no longer moves only collects vulnerabilities.