ansible-playbooks/roles/podman/README.md

Podman Role

This Ansible role installs and configures Podman for container management on NAS/homelab systems.

Features

• Installs Podman and podman-compose
• Configures container registry search paths
• Creates shared projects directory for compose files
• Enables short image name resolution (e.g., redis:alpine → docker.io/library/redis:alpine)
• Creates external networks for services (e.g., dedicated Immich network)

Requirements

• systemd-based Linux distribution
• Root/sudo access

Role Variables

See defaults/main.yml for all available variables and their default values.

Key Configuration

Unqualified Search Registries

When you use short image names (without registry prefix), Podman searches configured registries in order (e.g., redis:alpine → docker.io/library/redis:alpine).

Customize via the podman_unqualified_search_registries variable.

External Networks

The role can create external Podman networks for services that need dedicated network isolation. Define the podman_external_networks list in your inventory. Networks persist across container restarts and compose stack rebuilds. See defaults/main.yml for configuration details.

Dependencies

• containers.podman collection (installed via requirements.yml)

Example Playbook

---
- hosts: servers
  become: true
  roles:
    - role: podman

Custom Configuration

See defaults/main.yml for all available variables. Override in your inventory as needed.

Files Deployed

• /etc/containers/registries.conf - Registry configuration
• {{ podman_projects_dir }} - Projects directory (default: /opt/podman)

Usage

Running Containers

# Using short names (works after role deployment)
podman run -d redis:alpine

# Using fully qualified names (always works)
podman run -d docker.io/library/redis:alpine

Docker Compose

Services using podman-compose should store their compose files in subdirectories:

/opt/podman/
├── immich/
│   └── docker-compose.yml
├── nextcloud/
│   └── docker-compose.yml
└── gitea/
    └── docker-compose.yml

Troubleshooting

Short names not resolving

Check the registries configuration:

cat /etc/containers/registries.conf

Test search order:

podman search redis --limit 3

Permission denied

Ensure the user is in the appropriate groups (handled by Podman package):

# Check groups
groups $USER

# May need to log out and back in after installation

License

MIT

Author Information

Created for managing containerized services in NAS/homelab environments.