podman

name	podman
description	Run, build, and manage OCI containers rootlessly on Bluefin — including Quadlets for persistent systemd-managed services.
domain	cloud-native

Podman

Podman is the default container engine on Bluefin. It is daemonless and rootless by default — containers run as your user with no background service and no root required.

When to Use

• Running containers without a daemon (rootless by default)
• Building container images with a Containerfile or Dockerfile
• Running persistent services as systemd units (Quadlets)
• Replacing Docker workflows on Bluefin DX

When NOT to Use

• GUI applications — use Flatpak instead
• Mutable development environments needing apt/dnf — use Distrobox instead
• One-off package installation — use Homebrew or Distrobox

Key Concepts

Podman is rootless by default on Bluefin. No daemon, no root — containers run as your own user inside a user namespace. This improves security and means you do not need sudo for the vast majority of container operations.

• Container images are stored per-user in ~/.local/share/containers/
• Networking uses slirp4netns or pasta (no host network access by default)
• Volumes and bind mounts live in user space
• Rootful mode (sudo podman) is available for edge cases (see below)

Core Commands

# Pull an image
podman pull docker.io/library/nginx:latest

# Run a container (detached, with port mapping)
podman run -d --name mynginx -p 8080:80 docker.io/library/nginx:latest

# List running containers
podman ps

# List all containers (including stopped)
podman ps -a

# Stop and remove a container
podman stop mynginx && podman rm mynginx

# List local images
podman images

# Build from a Containerfile (or Dockerfile)
podman build -t myapp:latest .

# Execute a command inside a running container
podman exec -it mynginx bash

# View container logs
podman logs mynginx

# Follow logs in real time
podman logs -f mynginx

# Volume management
podman volume create mydata
podman volume ls
podman volume inspect mydata
podman volume rm mydata

# Clean up stopped containers and dangling images
podman system prune

# Remove everything (stopped containers, all images, all volumes)
podman system prune --all --volumes

Podman Desktop

Podman Desktop provides a GUI for managing containers, images, volumes, and Kubernetes workloads.

# Install via Flatpak (recommended on Bluefin)
flatpak install flathub io.podman_desktop.PodmanDesktop

Features:

• Container lifecycle management (start, stop, restart, delete)
• Image building and registry push/pull
• Volume and network management
• Kubernetes YAML generation from running containers
• Extension ecosystem (OpenShift, Kind, Compose, etc.)

Launch from your application menu or run flatpak run io.podman_desktop.PodmanDesktop.

Quadlets — Persistent Services as systemd Units

Quadlets are the recommended way to run persistent containers on Bluefin. They define containers as systemd unit files, giving you automatic startup on login, restart policies, and systemctl management — without Docker Compose or a daemon.

Quadlet files live in ~/.config/containers/systemd/ for user (rootless) services, or /etc/containers/systemd/ for system-wide (rootful) services.

systemd reads these files when you run systemctl --user daemon-reload and generates transient .service units automatically.

Container Unit (most common)

~/.config/containers/systemd/myservice.container

[Unit]
Description=My nginx service
After=network-online.target

[Container]
Image=docker.io/library/nginx:latest
PublishPort=8080:80
Volume=%h/mydata:/usr/share/nginx/html:z
Environment=NGINX_PORT=8080

[Service]
Restart=always

[Install]
WantedBy=default.target

%h expands to your home directory. The :z label on volumes sets the correct SELinux context for shared access.

Activate and manage:

# Reload systemd to pick up new/changed unit files
systemctl --user daemon-reload

# Start the service now
systemctl --user start myservice

# Enable to start automatically on login
systemctl --user enable myservice

# Check status and recent logs
systemctl --user status myservice

# Stop and disable
systemctl --user stop myservice
systemctl --user disable myservice

Volume Unit

Declare a named volume as a Quadlet so it is created before the container starts.

~/.config/containers/systemd/mydata.volume

[Volume]
Label=app=myservice

Reference it from a .container file:

[Container]
Volume=mydata.volume:/data:z

Network Unit

Define a custom network for container isolation.

~/.config/containers/systemd/mynet.network

[Network]
Subnet=10.89.1.0/24
Label=app=myservice

Reference it from a .container file:

[Container]
Network=mynet.network

Auto-Update with Quadlets

Add AutoUpdate=registry to the [Container] section to enable automatic image updates:

[Container]
Image=docker.io/library/nginx:latest
AutoUpdate=registry

Then either run updates manually or enable the built-in timer:

# Manual update check
podman auto-update

# Enable the automatic update timer (runs daily)
systemctl --user enable --now podman-auto-update.timer

# Check timer status
systemctl --user status podman-auto-update.timer

Podman will pull new image digests and restart affected Quadlet services automatically.

Rootful Containers (Rare)

The vast majority of use cases work rootless. Use rootful (sudo podman) only when:

• Binding to ports < 1024 on the host (preferred alternative: use a high port + reverse proxy)
• Manipulating host network namespaces directly
• Certain advanced storage or device operations

sudo podman run -d --name privileged-svc -p 443:443 myimage:latest

Rootful Quadlets go in /etc/containers/systemd/ and are managed with systemctl (no --user flag).

Docker Compatibility

Podman is a drop-in replacement for Docker in almost all cases. Most docker CLI commands work identically with podman.

# Optional: alias docker to podman
echo 'alias docker=podman' >> ~/.bashrc
source ~/.bashrc

Docker Compose

Use podman compose (built-in Compose V2 support) or podman-compose:

# Built-in (recommended — no extra install needed)
podman compose up -d
podman compose down
podman compose logs -f

# Alternative: install podman-compose via Homebrew
brew install podman-compose
podman-compose up -d

Most docker-compose.yml files work unmodified with podman compose. Notable differences:

docker-compose	podman compose
version: field required	version: field optional
Docker socket (/var/run/docker.sock)	Podman socket (/run/user/$UID/podman/podman.sock)
Root by default	Rootless by default

Troubleshooting

Container can't reach the internet (rootless networking)

Rootless containers use userspace networking. Check that slirp4netns or pasta is working:

podman network ls
podman info | grep -i network

# For simple cases, use host networking (no isolation)
podman run --network=host myimage:latest

Port conflict — rootless can't bind to ports < 1024

# Use a high host port and proxy, or run rootful for that container
podman run -p 8080:80 nginx:latest   # host:8080 → container:80

To allow rootless binding to low ports (system-wide, use with care):

sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80

Image pull fails / rate limited

# Authenticate with the registry
podman login docker.io

# Use an unqualified search registry (adds docker.io prefix automatically)
podman pull nginx:latest

SELinux volume mount errors

# Add :z (shared) or :Z (private) label to bind mounts
podman run -v /host/path:/container/path:z myimage

Quadlet service not starting

# Check that daemon-reload was run after adding the unit file
systemctl --user daemon-reload

# View the generated unit to verify it parsed correctly
systemctl --user cat myservice

# Check journal for errors
journalctl --user -u myservice -n 50

Reset everything

# Remove all stopped containers and dangling images
podman system prune --all

# Nuclear reset (removes all containers, images, volumes, networks)
podman system reset

Decision Guide

Need	Tool
Run a container image	Podman
Persistent service (auto-start on login)	Podman + Quadlet
GUI container management	Podman Desktop (Flatpak)
Mutable Linux environment (dnf/apt)	Distrobox
GUI application	Flatpak
Self-hosted homelab services	Podman Quadlets (see homelab skill)
Docker Compose workloads	podman compose

References

• Podman documentation
• Quadlet reference
• Podman Desktop
• Rootless containers guide