Using Compose Files with Podman
Introduction
Docker Compose is a command-line tool that uses a specially formatted YAML file as input to assemble and then run single, or multiple, containers as applications. This allows developers to develop, test and then deliver to their users a single YAML file for their application, and use only one command to start, and stop, it reliably. This portability and reliability has made Docker Compose not only hugely popular with both users and developers, but increasingly a requirement.
Objectives
This lab shows how to install and use both podman-compose
and docker-compose
with Podman, and verify they work with a simple docker-compose.yaml
file.
Prerequisites
- A client system with Oracle Linux installed
- Podman installed (the 'container-tools' package)
- Access to the Internet
Oracle Support Disclaimer
Oracle does not provide technical support for the sequence of steps that are provided in the following instructions because these steps refer to software programs and operating systems that are not provided by Oracle. This tutorial provides optional instructions as a convenience only.
For more information about Oracle's supported method for the development and usage of Podman-based services see https://docs.oracle.com/en/operating-systems/oracle-linux/podman/ .
Setup the Lab Environment
Note: When using the free lab environment, see Oracle Linux Lab Basics for connection and other usage instructions.
Open a terminal and connect via ssh to the ol-server instance if not already connected.
ssh oracle@<ip_address_of_instance>
Confirm Podman Works
The container-tools package in Oracle Linux provides the latest versions of Podman, Buildah, Skopeo, and associated dependencies.
Check the version of Podman.
podman -v
Confirm the Podman CLI is working.
podman run quay.io/podman/hello
Example Output:
[oracle@ol-server ~]$ podman run quay.io/podman/hello Trying to pull quay.io/podman/hello:latest... Getting image source signatures Copying blob f82b04e85914 done Copying config dbd85e09a1 done Writing manifest to image destination Storing signatures !... Hello Podman World ...! .--"--. / - - \ / (O) (O) \ ~~~| -=(,Y,)=- | .---. /` \ |~~ ~/ o o \~~~~.----. ~~ | =(X)= |~ / (O (O) \ ~~~~~~~ ~| =(Y_)=- | ~~~~ ~~~| U |~~ Project: https://github.com/containers/podman Website: https://podman.io Documents: https://docs.podman.io Twitter: @Podman_io
Setup Podman to Work with Compose Files
Podman introduced support for Docker Compose functionality in Podman v3.2.0 , after limited support was introduced in Podman v3.0.0 , thereby introducing the ability to use Docker Compose from within Podman. More recently Podman v4.1.0 extended the support of Docker Compose functionality to include using Docker Compose v2.2 and higher.
The following steps describe how to install, and configure, both of podman-compose
and docker-compose
.
Install the Podman Docker Package
This enables Podman to work natively with Docker commands.
Install the
podman-docker
package.sudo dnf install -y podman-docker
Install Docker Compose
Note:
Installing Compose in a standalone manner as described here requires using
docker-compose
instead of the standard syntax used when using the Docker utility ofdocker compose
. In other words substitute thedocker compose up
syntax withdocker-compose up
instead.
Download and install Compose standalone.
sudo curl -SL https://github.com/docker/compose/releases/download/v2.15.1/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
Example Output:
[oracle@ol-server ~]$ sudo curl -SL https://github.com/docker/compose/releases/download/v2.15.1/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 100 42.8M 100 42.8M 0 0 158M 0 --:--:-- --:--:-- --:--:-- 158M
Apply executable permissions to the binary.
sudo chmod +x /usr/local/bin/docker-compose
Confirm Compose standalone works.
docker-compose version
Example Output:
[oracle@ol-server ~]$ docker-compose version Docker Compose version v2.15.1
Start the Podman Socket
The following steps are required to make Docker Compose functionality work by creating a Unix socket.
Configure the Podman socket with these steps.
sudo systemctl enable --now podman.socket sudo systemctl status podman.socket
Example Output:
[oracle@ol-server ~]$ sudo systemctl enable --now podman.socket Created symlink /etc/systemd/system/sockets.target.wants/podman.socket -> /usr/lib/systemd/system/podman.socket. [oracle@ol-server ~]$ sudo systemctl status podman.socket * podman.socket - Podman API Socket Loaded: loaded (/usr/lib/systemd/system/podman.socket; enabled; vendor preset) Active: active (listening) since Thu 2023-01-19 20:58:20 GMT; 16s ago Docs: man:podman-system-service(1) Listen: /run/podman/podman.sock (Stream) CGroup: /system.slice/podman.socket Jan 19 20:58:20 ol-server systemd[1]: Listening on Podman API Socket.
Verify that the socket works as expected using curl.
sudo curl -w "\n" -H "Content-Type: application/json" --unix-socket /var/run/docker.sock http://localhost/_ping
Example Output:
[oracle@ol-server ~]$ sudo curl -w "\n" -H "Content-Type: application/json" --unix-socket /var/run/docker.sock http://localhost/_ping OK [oracle@ol-server ~]$
If the output of this command returns OK
, then Compose functionality is successfully configured to work with docker-compose.yaml files.
Install Podman Compose
Podman Compose is a Python 3 library that implements the Compose Specification to run with Podman.
Before installing Podman Compose, confirm that pip is updated to the latest version.
sudo -H pip3 install --upgrade pip
Install the Podman Compose package.
sudo pip3 install podman-compose
When running the
pip3 install
assudo
, the WARNING messages can be ignored.Confirm Podman Compose works.
podman-compose version
Example Output:
[oracle@ol-server ~]$ podman-compose version ['podman', '--version', ''] using podman version: 4.2.0 podman-composer version 1.0.3 podman --version podman version 4.2.0 exit code: 0
Create a Docker Compose File
This docker-compose.yaml file allows the pulling and starting of the designated application.
Create a directory for the test.
mkdir -p Documents/examples/echo
Change into the directory.
cd Documents/examples/echo
Create the docker-compose.yaml file.
cat >> docker-compose.yaml << EOF --- version: '3' services: web: image: k8s.gcr.io/echoserver:1.4 ports: - "${HOST_PORT:-8080}:8080" EOF
Review the docker-compose.yaml just created.
cat docker-compose.yaml
Example Output:
[oracle@ol-server echo]$ cat docker-compose.yaml --- version: '3' services: web: image: k8s.gcr.io/echoserver:1.4 ports: - "8080:8080"
Confirm Podman Compose is Working
Change into the directory where the docker-compose file is located.
Important:
podman-compose
commands will not work unless you are in the directory where thedocker-compose.yaml
file is located.cd ~/Documents/examples/echo/
Start the
echoserver
application.podman-compose up -d
Example Output:
[oracle@ol-server echo]$ podman-compose up -d ['podman', '--version', ''] using podman version: 4.2.0 ** excluding: set() ['podman', 'network', 'exists', 'echo_default'] ['podman', 'network', 'create', '--label', 'io.podman.compose.project=echo', '--label', 'com.docker.compose.project=echo', 'echo_default'] ['podman', 'network', 'exists', 'echo_default'] podman create --name=echo_web_1 --label io.podman.compose.config-hash=123 --label io.podman.compose.project=echo --label io.podman.compose.version=0.0.1 --label com.docker.compose.project=echo --label com.docker.compose.project.working_dir=/home/oracle/examples/echo --label com.docker.compose.project.config_files=docker-compose.yaml --label com.docker.compose.container-number=1 --label com.docker.compose.service=web --net echo_default --network-alias web -p 8080:8080 k8s.gcr.io/echoserver:1.4 Trying to pull k8s.gcr.io/echoserver:1.4... Getting image source signatures Copying blob d3c51dabc842 done Copying blob a3ed95caeb02 done Copying blob 6d9e6e7d968b done Copying blob 412c0feed608 done Copying blob cd23f57692f8 done Copying blob dcd34d50d5ee done Copying blob a3ed95caeb02 skipped: already exists Copying blob a3ed95caeb02 skipped: already exists Copying blob a3ed95caeb02 skipped: already exists Copying blob b4241160ce0e done Copying blob 7abee76f69c0 done Writing manifest to image destination Storing signatures 1b54b75ca13786d33df6708da1d83ecce14b055e78b03007c3c4e1f441e7139c exit code: 0
Note: As with Podman, any container(s) referenced in the
docker-compose.yaml
file are only pulled if not already present on the system.Test the
echoserver
application is up and running.curl -X POST -d "foobar" http://localhost:8080/; echo
Example Output:
[oracle@ol-server echo]$ curl -X POST -d "foobar" http://localhost:8080/; echo CLIENT VALUES: client_address=10.89.0.2 command=POST real path=/ query=nil request_version=1.1 request_uri=http://localhost:8080/ SERVER VALUES: server_version=nginx: 1.10.0 - lua: 10001 HEADERS RECEIVED: accept=*/* content-length=6 content-type=application/x-www-form-urlencoded host=localhost:8080 user-agent=curl/7.61.1 BODY: foobar
Additionally confirm success by reviewing the logs.
podman-compose logs
Example Output:
[oracle@ol-server echo]$ podman-compose logs ['podman', '--version', ''] using podman version: 4.2.0 podman logs echo_web_1 10.89.0.2 - - [17/Jan/2023:12:46:47 +0000] "POST / HTTP/1.1" 200 446 "-" "curl/7.61.1" exit code: 0
Use the Podman Compose utility to see running containers.
podman-compose ps
Example Output:
[oracle@ol-server echo]$ podman-compose ps ['podman', '--version', ''] using podman version: 4.2.0 podman ps -a --filter label=io.podman.compose.project=echo CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES f4053947c8c1 k8s.gcr.io/echoserver:1.4 nginx -g daemon o... 2 minutes ago Up 2 minutes ago 0.0.0.0:8080->8080/tcp echo_web_1 exit code: 0
Note: See other Podman Compose utility commands by running
podman-compose --help
. However, these additional commands are out of scope for this Lab.Now it is time to stop the echoweb service.
podman-compose down
Confirm Docker Compose is Working
(Optional) Change into the directory where the docker-compose file is located.
Important:
docker-compose
commands will not work unless you are in the directory where thedocker-compose.yaml
file is located.cd ~/Documents/examples/echo/
Start the
echoserver
application.sudo /usr/local/bin/docker-compose up -d
Example Output:
[oracle@ol-server echo]$ sudo /usr/local/bin/docker-compose up -d [+] Running 0/0 [+] Running 0/1echo-web-1 Starting 0.0 [+] Running 0/1echo-web-1 Starting 0.1 [+] Running 0/1echo-web-1 Starting 0.2 [+] Running 0/1echo-web-1 Starting 0.3 [+] Running 0/1echo-web-1 Starting 0.4 [+] Running 0/1echo-web-1 Starting 0.5 [+] Running 0/1echo-web-1 Starting 0.6 [+] Running 0/1echo-web-1 Starting 0.7 [+] Running 1/1echo-web-1 Starting 0.8 ��� Container echo-web-1 Started 0.8s
NOTE:
If the following output is returned when executing this command:
��� Container echo-web-1 Starting 0.9s Error response from daemon: cannot listen on the TCP port: listen tcp4 :8080: bind: address already in use
Don't worry, it only means that the
podman-compose down
command wasn't executed, and the echoserver container previously started usingpodman-compose
is still running. Follow the previous steps to stop it.Test the container is running.
curl -X POST -d "foobar" http://localhost:8080/; echo
Example Output:
[oracle@ol-server ~]$ curl -X POST -d "foobar" http://localhost:8080/; echo CLIENT VALUES: client_address=10.89.0.2 command=POST real path=/ query=nil request_version=1.1 request_uri=http://localhost:8080/ SERVER VALUES: server_version=nginx: 1.10.0 - lua: 10001 HEADERS RECEIVED: accept=*/* content-length=6 content-type=application/x-www-form-urlencoded host=localhost:8080 user-agent=curl/7.61.1 BODY: foobar
As before, use the Docker Compose utility to inspect the logs and confirm a successful request was returned by this application.
sudo /usr/local/bin/docker-compose logs
Example Output:
[oracle@ol-server echo]$ sudo /usr/local/bin/docker-compose logs echo-web-1 | 10.89.0.1 - - [17/Jan/2023:14:48:56 +0000] "POST / HTTP/1.1" 200 446 "-" "curl/7.61.1"
The Docker Compose utility also provides a way to review the containers started by the Compose file.
sudo /usr/local/bin/docker-compose ps
Example Output:
echo-web-1 k8s.gcr.io/echoserver:1.4 "nginx -g daemon off;" web 12 minutes ago Up 12 minutes 8080/tcp
Note: See other Docker Compose utility commands by running
docker-compose --help
. However, these additional commands are out of scope for this Lab.Stop the echoweb service.
sudo /usr/local/bin/docker-compose down
Example Output:
[oracle@ol-server echo]$ sudo /usr/local/bin/docker-compose down [+] Running 0/0 [+] Running 0/1echo-web-1 Stopping 0.1 [+] Running 0/1echo-web-1 Stopping 0.2 [+] Running 0/1echo-web-1 Stopping 0.3 [+] Running 2/1echo-web-1 Removing 0.4 ��� Container echo-web-1 Removed 0.4s ��� Network echo_default Removed 0.0s
Important Information
If both the podman-compose
and docker-compose
executables have been installed on the same system, it is important to note that it is not possible to invoke them interchangeably. This means that if a process is started by podman-docker
it cannot be queried, or stopped by using the docker-compose
utility, or vice-versa, as shown in the example below:
Change into the directory where the Compose file is located.
Important: The
podman-compose
ordocker-compose
commands will not work unless you are in the directory where thedocker-compose.yaml
file is located.cd ~/Documents/examples/echo/
Start by using Podman Compose.
podman-compose up -d
Try to list the running containers using Docker Compose.
sudo /usr/local/bin/docker-compose ps
Example Output
[oracle@ol-server echo]$ sudo /usr/local/bin/docker-compose ps NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
However using Podman Compose confirms the container is running.
podman-compose ps
Example Output:
[oracle@ol-server echo]$ podman-compose ps ['podman', '--version', ''] using podman version: 4.2.0 podman ps -a --filter label=io.podman.compose.project=echo CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 55335e797296 k8s.gcr.io/echoserver:1.4 nginx -g daemon o... 4 minutes ago Up 4 minutes ago 0.0.0.0:8080->8080/tcp echo_web_1 exit code: 0
Summary
This confirms how to use a Compose file with Podman using either podman-compose
or docker-compose
.
For More Information
See other related resources:
- Oracle Learning Library
- Oracle Linux Documentation: