Skip to main content

Podman Setup

James Herring
Updated

Podman Setup

Podman is a free, open-source, daemonless container runtime. Unlike Docker Desktop, Podman does not require a background service to be running -- containers are launched directly as child processes. It also supports rootless mode, allowing containers to run without root or administrator privileges.

Podman is a fully supported runtime for Precision Bridge and is a good choice for organisations that cannot use Docker or prefer a daemonless, rootless approach.

When to Choose Podman

  • No licensing restrictions -- free for all users, including commercial use, regardless of company size
  • Daemonless -- no background dockerd service consuming resources when idle
  • Rootless -- can run containers without root/administrator privileges, which satisfies stricter security policies
  • OCI-compatible -- runs the same container images as Docker, including all Precision Bridge images
  • No socket conflict -- can be installed alongside Docker Desktop or Rancher Desktop without conflict

System Prerequisites

Windows

  • Windows 10 version 1903 or later, or Windows 11
  • WSL 2 (Windows Subsystem for Linux 2) must be enabled. If it is not already installed, open PowerShell as Administrator and run wsl --install, then restart your computer.

macOS

  • macOS 12 (Monterey) or later
  • Supported on both Apple Silicon (M1, M2, M3, M4) and Intel Macs

Linux

  • Most modern distributions are supported (Ubuntu 20.04+, Fedora 34+, RHEL 8+, Debian 11+)
  • No additional prerequisites -- Podman uses the native Linux kernel

Download

Download Podman from the official website:

Download Podman Desktop

Podman Desktop provides a graphical interface similar to Docker Desktop. Alternatively, you can install the Podman CLI directly without the desktop application (see platform-specific instructions below).

Installation -- Windows

  1. Download the Windows installer from podman-desktop.io
  2. Run the installer and follow the on-screen prompts
  3. Podman Desktop will guide you through initialising your first Podman machine

Option B: CLI Only

  1. Download the Podman Windows installer from the Podman releases page
  2. Run the .exe installer
  3. After installation, open a new terminal and initialise the Podman machine:
podman machine init
podman machine start

Installation -- macOS

  1. Download the macOS installer from podman-desktop.io
  2. Open the .dmg file and drag Podman Desktop to your Applications folder
  3. Open Podman Desktop -- it will guide you through initialising your first Podman machine

Option B: CLI via Homebrew

brew install podman
podman machine init
podman machine start

Installation -- Linux

On Linux, Podman runs natively without a virtual machine.

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y podman

Fedora / RHEL

sudo dnf install -y podman

Other Distributions

See the official Podman installation guide for your distribution.

Installing Podman Compose

Precision Bridge uses Docker Compose files to orchestrate its containers. To use these with Podman, you need a Compose-compatible tool. There are two options:

podman-compose is a standalone Python script that reads Docker Compose files and translates them to Podman commands.

# Install via pip (works on all platforms)
pip install podman-compose

# Verify installation
podman-compose --version

Option B: Podman Compose Plugin

Newer versions of Podman include a built-in podman compose subcommand that delegates to an external compose provider (usually Docker Compose or podman-compose).

# Check if the plugin is available
podman compose version

If this command returns a version number, the plugin is already available. If not, install podman-compose using Option A above.

Verifying the Installation

Open a terminal and run:

podman --version

You should see output similar to:

podman version 5.x.x

Also verify that Compose is available:

podman-compose --version
# or
podman compose version

You should see a version number in the output.

Finally, verify that Podman can run containers:

podman run --rm hello-world

This should download a small test image and print a confirmation message.

Running Precision Bridge with Podman

Precision Bridge's Docker Compose files work with Podman with minimal changes. Use podman-compose (or podman compose) wherever the documentation refers to docker compose:

# Start Precision Bridge
podman-compose up -d

# View logs
podman-compose logs -f

# Stop Precision Bridge
podman-compose down

Loading Offline Images

If you are installing Precision Bridge from offline tarballs (air-gapped installation), use podman load instead of docker load:

for img in pb-app pb-license pb-prefect pb-postgres pb-redis; do
  podman load -i ${img}-${VERSION}.tar.gz
done

podman-compose up -d

host.docker.internal Compatibility

Some versions of Podman do not automatically add a host.docker.internal entry that allows containers to communicate with services running on the host machine.

No manual action is needed. Precision Bridge automatically detects when it is running under Podman and applies the necessary corrections at startup. This is handled transparently -- you do not need to configure anything.

If automatic detection does not work in your environment, you can set the PB_HOST_GATEWAY environment variable to your host machine's IP address:

export PB_HOST_GATEWAY=10.88.0.1  # typical Podman bridge gateway
podman-compose up -d

Troubleshooting

"podman-compose: command not found"

Symptom: Running podman-compose returns "command not found."

Solution: Install podman-compose via pip:

pip install podman-compose

If you installed it but the command is still not found, ensure that your Python scripts directory is in your system PATH.

Podman Machine Not Running (Windows / macOS)

Symptom: podman commands return errors about connecting to the Podman machine, or "Cannot connect to Podman."

Solution: 1. Check the machine status: podman machine list 2. If no machine exists: podman machine init && podman machine start 3. If a machine exists but is stopped: podman machine start 4. If using Podman Desktop, ensure the machine is shown as "Running" in the dashboard

Permission Denied Errors (Linux)

Symptom: Podman commands fail with permission errors when running rootless.

Solution: - Ensure your user has entries in /etc/subuid and /etc/subgid: bash grep $USER /etc/subuid /etc/subgid - If entries are missing, add them: bash sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER podman system migrate

Volume Mount Issues

Symptom: Containers cannot access data in volumes, or volume data is not persisted.

Solution: - When running rootless, ensure the volume path is accessible by your user - For named volumes (used by Precision Bridge), Podman manages storage automatically -- no action is needed - If upgrading from an older Podman version, run podman system migrate to update storage

Networking Issues

Symptom: Containers cannot reach external services or each other.

Solution: - On Windows/macOS, ensure the Podman machine is running: podman machine list - Try restarting the Podman machine: podman machine stop && podman machine start - On Linux, check that the Podman network bridge is functioning: podman network ls - If using a corporate VPN, you may need to restart the Podman machine after connecting to the VPN

Next Steps

Podman is installed and running. Proceed to Download and Install to install Precision Bridge.

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk