Note:
- This tutorial is available in an Oracle-provided free lab environment.
- It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.
Use Compose Files with Podman on Oracle Linux
Introduction
Podman and Docker Compose are both command-line tools that use a specially formatted YAML file as input to assemble and then run single or multiple containers as applications. These tools allow 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 have made using the Compose specification hugely popular with users and developers, and it is increasingly becoming a requirement.
Objectives
In this tutorial, you’ll learn to:
- Install and use both
podman-compose
anddocker-compose
with Podman - Verify they work with a simple
docker-compose.yaml
file
Prerequisites
-
Minimum of a single Oracle Linux system
-
Each system should have Oracle Linux installed and configured with:
- A non-root user account with sudo access
- Podman and cURL packages
- Access to the Internet
Deploy Oracle Linux
Note: If running in your own tenancy, read the linux-virt-labs
GitHub project README.md and complete the prerequisites before deploying the lab environment.
-
Open a terminal on the Luna Desktop.
-
Clone the
linux-virt-labs
GitHub project.git clone https://github.com/oracle-devrel/linux-virt-labs.git
-
Change into the working directory.
cd linux-virt-labs/ol
-
Install the required collections.
ansible-galaxy collection install -r requirements.yml
-
Deploy the lab environment.
ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e use_podman=true -e update_all=true
The free lab environment requires the extra variable
local_python_interpreter
, which setsansible_python_interpreter
for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules.The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add
-e instance_shape="VM.Standard3.Flex"
or-e os_version="9"
to the deployment command.Important: Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Cloud Native Environment is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab.
Confirm Podman Works
The container-tools package in Oracle Linux provides the latest versions of Podman, Buildah, Skopeo, and associated dependencies.
-
Open a terminal and connect via SSH to the ol-node-01 instance.
ssh oracle@<ip_address_of_instance>
-
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.
Install the Podman Docker Package
Install the podman-docker
package, which enables Podman to work natively with Docker commands.
sudo dnf install -y podman-docker
Install Docker Compose
-
Download and install Compose standalone.
sudo curl -SL https://github.com/docker/compose/releases/download/v2.28.1/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
Example Output:
% 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 60.1M 100 60.1M 0 0 103M 0 --:--:-- --:--:-- --:--:-- 378M
-
Apply executable permissions to the binary.
sudo chmod +x /usr/local/bin/docker-compose
-
Confirm Compose standalone works.
docker-compose version
The output returns the current version of
docker-compose
.Note: Installing Compose in a standalone manner as described here requires using
docker-compose up
, for example, instead of the standarddocker-compose up
syntax used when running the Docker utility.
Start the Podman Socket
Podman and Docker Compose each require the starting of the Podman socket, which allows system calls from each program to communicate with Podman over this systemd controlled process.
-
Configure the Podman socket.
systemctl --user enable --now podman.socket systemctl --user status podman.socket
The output shows the systemd socket
active (listening)
. -
Get the location for the user’s Podman socket location.
podman info | grep -i remotesocket -A2
-
Verify that the socket works using cURL.
curl -w "\n" -H "Content-Type: application/json" --unix-socket /run/user/$UID/podman/podman.sock http://localhost/_ping
The path for the
--unix-socket
matches the path provided frompodman info
. The output of this command should returnOK
, indicating a successful configuration of the Compose functionality that is ready 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. The latest version of Podman Compose requires a minimal version of Python 3.12.
-
Install Python 3.12 and the required dependencies.
sudo dnf install -y python3.12 python3.12-pip
-
Install the Podman Compose package.
pip3.12 install podman-compose
-
Confirm Podman Compose works by displaying its version.
podman-compose version
Create a Compose File
This Compose file allows the pulling and starting of the designated application.
-
Create a directory for the test and change into that directory.
mkdir -p projects/echo cd projects/echo
-
Create the Compose file.
cat >> compose.yaml << EOF services: web: image: k8s.gcr.io/echoserver:1.4 ports: - "${HOST_PORT:-8080}:8080" EOF
-
Review the Compose file.
cat compose.yaml
Run Podman Compose
-
Change into the same directory as the Compose file.
Important:
podman-compose
commands will not work unless you are in the same directory as thecompose.yaml
file.cd ~/projects/echo/
-
Start the
echoserver
application.podman-compose up -d
The output shows Podman pulling down the container and starting it with the parameters listed in the Compose file. The
-d
option tells Podman to run the container in the background in detached mode. Podman will only pull images referenced in the Compose file if they are not locally present. -
Test the echoserver application is up and running.
curl -X POST -d "foobar" http://localhost:8080/; echo
Example Output:
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:
['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:
['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
You can see other Podman Compose utility commands by running
podman-compose --help
. -
Now, it is time to stop the echoserver container.
podman-compose down
-
Remove the additional Podman bridge network created during the container deployment.
podman network rm echo_default
Confirm Docker Compose is Working
-
Set environment variable for the location of the Podman socket.
export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock
-
Start the echoserver application.
This command must run from within the same directory as the Compose file.
docker-compose up -d
The output shows the creation of the echo_default network and the echo-web-1 container.
-
Access the container’s application.
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
-
Inspect the logs and confirm that this application successfully submitted a return request.
docker-compose logs
Example Output:
echo-web-1 | 10.89.0.1 - - [17/Jan/2023:14:48:56 +0000] "POST / HTTP/1.1" 200 446 "-" "curl/7.61.1"
-
Get a listing of containers started using the Docker Compose utility.
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
-
Stop the echoserver application.
docker-compose down
Important Information
If you install both the podman-compose
and docker-compose
executables on the same system, it is essential to note that it is not possible to invoke them interchangeably. What we mean by this statement is that if you start a process using podman-compose
, you cannot query it or stop it by using docker-compose
or vice versa.
-
Start by using Podman Compose.
podman-compose up -d
-
Try to list the running containers using Docker Compose.
docker-compose ps
The output returns an empty list showing that, from its perspective, no containers are running.
-
However, using Podman Compose confirms the container is running.
podman-compose ps
Example Output:
['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
More Learning Resources
Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.
For product documentation, visit Oracle Help Center.
Use Compose Files with Podman on Oracle Linux
F76747-04
July 2024