archy/docs/adr/001-podman-over-docker.md

ADR-001: Podman Over Docker

Status: Accepted Date: 2026-03

Context

Archipelago needs a container runtime for running applications. Docker and Podman are the two main options.

Decision

Use Podman as the container runtime instead of Docker.

Consequences

Positive

• Rootless by default: Containers run without root privileges, reducing attack surface
• Daemonless: No persistent daemon process; containers are managed as individual processes under systemd
• Docker-compatible: Supports Docker images and most Docker CLI commands
• Systemd integration: Podman containers can be managed as systemd services natively
• No vendor lock-in: OCI-compliant, works with any container registry

Negative

• Smaller ecosystem: Some Docker-specific tools and compose features require adaptation
• Docker Compose differences: Podman Compose exists but has occasional compatibility gaps
• Documentation: Most container documentation assumes Docker; developers need to translate
• Networking: Podman networking (CNI/netavark) differs from Docker's bridge networking

Mitigation

• Use podman CLI wrapper that provides Docker-compatible interface
• Document Podman-specific commands in developer guide
• Use archy-net custom network for inter-container DNS