Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Compose and Quadlet

Running Compose Files with Podman

Run multi-container apps from a compose.yaml with Podman: podman compose, podman-compose, the Docker-compatible socket, rootless caveats, and how compose maps to podman run.

Real applications are rarely one container. A web app needs a database, maybe a cache and a worker. A Compose file (compose.yaml) describes all of them in one place: images, ports, volumes, networks, environment variables and start order. Podman can run these files, so the huge number of existing Compose projects work without Docker.

This lesson shows the three ways to run Compose files with Podman, how a Compose file translates into Podman objects, and where the differences bite. Compose itself needs a real Podman, so the commands are read-only; the runnable stand-ins convert Compose-style data into podman run commands and compute start order.

Three ways to run a Compose file

1. podman compose is a thin wrapper. It does not implement Compose; it finds a compose provider on your machine (either docker-compose or podman-compose) and runs it with Podman configured as the backend.

Terminal
podman compose up -d
podman compose ps
podman compose logs -f
podman compose down

2. podman-compose is a separate Python program that reads Compose files and issues Podman commands directly. It does not need a socket.

Terminal
pip install --user podman-compose
podman-compose up -d

3. The Docker docker-compose tool talking to Podman's API socket. Podman can serve a Docker-compatible API:

Terminal
systemctl --user enable --now podman.socket
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
docker-compose up -d

Which one should you use? If you want the full Compose specification behavior, use docker-compose (the real Compose) through the socket, or let podman compose pick it. If you want zero extra daemons and are happy with the commonly used features, podman-compose is simple. The newer podman kube play and Quadlet (next lessons) are the "Podman-native" alternatives.

A small Compose file

YAML
services:
  db:
    image: docker.io/library/postgres:17
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - dbdata:/var/lib/postgresql/data
  web:
    image: docker.io/library/nginx:stable
    ports:
      - "8080:80"
    depends_on:
      - db
volumes:
  dbdata:

Run it with podman compose up -d and Compose creates:

  • a network named <project>_default with DNS, so web can reach db by name,
  • a volume named <project>_dbdata,
  • containers named <project>_db_1 and <project>_web_1 (the exact naming depends on the provider).

The project name defaults to the folder name; override it with -p myapp or the top-level name: key.

Always write fully qualified image names (docker.io/library/nginx) in Compose files you share. Short names depend on each machine's registry settings; see Registries and Authentication.

How Compose keys map to Podman

Understanding the mapping lets you translate a Compose file by hand, which is a good way to debug what a provider did.

Compose key Podman equivalent
image the image argument of podman run
ports: ["8080:80"] -p 8080:80
environment -e KEY=value
volumes: ["dbdata:/data"] -v dbdata:/data
networks --network NAME
restart: always --restart always
command the command after the image
user --user
depends_on start ordering only (no podman run flag)

Translating a service

Python Compose service to podman run (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Start order with depends_on

depends_on controls the order in which containers are started. By itself it does not wait until a database accepts connections, only until its container has started. With a health check you can wait for readiness:

YAML
services:
  db:
    image: docker.io/library/postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
  web:
    image: docker.io/library/nginx:stable
    depends_on:
      db:
        condition: service_healthy

How well condition: service_healthy works depends on the provider; with docker-compose it is reliable. Otherwise make the application retry its connection.

The ordering itself is a topological sort of the dependency graph:

Python Start order from depends_on (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Differences you will meet

  • Rootless ports: ports: ["80:80"] fails for a rootless user. See Publishing Ports and Name Resolution.
  • Volumes and SELinux: on Fedora/RHEL, bind mounts usually need :z or :Z (for example ./data:/data:Z) so the container is allowed to read them.
  • Build sections: build: uses Buildah under the hood; see Building Images with a Containerfile.
  • Provider differences: podman-compose supports most common keys, but advanced features (profiles, extends, some deploy: options) may be missing or behave differently. Read the provider's notes.
  • Socket path: root uses /run/podman/podman.sock; rootless uses $XDG_RUNTIME_DIR/podman/podman.sock.

When to leave Compose behind

Compose is great for development. For servers that should start at boot and be supervised by systemd, Podman's own approach is better: Quadlet unit files describe containers as systemd services, with no extra tool to install.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does podman compose do itself?

    podman compose is a wrapper that locates docker-compose or podman-compose and runs it against Podman.
  2. 2. Which setting lets the real docker-compose talk to Podman?

    Podman provides a Docker-compatible API on its socket; DOCKER_HOST points docker-compose at it.
  3. 3. What does a plain depends_on guarantee?

    Plain depends_on orders container starts; readiness needs a health check and a service_healthy condition or application retries.
  4. 4. Why use fully qualified image names in a shared Compose file?

    docker.io/library/nginx is unambiguous; nginx might resolve differently or prompt on another machine.

Summary

  • Run Compose files with podman compose (wrapper), podman-compose (Python tool) or docker-compose via the Podman socket.
  • A project gets its own network with DNS, named volumes and prefixed container names.
  • Compose keys map directly to podman run flags; depends_on only orders starts unless health conditions are used.
  • Rootless ports, SELinux labels and provider gaps are the usual surprises.
  • For long-running services, Quadlet integrates better with systemd.

Next: Quadlet: Containers as systemd Units