Podman Compose

An implementation of Compose Spec with Podman backend. This project focuses on:

• rootless
• daemon-less process model, we directly execute podman, no running daemon.

This project only depends on:

• podman
• a podman network backend with DNS name resolution available. This allows containers to be able to resolve each other if they are on the same network.
  • either: podman dnsname plugin with CNI network backend: It is usually found in the podman-plugins or podman-dnsname distro packages, those packages are not pulled by default and you need to install them.
  • or: netavark/aardvark-dns: Both are usually installed on new installations of podman 4.
• Python 3.9 or newer
• PyYAML
• python-dotenv

And it's formed as a single Python file script that you can drop into your PATH and run.

References:

• spec.md
• docker-compose compose-file-v3
• docker-compose compose-file-v2

Alternatives

As in this article you can setup a podman.socket and use unmodified docker-compose that talks to that socket but in this case you lose the process-model (ex. docker-compose build will send a possibly large context tarball to the daemon)

For production-like single-machine containerized environment consider

• k3s | k3s github
• MiniKube

For the real thing (multi-node clusters) check any production OpenShift/Kubernetes distribution like OKD.

Versions

If you have legacy version of podman (before 3.1.0) you might need to stick with legacy podman-compose 0.1.x branch. The legacy branch 0.1.x uses mappings and workarounds to compensate for rootless limitations.

Modern podman versions (>=3.4) do not have those limitations, and thus you can use latest and stable 1.x branch.

If you are upgrading from podman-compose version 0.1.x then we no longer have global option -t to set mapping type like hostnet. If you desire that behavior, pass it the standard way like network_mode: host in the YAML.

Installation

Pip

Install the latest stable version from PyPI:

pip3 install podman-compose

pass --user to install inside a regular user's home without being root.

Or latest development version from GitHub:

pip3 install https://github.com/containers/podman-compose/archive/main.tar.gz

Package repositories

podman-compose is available from the following package repositories:

Debian:

sudo apt install podman-compose

Fedora (starting from f31) repositories:

sudo dnf install podman-compose

Homebrew:

brew install podman-compose

Generate binary using docker/podman locally

This script will download the repo, generate the binary using this Dockerfile, and place the binary in the directory where you called this script.

sh -c "$(curl -sSL https://raw.githubusercontent.com/containers/podman-compose/main/scripts/download_and_build_podman-compose.sh)"

Manual

curl -o /usr/local/bin/podman-compose https://raw.githubusercontent.com/containers/podman-compose/main/podman_compose.py
chmod +x /usr/local/bin/podman-compose

or inside your home

curl -o ~/.local/bin/podman-compose https://raw.githubusercontent.com/containers/podman-compose/main/podman_compose.py
chmod +x ~/.local/bin/podman-compose

Tests

podman-compose is tested via unit and integration tests.

Unit tests can be run via the following:

python3 -m unittest discover tests/unit

Integration tests can be run via the following:

python3 -m unittest discover tests/integration

Contributing guide

If you are a user or a developer and want to contribute please check the CONTRIBUTING section