Use Compose Files with Podman on Oracle Linux

2
0
Send lab feedback

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 and docker-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.

  1. Open a terminal on the Luna Desktop.

  2. Clone the linux-virt-labs GitHub project.

    git clone https://github.com/oracle-devrel/linux-virt-labs.git

  3. Change into the working directory.

    cd linux-virt-labs/ol

  4. Install the required collections.

    ansible-galaxy collection install -r requirements.yml

  5. 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 sets ansible_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 Linux 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.

  1. Open a terminal and connect via SSH to the ol-node-01 instance.

    ssh oracle@<ip_address_of_instance>

  2. Check the version of Podman.

    podman -v

  3. 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

  1. 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

  2. Apply executable permissions to the binary.

    sudo chmod +x /usr/local/bin/docker-compose

  3. 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 standard docker-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.

  1. Configure the Podman socket.

    systemctl --user enable --now podman.socket
systemctl --user status podman.socket

    The output shows the systemd socket active (listening).

  2. Get the location for the user's Podman socket location.

    podman info | grep -i remotesocket -A2

  3. 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 from podman info. The output of this command should return OK, 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.

  1. Install and enable the developer_EPEL repository.

    Oracle Linux 8:

    sudo dnf install -y oracle-epel-release-el8
sudo dnf config-manager --enable ol8_developer_EPEL

    Oracle Linux 9:

    sudo dnf install -y oracle-epel-release-el9
sudo dnf config-manager --enable ol9_developer_EPEL

  2. Install the Podman Compose package.

    sudo dnf install -y podman-compose

  3. 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.

  1. Create a directory for the test and change into that directory.

    mkdir -p projects/echo
cd projects/echo

  2. Create the Compose file.

    cat >> compose.yaml << EOF
services:
  web:
    image: k8s.gcr.io/echoserver:1.4
    ports:
      - "${HOST_PORT:-8080}:8080"
EOF

  3. Review the Compose file.

    cat compose.yaml

Run Podman Compose

  1. Change into the same directory as the Compose file.

    Important: podman-compose commands will not work unless you are in the same directory as the compose.yaml file.

    cd ~/projects/echo/

  2. 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.

  3. 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

  4. 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

  5. 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.

  6. Now, it is time to stop the echoserver container.

    podman-compose down

  7. Remove the additional Podman bridge network created during the container deployment.

    podman network rm echo_default

Confirm Docker Compose is Working

  1. Set environment variable for the location of the Podman socket.

    export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock

  2. 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.

  3. 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

  4. 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"

  5. 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

  6. 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.

  1. Start by using Podman Compose.

    podman-compose up -d

  2. 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.

  3. 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

Next Steps

This confirms how to use a Compose file with Podman using either podman-compose or docker-compose.

2024-12-26T21:31:34.984Z