RFC: Add support for Podman as container engine alternative to Docker

[tmshlvck]

Description

There were multiple requests for podman support:

• https://github.com/armbian/build/issues/7940
• https://github.com/armbian/build/issues/4328

Since rootless podman support is probably intractable at this point I am suggesting the basic support in rootful mode.

This RFC implements Podman support for Armbian builds to address mounting issues experienced with Podman while maintaining Docker compatibility.

Key changes:

• Auto-detect container engine: prefers Docker, falls back to Podman
• Use sudo with Podman (runs in root mode - not more secure than Docker)
• Add required mount options (suid,dev) and --network host for Podman
• Update all docker commands to use dynamic DOCKER_COMMAND variable

Technical notes:

• Podman runs with sudo/root privileges, so security model matches Docker
• Requires sudo access when using Podman (security consideration)
• Solves Podman-specific mount permission and networking issues
• Maintains full backward compatibility with existing Docker workflows
• May need documentation updates

Documentation summary for feature / change

I believe that if this gets merged we could mention podman support as a note to the docker requirements.

How Has This Been Tested?

• [x] I tested multiple board image builds: bananapif3, rpi4b, orangepi5 - all OK

Checklist:

• [x] My code follows the style guidelines of this project
• [x] I have performed a self-review of my own code
• [x] My changes generate no new warnings

Summary by CodeRabbit

Release Notes

• New Features
  • Added support for Podman as an alternative container runtime. The system now automatically detects and configures the appropriate container engine, with Docker remaining the default option.

[github-actions[bot]]

Hey @tmshlvck! 👋

Thanks for submitting your first pull request to the Armbian project — we're excited to have you contributing! 🧡
Your effort doesn’t just improve Armbian — it benefits the entire community of users and developers.

If you'd like to stay informed about project updates or collaborate more closely with the team,
you can optionally share some personal contact preferences at armbian.com/update-data.
This helps us keep in touch without relying solely on GitHub notifications.

Also, don’t forget to ⭐ star the repo if you haven’t already — and welcome aboard! 🚀

[EvilOlaf]

@coderabbitai review

[coderabbitai[bot]]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai[bot]]

Walkthrough

Adds runtime detection and abstraction for the container engine in lib/functions/host/docker.sh. Introduces three globals—DOCKER_COMMAND, DOCKER_NETWORK, and DOCKER_MOUNT_OPTS—initialized during a one-time info check to select between Docker and Podman (via sudo). Replaces direct docker calls with the dynamic command across info, image pull/list, volume/purge, build, launch, and preparation flows. Updates readiness checks and messages to accept either engine. Mount preparation now appends engine-specific options, and host networking is applied when Podman is used. New globals are exposed as readonly.

Changes

Cohort / File(s)	Change summary
Host container runtime abstraction lib/functions/host/docker.sh	Added runtime detection (Docker vs Podman) and three readonly globals: DOCKER_COMMAND, DOCKER_NETWORK, DOCKER_MOUNT_OPTS. Replaced direct docker invocations with $DOCKER_COMMAND across info, image operations, purge, build, launch, losetup/run, shell fallbacks. Appended mount options for Podman compatibility and adjusted readiness/error messages.

Sequence Diagram(s)

sequenceDiagram
    participant Init as Init script
    participant Detect as runtime detector
    participant Engine as Container engine (docker/podman)
    participant Runner as Container runner actions

    Init->>Detect: call detect_docker_info()
    Detect-->>Init: set DOCKER_COMMAND, DOCKER_NETWORK, DOCKER_MOUNT_OPTS (readonly)
    alt Docker selected
        Init->>Engine: run `docker info` via $DOCKER_COMMAND
    else Podman selected
        Init->>Engine: run `sudo podman info` via $DOCKER_COMMAND
    end

    Note over Init,Runner: Subsequent operations use $DOCKER_COMMAND and DOCKER_* settings
    Init->>Runner: image pull/list, build, launch, purge, mount with DOCKER_MOUNT_OPTS
    Runner->>Engine: execute container operations using $DOCKER_COMMAND and DOCKER_NETWORK
    Engine-->>Runner: return status/results

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Potential review focal points:

• Correctness of all substitutions from docker to $DOCKER_COMMAND in command contexts and quoting.
• Proper readonly initialization and fallback behavior when both engines are absent.
• Mount option concatenation and compatibility with Podman bind/volume syntax.
• Network flag application for Podman launches and any sudo implications.

Suggested reviewers

• chraac
• igorpecovnik
• EvilOlaf
• AGM1968
• rpardini

Poem

I’m a rabbit in the shell, I hop and I probe,
Found Docker or Podman to run every globe.
DOCKER_COMMAND set, mounts snug and tight,
Networks chosen true, containers take flight.
Hooray for small changes that make launches just right! 🐇✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding Podman support as a Docker alternative, which aligns with the core objective of the PR.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 23e72dc2d64d7176535fd2b6c509883c2fdfdd7d and 6b2a5f73ff4f5053cdeecc5b62465042b395027e.

📒 Files selected for processing (1)

• lib/functions/host/docker.sh (9 hunks)

🧰 Additional context used

🧠 Learnings (4)

📓 Common learnings

Learnt from: tmshlvck
Repo: armbian/build PR: 8660
File: lib/functions/host/docker.sh:519-529
Timestamp: 2025-09-22T06:01:50.284Z
Learning: In the Armbian build framework's docker.sh, DOCKER_MOUNT_OPTS is conditionally set: empty for Docker, and ",suid,dev" for Podman to handle mount permission requirements.

Learnt from: tmshlvck
Repo: armbian/build PR: 8660
File: lib/functions/host/docker.sh:519-529
Timestamp: 2025-09-22T06:01:50.284Z
Learning: In the Armbian build framework's docker.sh, DOCKER_MOUNT_OPTS is conditionally set: empty for Docker, and ",suid,dev" for Podman to handle mount permission requirements.

📚 Learning: 2025-09-22T06:01:50.284Z

Learnt from: tmshlvck
Repo: armbian/build PR: 8660
File: lib/functions/host/docker.sh:519-529
Timestamp: 2025-09-22T06:01:50.284Z
Learning: In the Armbian build framework's docker.sh, DOCKER_MOUNT_OPTS is conditionally set: empty for Docker, and ",suid,dev" for Podman to handle mount permission requirements.

Applied to files:

• lib/functions/host/docker.sh

📚 Learning: 2025-10-24T04:46:22.901Z

Learnt from: tabrisnet
Repo: armbian/build PR: 0
File: :0-0
Timestamp: 2025-10-24T04:46:22.901Z
Learning: In lib/functions/rootfs/rootfs-create.sh, the FIXME comment about mmdebstrap usage with --aptopt is a future note related to PR #8785, which hasn't been merged yet.

Applied to files:

• lib/functions/host/docker.sh

📚 Learning: 2025-09-24T09:54:07.968Z

Learnt from: amazingfate
Repo: armbian/build PR: 8668
File: extensions/ufs.sh:2-2
Timestamp: 2025-09-24T09:54:07.968Z
Learning: In Armbian's build system, DOCKER_ARMBIAN_BASE_IMAGE must be set globally at file load time in extensions, not inside extension_prepare_config functions, because docker operations happen early in the build process and would default to ubuntu:noble if not set before docker_cli_prepare() runs.

Applied to files:

• lib/functions/host/docker.sh

🧬 Code graph analysis (1)

lib/functions/host/docker.sh (2)

lib/functions/logging/runners.sh (1)

• run_host_command_logged (204-206)

lib/functions/cli/cli-docker.sh (2)

• cli_docker_run (32-112)
• cli_docker_pre_run (10-30)

🔇 Additional comments (6)

lib/functions/host/docker.sh (6)

45-73: ✓ Container engine detection and globals initialization look solid.

The detection logic correctly prefers Docker (if available) and falls back to Podman with sudo. Making the globals readonly after initialization prevents accidental mutations downstream. Good defensive design.

---

89-103: ✓ is_docker_ready_to_go updated appropriately.

Guard clause now checks for either docker or podman, and error messaging reflects both runtimes. Clean update.

---

113-126: ✓ Previous quoting issue resolved.

The unquoted $DOCKER_COMMAND in set statements (lines 117, 125) and pipe expressions (lines 113-114) correctly allows word splitting for "sudo podman". The previous review comment flagged a quoted form; this version correctly uses unquoting.

---

339-376: ✓ Image operations use dynamic $DOCKER_COMMAND correctly.

Unquoted invocations at lines 339, 352, 355, and 376 properly allow word splitting for "sudo podman". Consistent and correct throughout this segment.

---

601-607: ✓ losetup and launch invocations correctly use dynamic command and network variables.

Unquoted expansion of $DOCKER_COMMAND and $DOCKER_NETWORK is appropriate here. Both expand correctly:

• $DOCKER_COMMAND splits "sudo podman" into separate tokens.
• $DOCKER_NETWORK expands to empty (Docker) or "--network host" (Podman), correctly passed as separate arguments.

---

639-640: ✓ Volume purge operations use dynamic command correctly.

Unquoted $DOCKER_COMMAND properly allows "sudo podman" word splitting.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}