Skip to content
Hands-on IT IT Drills

Day 4: Socket, Compose and terminal UIs

Goal: Give Podman a Docker-compatible API, start notes with podman compose and watch the containers with lazydocker, ctop and podman 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 service on the first request.
  • The socket speaks the Docker API (and its own libpod API). Tools built for Docker find it via DOCKER_HOST.
  • podman compose is just a wrapper: it calls docker-compose or podman-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.service

Expected:

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

Expected:

    * 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' ' -f2

Expected:

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 version

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

Expected:

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 up fails with internal libpod error.
  • podman-compose 1.5 understands depends_on with service_healthy and service_completed_successfully – migrate runs only after the healthcheck, api only after migrate.
  • podman-compose names containers <project>_<service>_1 and puts them into a pod pod_notes without an infra container. Degraded means: 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.service

Expected:

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

Expected:

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:

lazydocker

Expected (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 with systemctl --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
ctop

Expected (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 ~/.bashrc

Expected:

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

Expected:

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

Expected (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.yaml files 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 service or 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.