Most of the commands in podman is same as docker, it is easy to replace docker with podman. The difference is:

1. When you running container by using docker, as docker is a client-server architecture, docker use a daemon to run container, podman run container directly;

2. If you don’t specify the user and group, the user and group you running podman command will be used;

3. A configuration file is required to run podman, save it to /etc/containers/registries.conf:

   unqualified-search-registries = ['docker.io']
   
   [[registry]]
   # In Nov. 2020, Docker rate-limits image pulling.  To avoid hitting these
   # limits while testing, always use the google mirror for qualified and
   # unqualified `docker.io` images.
   # Ref: https://cloud.google.com/container-registry/docs/pulling-cached-images
   prefix="docker.io"
   location="mirror.gcr.io"
   
   # 2020-10-27 a number of images are not present in gcr.io, and podman
   # barfs spectacularly when trying to fetch them. We've hand-copied
   # those to quay, using skopeo copy --all ...
   [[registry]]
   prefix="docker.io/library"
   location="mirror.gcr.io"
   

Nearly all the containers works fine in my homelab, except 2 cases:

Create a pod in podman when you’re using link in docker

I have a container with a link in docker:

#!/bin/bash
 
docker rm -f aria2-server
docker rm -f aria2-webui
 
docker pull p3terx/aria2-pro
docker pull p3terx/ariang
 
docker run -d \
    --name aria2-server \
    --restart unless-stopped \
    --log-opt max-size=1m \
    -e PUID=$UID \
    -e PGID=$GID \
    -e UMASK_SET=022 \
    -e RPC_SECRET="<YOUR_SECRET>" \
    -e RPC_PORT=6800 \
    -p 6800:6800 \
    -e LISTEN_PORT=6888 \
    -v /path/to/config:/config \
    -v /path/to/downloads:/downloads \
    p3terx/aria2-pro
 
 
docker run -d \
    --name aria2-webui \
    --log-opt max-size=1m \
    --restart unless-stopped \
    --link aria2-server \
    -p 6880:6880 \
    p3terx/ariang

when you replace docker with podman, it will fail:

Error: unknown flag: --link
See 'podman run --help'

It is because podman doesn’t support the --link option. The workaround is create a pod first:

#!/bin/bash

podman rm -f aria2-server
podman rm -f aria2-webui

podman pull p3terx/aria2-pro
podman pull p3terx/ariang

podman pod create --name aria2-pod --publish 6880:6880 --publish 6888:6888 --publish 6800:6800/udp

podman run -d \
    --name aria2-server \
    --pod aria2-pod \
    --restart unless-stopped \
    --log-opt max-size=1m \
    -e PUID=$UID \
    -e PGID=$GID \
    -e UMASK_SET=022 \
    -e RPC_SECRET="<YOUR_SECRET>" \
    -e RPC_PORT=6800 \
    -e LISTEN_PORT=6888 \
    -v /data/apps/aria2/config:/config \
    -v /data/hdd/share/media/downloads:/downloads \
    p3terx/aria2-pro


podman run -d \
    --name aria2-webui \
    --pod aria2-pod \
    --log-opt max-size=1m \
    --restart unless-stopped \
    p3terx/ariang

Run podman with woodpecker

When I run podman with woodpecker, it will fail in woodpecker-agent:

{"level":"info","time":"2025-03-20T04:07:23Z","message":"log level: info"}
{"level":"info","time":"2025-03-20T04:07:23Z","message":"no agent config found at '/etc/woodpecker/agent.conf', start with defaults"}
{"level":"error","engine":"docker","time":"2025-03-20T04:07:23Z","message":"selected backend engine is unavailable"}
{"level":"info","time":"2025-03-20T04:07:23Z","message":"shutdown of whole agent"}
{"level":"fatal","error":"selected backend engine docker is unavailable","time":"2025-03-20T04:07:23Z","message":"error running agent"}
{"level":"info","time":"2025-03-20T04:07:24Z","message":"log level: info"}
{"level":"info","time":"2025-03-20T04:07:24Z","message":"no agent config found at '/etc/woodpecker/agent.conf', start with defaults"}
{"level":"error","engine":"docker","time":"2025-03-20T04:07:24Z","message":"selected backend engine is unavailable"}
{"level":"info","time":"2025-03-20T04:07:24Z","message":"shutdown of whole agent"}
{"level":"fatal","error":"selected backend engine docker is unavailable","time":"2025-03-20T04:07:24Z","message":"error running agent"}

podman woodpecker agent

It is because woodpecker doesn’t support podman officially, it needs some hack:

podman run -d \
  --name woodpecker-agent \
  --pod woodpecker-pod \
  --restart always \
  --security-opt label=disable \
  --privileged \
  --pid=host \
  -v /run/user/1000/podman/podman.sock:/run/podman/podman.sock:z \
  -e DOCKER_HOST="unix:///run/podman/podman.sock" \
  -e WOODPECKER_BACKEND="docker" \
  -e WOODPECKER_SERVER=woodpecker-server:8010 \
  -e WOODPECKER_AGENT_SECRET=$WOODPECKER_AGENT_SECRET \
  -e WOODPECKER_MAX_WORKFLOWS=4 \
  woodpeckerci/woodpecker-agent:v3.4 agent

Conclusion

After replacing docker with podman, it is easy to run container in homelab, and I can manage all my containers in both command line and cockpit, which is very useful.