Usability of Docker Compose with Podman for remote deployments

[shantanoo-desai]

Aim

I have been poking around to see if I can leverage podman v5.x with the Docker Compose v5.x plugin (not the podman-compose tool).

The tool does provide a better Developer Experience (DX) and also supports Init Containers logic (tested locally) which the podman-compose tool doesn't.

This discussion goes through a deeper-inspection on what probably a final missing-bit on leveraging the goal of something along the lines of:

podman --connection staging-srv compose -f staging.yml up -d

Initial Setup

One can easily leverage using the compose plugin with podman by doing the following:

mkdir -p ~/.docker/cli-plugins
wget https://github.com/docker/compose/releases/download/v5.3.1/docker-compose-linux-x86_64 \
  -O ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugin/docker-compose

Simple test:

podman compose version
v5.3.1

In order to leverage building a compose application:

systemctl --user enable --now podman.socket

on such machines:

podman compose -f compose.yml up -d

works flawlessly.

Experimenting with Remote Connections

Assume the the two identical machines are setup based on the information provided in Initial Setup above.

Name	podman version
box-01 (Ubuntu)	5.7.0
box-02 (Rocky Linux)	5.8.2

These boxes are configured to have passwordless SSH login already.

Assume box-01 is a staging server and box-02 is development environment.

Setup Connection

on box-01:

sudo systemctl enable --now sshd

systemctl --user enable --now podman.socket
# /run/user/1001/podman/podman.sock

on box-02:

podman system connection add staging \
  --identity ~/.ssh/id_ed25519 \
  ssh://laborant@box-01

list connection:

podman system connection ls
Name        URI                                                        Identity                        Default     ReadWrite
staging      ssh://laborant@box-01:22/run/user/1001/podman/podman.sock  /home/laborant/.ssh/id_ed25519  true        true

remote CLI trials:

podman -c staging info -f '{{ .Version }}'
v{5.7.0 5.7.0 go1.25.0  Mon Feb 23 15:35:32 2026 1771860932 Ubuntu linux/amd64 linux}

podman info -f '{{ .Version }}'
{5.8.2 5.8.2 go1.26.5 (Red Hat 1.26.5-1.el10_2) a476c2b2c35443a3db1a1668ac7b402eb1eb0619 Fri Jul 10 00:00:00 2026 1783641600 Rocky Linux Build System <releng@rockylinux.org> linux/amd64 linux}

Trials and Tribulations with podman --remote compose

podman --remote compose up -d

For the following simple compose.yml file:

# compose.yml
services
  test:
    image: busybox:latest
    command: 'sleep infinity'

Trying to perform spews out docker related error

podman --log-level=debug --remote compose -f test.yml up

INFO[0000] podman filtering at log level debug          
DEBU[0000] Called compose.PersistentPreRunE(podman --log-level=debug --remote compose -f test.yml up) 
DEBU[0000] SSH Ident Key "/home/laborant/.ssh/id_ed25519" SHA256:iUqndfQnhvkJog/l7+ezkmGhtL8rZEqQPrKtJ2iaPtA ssh-ed25519 
DEBU[0000] DoRequest Method: GET URI: http://d/v5.8.2/libpod/_ping 
DEBU[0000] SSH Ident Key "/home/laborant/.ssh/id_ed25519" SHA256:iUqndfQnhvkJog/l7+ezkmGhtL8rZEqQPrKtJ2iaPtA ssh-ed25519 
DEBU[0000] DoRequest Method: GET URI: http://d/v5.8.2/libpod/_ping 
DEBU[0000] Found compose provider "/home/laborant/.docker/cli-plugins/docker-compose" 
DEBU[0000] Executing compose provider (/home/laborant/.docker/cli-plugins/docker-compose -f test.yml up) with additional env DOCKER_HOST=ssh://laborant@box-01:22 DOCKER_BUILDKIT=0 DOCKER_CONFIG= 

unable to get image 'busybox:latest': error during connect: Get "http://docker.example.com/v1.55/images/busybox:latest/json": command [ssh -l laborant -p 22 -o ConnectTimeout=30 -T -- box-01 docker system dial-stdio] has exited with exit status 127, make sure the URL is valid, and Docker 18.09 or later is installed on the remote host: stderr=bash: line 1: docker: command not found

Error: executing /home/laborant/.docker/cli-plugins/docker-compose -f test.yml up: exit status 1
DEBU[0000] Shutting down engines       

Makes sense as the compose plugin expects Docker CLI to exist remote (which doesn't)

leveraging DOCKER_HOST

compose plugin does recognize DOCKER_HOST as seen in the logs above:

DOCKER_HOST=$(podman system connection ls -f '{{ .URI }}') podman --remote compose up -d

would result in the same output as above.

Leveraging DOCKER_HOST as podman.socket path

export DOCKER_HOST=$(podman --remote info -f '{{ .Host.RemoteSocket.Path }}')
# /run/user/1001/podman/podman.sock
podman --remote compose -f test.yml up -d

Would infact start the Application locally and not remotely:

INFO[0000] podman filtering at log level debug          
DEBU[0000] Called compose.PersistentPreRunE(podman --log-level=debug --remote compose -f test.yml up -d) 
DEBU[0000] SSH Ident Key "/home/laborant/.ssh/id_ed25519" SHA256:iUqndfQnhvkJog/l7+ezkmGhtL8rZEqQPrKtJ2iaPtA ssh-ed25519 
DEBU[0000] DoRequest Method: GET URI: http://d/v5.8.2/libpod/_ping 
DEBU[0000] SSH Ident Key "/home/laborant/.ssh/id_ed25519" SHA256:iUqndfQnhvkJog/l7+ezkmGhtL8rZEqQPrKtJ2iaPtA ssh-ed25519 
DEBU[0000] DoRequest Method: GET URI: http://d/v5.8.2/libpod/_ping 
DEBU[0000] Found compose provider "/home/laborant/.docker/cli-plugins/docker-compose" 
DEBU[0000] Executing compose provider (/home/laborant/.docker/cli-plugins/docker-compose -f test.yml up -d) with additional env DOCKER_HOST=unix:///run/user/1001/podman/podman.sock DOCKER_BUILDKIT=0 DOCKER_CONFIG= 
>>>> Executing external compose provider "/home/laborant/.docker/cli-plugins/docker-compose". Please see podman-compose(1) for how to disable this message. <<<<

[+] up 2/2
 ✔ Network laborant_default  Created                                                         0.0s 
 ✔ Container laborant-test-1 Started                                                         0.1s
DEBU[0000] Called compose.PersistentPostRunE(podman --log-level=debug --remote compose -f test.yml up -d) 
DEBU[0000] Shutting down engines   

Only way possible: SSH tunneling

because connecting to remote socket via SSH doesn't work, the only way out is to use:

ssh -N \
  -L /tmp/podman-box01.sock:/run/user/1000/podman/podman.sock \
  laborant@box-01

Deploy the application:

DOCKER_HOST=unix:///tmp/podman-box01.sock podman --log-level=debug --remote compose -f test.yml up -d
INFO[0000] podman filtering at log level debug          
DEBU[0000] Called compose.PersistentPreRunE(podman --log-level=debug --remote compose -f test.yml up -d) 
DEBU[0000] SSH Ident Key "/home/laborant/.ssh/id_ed25519" SHA256:iUqndfQnhvkJog/l7+ezkmGhtL8rZEqQPrKtJ2iaPtA ssh-ed25519 
DEBU[0000] DoRequest Method: GET URI: http://d/v5.8.2/libpod/_ping 
DEBU[0000] SSH Ident Key "/home/laborant/.ssh/id_ed25519" SHA256:iUqndfQnhvkJog/l7+ezkmGhtL8rZEqQPrKtJ2iaPtA ssh-ed25519 
DEBU[0000] DoRequest Method: GET URI: http://d/v5.8.2/libpod/_ping 
DEBU[0000] Found compose provider "/home/laborant/.docker/cli-plugins/docker-compose" 
DEBU[0000] Executing compose provider (/home/laborant/.docker/cli-plugins/docker-compose -f test.yml up -d) with additional env DOCKER_HOST=unix:///tmp/podman-box01.sock DOCKER_BUILDKIT=0 DOCKER_CONFIG= 
>>>> Executing external compose provider "/home/laborant/.docker/cli-plugins/docker-compose". Please see podman-compose(1) for how to disable this message. <<<<

[+] up 1/1
 ✔ Container laborant-test-1 Running                                                         0.0s
DEBU[0000] Called compose.PersistentPostRunE(podman --log-level=debug --remote compose -f test.yml up -d) 
DEBU[0000] Shutting down engines 

So adding this socket to a connection:

podman system connection add compose-box01 unix:///tmp/podman-box01.sock

Finally:

podman -c compose-box01 compose -f test.yml up -d

This time the deployment actually works and only the remote machine has the deployed container.

Query

Is this the only possible way to leverage remote podman + docker compose plugin?

Or can podman system leverage an SSH proxy / tunneling logic to help with the lifecycle of the tunnel?

Or is this something that is beyond the realm of Podman and relies on the compose development design?

[shantanoo-desai]

Investigations

I think a better solution / hack that I found instead of SSH tunneling:

Wrapper spoofing:

sudo tee /usr/local/bin/docker >/dev/null <<'EOF'
#!/bin/sh
exec podman "$@"
EOF
sudo chmod +x /usr/local/bin/docker

OR

sudo ln -s $(which podman) /usr/local/bin/docker

Implementing this on the remote machine works like a charm.

[lewis-qs]

I have to use some software that execs to docker under the hood, I use the podman-docker Fedora package and never had any issues, with the caveat I don't think it's doing anything with compose though but assume in practice it would work the same. I think it's just these wrappers on the podman GitHub repository.