podman

name	podman
description	Use when the user asks about Podman, rootless containers, Quadlet/systemd units, Podman Compose, or migrating Docker workflows to Podman. Creates and manages rootless Podman containers, maps Docker commands, configures podman run/build/compose flows, and sets up systemd-managed services.
metadata	{"references":["references/rootless-containers.md","references/docker-compatibility.md","references/operations-and-troubleshooting.md"],"assets":["assets/podman-compose-example.yml","assets/quadlet-example.container"]}

Podman

Primary Actions

• Run and manage rootless Podman containers.
• Translate Docker workflows to Podman equivalents.
• Configure Podman Compose for multi-service stacks.
• Create systemd-managed services using Quadlet.
• Troubleshoot rootless, socket, and service lifecycle issues.

Quick Command Map (Differences from Docker)

# Docker socket compatibility
systemctl --user enable --now podman.socket
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock

# Pod operations (Podman-specific)
podman pod create --name app-pod

# Quadlet service management
systemctl --user daemon-reload
systemctl --user enable --now my-service

Rootless Container Example

# Run a container without root — this is the Podman default
podman run --rm -it alpine sh

# Verify rootless mode
podman info --format '{{ .Host.Security.Rootless }}'   # should print: true

# Verify user namespace mapping (uid 0 in container = your UID on host)
podman unshare cat /proc/self/uid_map

Quadlet Unit Example

Place .container files in ~/.config/containers/systemd/ (user) or /etc/containers/systemd/ (system):

# ~/.config/containers/systemd/myapp.container
[Unit]
Description=My App Container

[Container]
Image=docker.io/library/nginx:alpine
PublishPort=8080:80
Volume=%h/data:/usr/share/nginx/html:Z

[Service]
Restart=always

[Install]
WantedBy=default.target

# Load and start
systemctl --user daemon-reload
systemctl --user enable --now myapp

# Validate
systemctl --user status myapp
journalctl --user -u myapp -n 50

See assets/quadlet-example.container for a more complete example.

Translate Docker → Podman

Docker	Podman	Notes
docker run	podman run	Identical flags; rootless by default
docker build	podman build	Identical Dockerfile syntax
docker ps	podman ps	Same output
docker compose up	podman-compose up	Or use Docker Compose CLI via socket
docker system prune	podman system prune	Same
Daemon required	No daemon	Podman is daemonless

Validation Workflow

1. Verify rootless mode:

   podman info --format '{{ .Host.Security.Rootless }}'   # → true
   podman unshare cat /proc/self/uid_map                   # → uid mapping present
   

2. Run a basic rootless container:

   podman run --rm hello-world
   

3. For Compose, validate config before up:

   podman-compose config
   podman-compose up --dry-run   # if supported by your version
   

4. For Quadlet, verify systemd unit status and logs:

   systemctl --user status myapp
   journalctl --user -u myapp --since "5 minutes ago"
   

5. If failures occur, fix and re-run the relevant check.

Deep References

• Rootless architecture, networking, volume permissions: references/rootless-containers.md
• Docker compatibility details and known differences: references/docker-compatibility.md
• Validation and troubleshooting playbook: references/operations-and-troubleshooting.md