Podman Compose - Managing Containers

Introduction

Podman is a daemonless engine for OCI container management. It aims to provide a one-to-one replacement for all Docker functionalities by directly implementing relevant container management features or using other utilities such as Buildah and Skopeo.

In this article, you will learn about Podman Compose, a tool for running multi-container apps similar to Docker Compose.

Prerequisites

• Podman installed on Linux/macOS/Windows with WSL2.
• Python3 and pip installed.
• Administrative system access.

What is Podman Compose?

Podman Compose is a Docker Compose implementation for Podman. It is a tool that facilitates the deployment of interdependent containers by grouping all the necessary instructions in a single YAML file. Podman Compose is designed to offer full compatibility with Docker Compose YAML files, with added functionalities that handle Podman's rootless and daemonless nature.

How to Install Podman Compose

Install Podman Compose using the pip package manager or a Python script. Fedora repositories contain the podman-compose package as of version 31, so it is possible to install this tool on Fedora using the DNF package manager. All three methods are described in the sections below.

Install Podman Compose with pip

To install Podman Compose with pip, first update pip packages to the latest version:

sudo -H pip3 install --upgrade pip

Install the latest stable version of Podman Compose:

pip3 install podman-compose

The command installs Podman Compose for all users.

To install for the current user only, add the --user flag:

pip3 install podman-compose --user

The latest development version of Podman Compose is available on GitHub. Install it with the following command:

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

The output confirms the installation's success.

Execute the above-mentioned command without sudo if you wish to limit the installation of the Podman Compose development version to the current user only.

Install Podman Compose with Python Script

Install the latest Podman Compose development version by downloading the precompiled Python script. The script is available on the project's GitHub page:

sudo curl -o /usr/local/bin/podman-compose https://raw.githubusercontent.com/containers/podman-compose/devel/podman_compose.py

The curl command downloads the file and places it in the /usr/local/bin directory.

Make the file executable by typing:

chmod +x /usr/local/bin/podman-compose

If you prefer to install Podman Compose inside your user home directory, use the same curl syntax, but change the install location:

curl -o ~/.local/bin/podman-compose https://raw.githubusercontent.com/containers/podman-compose/devel/podman_compose.py

When the download completes, assign executable permissions to the file:

chmod +x ~/.local/bin/podman-compose

Install Podman Compose on Fedora 31 and Newer

If you use Fedora 31 or a newer version of this OS, install Podman Compose directly from Fedora repositories. Use the DNF package manager:

sudo dnf install podman-compose

How to Use Podman Compose?

Using Podman Compose to deploy an app features a process similar to deploying with Docker Compose. The process involves creating a compose.yml file with instructions for Podman on how to execute the app deployment.

Below is an example of using Podman Compose to deploy a Plex media server instance.

1. Create a directory for the compose.yml file and go to that directory.

mkdir plex-test && cd plex-test

2. Use a text editor to create compose.yml.

nano compose.yml

3. Define the deployment in the file. The example below provides the necessary configuration for a Plex server:

services:
  plex:
    image: docker.io/linuxserver/plex
    container_name: plex
    network_mode: host
    environment:
      - VERSION=podman
    restart: always
    volumes:
      - ${PLEX_MEDIA_PATH}:/media/

The services.plex.image field contains a link to the Plex image on Docker Hub. The file also defines the container name and environment variables and creates volumes for persistent data storage.

Save and exit the file when you finish editing it.

4. Issue the following command in the directory containing the compose.yml file:

podman-compose up

When the user issues the podman-compose up command, Podman Compose performs a series of tasks:

• Creates a pod with the name corresponding to the name of the current directory.
• Checks if the volumes specified in compose.yml exist and creates the missing volumes.
• Creates a container for each service defined in compose.yml.
• Adds the containers to the pod.

When the process completes, Plex displays a message containing the address for accessing the web UI.

Keep Plex running in the terminal window.

In another terminal window, check the deployment by listing the pods running on the system:

podman pod ls

The list shows the pod plex-test pod. Inside the pod is a single container running the Plex service:

Use a browser to visit the address from the Plex start-up message:

http://localhost:32400/web

The browser redirects you to the Plex sign-in page.

Check Running Containers

Type the command below to get a list of containers created by Podman Compose:

podman ps

The output shows a running container named plex. The name is defined in compose.yml.

Stop Containers

The standard method for stopping containers in Podman involves the podman stop command:

podman stop [container-id]

However, sometimes the number of Podman Compose containers is too large to stop manually. The following command stops all the containers associated with the specific Podman Compose deployment:

podman-compose down

The output shows that Podman Compose stops and removes the deployed containers. The pod containing those containers is also removed.

Stop and Remove Pods

You can also manually stop and remove pods created by Podman Compose. To stop a pod, type:

podman pod stop [pod-name-or-id]

The output confirms the pod's deletion by showing the entire pod ID.

The Plex server stops and exits to the command prompt.

Remove the stopped pods with the following podman pod command:

podman pod rm [pod-name-or-id]

Conclusion

This tutorial showed you how to use Podman Compose to deploy an app on your system.

The article included multiple methods for Podman Compose installation, alongside the instructions for container management.