Merge pull request #19297 from vrothberg/RUN-1865

add a podman-compose command

cmd/podman/compose.go

@@ -0,0 +1,302 @@
+//go:build amd64 || arm64
+// +build amd64 arm64
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"os/exec"
+	"runtime"
+	"strconv"
+	"strings"
+	"text/template"
+
+	"github.com/containers/common/pkg/config"
+	cmdMachine "github.com/containers/podman/v4/cmd/podman/machine"
+	"github.com/containers/podman/v4/cmd/podman/registry"
+	"github.com/containers/podman/v4/pkg/machine"
+	"github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+var composeCommand = &cobra.Command{
+	Use:   "compose [options]",
+	Short: "Run compose workloads via an external provider such as docker-compose or podman-compose",
+	Long: `This command is a thin wrapper around an external compose provider such as docker-compose or podman-compose.  This means that podman compose is executing another tool that implements the compose functionality but sets up the environment in a way to let the compose provider communicate transparently with the local Podman socket.  The specified options as well the command and argument are passed directly to the compose provider.
+
+The default compose providers are docker-compose and podman-compose.  If installed, docker-compose takes precedence since it is the original implementation of the Compose specification and is widely used on the supported platforms (i.e., Linux, Mac OS, Windows).
+
+If you want to change the default behavior or have a custom installation path for your provider of choice, please change the compose_provider field in containers.conf(5).  You may also set PODMAN_COMPOSE_PROVIDER environment variable.`,
+	RunE:              composeMain,
+	ValidArgsFunction: composeCompletion,
+	Example: `podman compose -f nginx.yaml up --detach
+  podman --log-level=debug compose -f many-images.yaml pull`,
+	DisableFlagParsing: true,
+	Annotations:        map[string]string{registry.ParentNSRequired: ""}, // don't join user NS for SSH to work correctly
+}
+
+func init() {
+	// NOTE: we need to fully disable flag parsing and manually parse the
+	// flags in composeMain. cobra's FParseErrWhitelist will strip off
+	// unknown flags _before_ the first argument.  So `--unknown argument`
+	// will show as `argument`.
+
+	registry.Commands = append(registry.Commands, registry.CliCommand{Command: composeCommand})
+}
+
+func composeCompletion(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	var stdout strings.Builder
+
+	args = append(args, toComplete)
+	args = append([]string{"__complete"}, args...)
+	if err := composeProviderExec(args, &stdout, io.Discard, false); err != nil {
+		// Ignore errors since some providers may not expose a __complete command.
+		return nil, cobra.ShellCompDirectiveError
+	}
+
+	var num int
+	output := strings.Split(strings.TrimRight(stdout.String(), "\n"), "\n")
+	if len(output) >= 1 {
+		if lastLine := output[len(output)-1]; strings.HasPrefix(lastLine, ":") {
+			var err error
+			if num, err = strconv.Atoi(lastLine[1:]); err != nil {
+				return nil, cobra.ShellCompDirectiveError
+			}
+			output = output[:len(output)-1]
+		}
+	}
+	return output, cobra.ShellCompDirective(num)
+}
+
+// composeProvider provides the name of or absolute path to the compose
+// provider (i.e., the external binary such as docker-compose).
+func composeProvider() (string, error) {
+	if value, ok := os.LookupEnv("PODMAN_COMPOSE_PROVIDER"); ok {
+		return value, nil
+	}
+
+	candidates := registry.PodmanConfig().ContainersConfDefaultsRO.Engine.ComposeProviders
+	if len(candidates) == 0 {
+		return "", errors.New("no compose provider specified, please refer to `man podman-compose` for details")
+	}
+
+	for _, candidate := range candidates {
+		path, err := exec.LookPath(os.ExpandEnv(candidate))
+		if err != nil {
+			if errors.Is(err, os.ErrNotExist) {
+				continue
+			}
+			return "", err
+		}
+		// First specified provider "candidate" wins.
+		logrus.Debugf("Found compose provider %q", path)
+		return path, nil
+	}
+
+	return "", errors.New("no configured compose provider found on system, please refer to the documentation for details")
+}
+
+// composeDockerHost returns the value to be set in the DOCKER_HOST environment
+// variable.
+func composeDockerHost() (string, error) {
+	if value, ok := os.LookupEnv("DOCKER_HOST"); ok {
+		return value, nil
+	}
+
+	// For local clients (Linux/FreeBSD), use the default API
+	// address.
+	if !registry.IsRemote() {
+		return registry.DefaultAPIAddress(), nil
+	}
+
+	cfg, err := config.ReadCustomConfig()
+	if err != nil {
+		return "", err
+	}
+
+	// NOTE: podman --connection=foo and --url=... are injected
+	// into the default connection below in `root.go`.
+	defaultConnection := cfg.Engine.ActiveService
+	if defaultConnection == "" {
+		switch runtime.GOOS {
+		// If no default connection is set on Linux or FreeBSD,
+		// we just use the local socket by default - just as
+		// the remote client does.
+		case "linux", "freebsd":
+			return registry.DefaultAPIAddress(), nil
+		// If there is no default connection on Windows or Mac
+		// OS, we can safely assume that something went wrong.
+		// A `podman machine init` will set the connection.
+		default:
+			return "", fmt.Errorf("cannot connect to a socket or via SSH: no default connection found: consider running `podman machine init`")
+		}
+	}
+
+	connection, ok := cfg.Engine.ServiceDestinations[defaultConnection]
+	if !ok {
+		return "", fmt.Errorf("internal error: default connection %q not found in database", defaultConnection)
+	}
+	parsedConnection, err := url.Parse(connection.URI)
+	if err != nil {
+		return "", fmt.Errorf("preparing connection to remote machine: %w", err)
+	}
+
+	// If the default connection does not point to a `podman
+	// machine`, we cannot use a local path and need to use SSH.
+	if !connection.IsMachine {
+		// Compose doesn't like paths, so we optimistically
+		// assume the presence of a Docker socket on the remote
+		// machine which is the case for podman machines.
+		return strings.TrimSuffix(connection.URI, parsedConnection.Path), nil
+	}
+
+	machineProvider, err := cmdMachine.GetSystemProvider()
+	if err != nil {
+		return "", fmt.Errorf("getting machine provider: %w", err)
+	}
+	machineList, err := machineProvider.List(machine.ListOptions{})
+	if err != nil {
+		return "", fmt.Errorf("listing machines: %w", err)
+	}
+
+	// Now we know that the connection points to a machine and we
+	// can find the machine by looking for the one with the
+	// matching port.
+	connectionPort, err := strconv.Atoi(parsedConnection.Port())
+	if err != nil {
+		return "", fmt.Errorf("parsing connection port: %w", err)
+	}
+	for _, item := range machineList {
+		if connectionPort != item.Port {
+			continue
+		}
+
+		vm, err := machineProvider.LoadVMByName(item.Name)
+		if err != nil {
+			return "", fmt.Errorf("loading machine: %w", err)
+		}
+		info, err := vm.Inspect()
+		if err != nil {
+			return "", fmt.Errorf("inspecting machine: %w", err)
+		}
+		if info.ConnectionInfo.PodmanSocket == nil {
+			return "", errors.New("socket of machine is not set")
+		}
+		if info.State != machine.Running {
+			return "", fmt.Errorf("machine %s is not running but in state %s", item.Name, info.State)
+		}
+		return "unix://" + info.ConnectionInfo.PodmanSocket.Path, nil
+	}
+
+	return "", fmt.Errorf("could not find a matching machine for connection %q", connection.URI)
+}
+
+// composeEnv returns the compose-specific environment variables.
+func composeEnv() ([]string, error) {
+	hostValue, err := composeDockerHost()
+	if err != nil {
+		return nil, err
+	}
+
+	return []string{
+		"DOCKER_HOST=" + hostValue,
+		// Podman doesn't support all buildkit features and since it's
+		// a continuous catch-up game, disable buildkit on the client
+		// side.
+		//
+		// See https://github.com/containers/podman/issues/18617#issuecomment-1600495841
+		"DOCKER_BUILDKIT=0",
+		// FIXME: DOCKER_CONFIG is limited by containers/podman/issues/18617
+		//        and it remains unclear which default path should be set
+		//        w.r.t. Docker compatibility and a smooth experience of podman-login
+		//        working with podman-compose _by default_.
+		"DOCKER_CONFIG=" + os.Getenv("DOCKER_CONFIG"),
+	}, nil
+}
+
+// underline uses ANSI codes to underline the specified string.
+func underline(str string) string {
+	return "\033[4m" + str + "\033[0m"
+}
+
+// composeProviderExec executes the compose provider with the specified arguments.
+func composeProviderExec(args []string, stdout io.Writer, stderr io.Writer, warn bool) error {
+	provider, err := composeProvider()
+	if err != nil {
+		return err
+	}
+
+	env, err := composeEnv()
+	if err != nil {
+		return err
+	}
+
+	if stdout == nil {
+		stdout = os.Stdout
+	}
+	if stderr == nil {
+		stderr = os.Stderr
+	}
+
+	cmd := exec.Command(provider, args...)
+	cmd.Stdin = os.Stdin
+	cmd.Stdout = stdout
+	cmd.Stderr = stderr
+	cmd.Env = append(os.Environ(), env...)
+	logrus.Debugf("Executing compose provider (%s %s) with additional env %s", provider, strings.Join(args, " "), strings.Join(env, " "))
+
+	if warn {
+		fmt.Fprint(os.Stderr, underline(fmt.Sprintf(">>>> Executing external compose provider %q. Please refer to the documentation for details. <<<<\n\n", provider)))
+	}
+
+	if err := cmd.Run(); err != nil {
+		// Make sure podman returns with the same exit code as the compose provider.
+		if exitErr, isExit := err.(*exec.ExitError); isExit {
+			registry.SetExitCode(exitErr.ExitCode())
+		}
+		// Format the error to make it explicit that error did not come
+		// from podman but from the executed compose provider.
+		return fmt.Errorf("executing %s %s: %w", provider, strings.Join(args, " "), err)
+	}
+
+	return nil
+}
+
+// composeHelp is a custom help function to display the help message of the
+// configured compose-provider.
+func composeHelp(cmd *cobra.Command) error {
+	tmpl, err := template.New("help_template").Parse(helpTemplate)
+	if err != nil {
+		return err
+	}
+	if err := tmpl.Execute(os.Stdout, cmd); err != nil {
+		return err
+	}
+
+	return composeProviderExec([]string{"--help"}, nil, nil, registry.PodmanConfig().ContainersConfDefaultsRO.Engine.ComposeWarningLogs)
+}
+
+// composeMain is the main function of the compose command.
+func composeMain(cmd *cobra.Command, args []string) error {
+	// We have to manually parse the flags here to make sure all arguments
+	// after `podman compose [ARGS]` are passed to the compose provider.
+	// For now, we only look for the --help flag.
+	fs := pflag.NewFlagSet("args", pflag.ContinueOnError)
+	fs.ParseErrorsWhitelist.UnknownFlags = true
+	fs.SetInterspersed(false)
+	fs.BoolP("help", "h", false, "")
+	if err := fs.Parse(args); err != nil {
+		return fmt.Errorf("parsing arguments: %w", err)
+	}
+
+	if len(args) == 0 || fs.Lookup("help").Changed {
+		return composeHelp(cmd)
+	}
+
+	return composeProviderExec(args, nil, nil, registry.PodmanConfig().ContainersConfDefaultsRO.Engine.ComposeWarningLogs)
+}

docs/source/markdown/.gitignore

@@ -1,6 +1,7 @@
 podman-attach.1.md
 podman-auto-update.1.md
 podman-build.1.md
+podman-compose.1.md
 podman-container-clone.1.md
 podman-container-diff.1.md
 podman-container-inspect.1.md

docs/source/markdown/podman-compose.1.md.in

@@ -0,0 +1,21 @@
+% podman-compose 1
+
+## NAME
+podman\-compose - Run Compose workloads via an external compose provider
+
+## SYNOPSIS
+**podman compose** [*options*] [*command* [*arg* ...]]
+
+## DESCRIPTION
+**podman compose** is a thin wrapper around an external compose provider such as docker-compose or podman-compose.  This means that `podman compose` is executing another tool that implements the compose functionality but sets up the environment in a way to let the compose provider communicate transparently with the local Podman socket.  The specified options as well the command and argument are passed directly to the compose provider.
+
+The default compose providers are `docker-compose` and `podman-compose`.  If installed, `docker-compose` takes precedence since it is the original implementation of the Compose specification and is widely used on the supported platforms (i.e., Linux, Mac OS, Windows).
+
+If you want to change the default behavior or have a custom installation path for your provider of choice, please change the `compose_provider` field in `containers.conf(5)`.  You may also set the `PODMAN_COMPOSE_PROVIDER` environment variable.
+
+## OPTIONS
+
+To see supported options of the installed compose provider, please run `podman compose --help`.
+
+## SEE ALSO
+**[podman(1)](podman.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**

docs/source/markdown/podman.1.md

@@ -315,6 +315,7 @@ the exit codes follow the `chroot` standard, see below:
 | [podman-build(1)](podman-build.1.md)             | Build a container image using a Containerfile.                              |
 | [podman-commit(1)](podman-commit.1.md)           | Create new image based on the changed container.                            |
 | [podman-completion(1)](podman-completion.1.md)   | Generate shell completion scripts                                           |
+| [podman-compose(1)](podman-compose.1.md)         | Run Compose workloads via an external compose provider.                     |
 | [podman-container(1)](podman-container.1.md)     | Manage containers.                                                          |
 | [podman-cp(1)](podman-cp.1.md)                   | Copy files/folders between a container and the local filesystem.            |
 | [podman-create(1)](podman-create.1.md)           | Create a new container.                                                     |

go.mod

@@ -13,7 +13,7 @@ require (
 	github.com/containernetworking/cni v1.1.2
 	github.com/containernetworking/plugins v1.3.0
 	github.com/containers/buildah v1.31.1-0.20230722114901-5ece066f82c6
-	github.com/containers/common v0.55.1-0.20230721175448-664d013a6ae2
+	github.com/containers/common v0.55.1-0.20230724161016-2966c705a7a3
 	github.com/containers/conmon v2.0.20+incompatible
 	github.com/containers/image/v5 v5.26.1-0.20230721194716-30c87d4a5b8d
 	github.com/containers/libhvee v0.4.0
@@ -48,7 +48,7 @@ require (
 	github.com/opencontainers/go-digest v1.0.0
 	github.com/opencontainers/image-spec v1.1.0-rc4
 	github.com/opencontainers/runc v1.1.8
-	github.com/opencontainers/runtime-spec v1.1.0-rc.3
+	github.com/opencontainers/runtime-spec v1.1.0
 	github.com/opencontainers/runtime-tools v0.9.1-0.20230317050512-e931285f4b69
 	github.com/opencontainers/selinux v1.11.0
 	github.com/openshift/imagebuilder v1.2.5

go.sum

@@ -247,8 +247,8 @@ github.com/containernetworking/plugins v1.3.0 h1:QVNXMT6XloyMUoO2wUOqWTC1hWFV62Q
 github.com/containernetworking/plugins v1.3.0/go.mod h1:Pc2wcedTQQCVuROOOaLBPPxrEXqqXBFt3cZ+/yVg6l0=
 github.com/containers/buildah v1.31.1-0.20230722114901-5ece066f82c6 h1:K/S8SFQsnnNTF0Ws58SrBD9L0EuClzAG8Zp08d7+6AA=
 github.com/containers/buildah v1.31.1-0.20230722114901-5ece066f82c6/go.mod h1:0sptTFBBtSznLqoTh80DfvMOCNbdRsNRgVOKhBhrupA=
-github.com/containers/common v0.55.1-0.20230721175448-664d013a6ae2 h1:4B42HUIAghFGSqej5RADTNf0WlOBFiGGzmGjNa3Do78=
-github.com/containers/common v0.55.1-0.20230721175448-664d013a6ae2/go.mod h1:O/JSRY1dLfwgBxVvn3yJfKvF63KEjbNJcJAtjpNvO90=
+github.com/containers/common v0.55.1-0.20230724161016-2966c705a7a3 h1:0fHDAdLNfOs5AuBizE7TOECDA4gCLoCgE6geR3k/H78=
+github.com/containers/common v0.55.1-0.20230724161016-2966c705a7a3/go.mod h1:SUX+gHoElocPp664K79AEt+GGHwngBJLrKdwNIRW0tQ=
 github.com/containers/conmon v2.0.20+incompatible h1:YbCVSFSCqFjjVwHTPINGdMX1F6JXHGTUje2ZYobNrkg=
 github.com/containers/conmon v2.0.20+incompatible/go.mod h1:hgwZ2mtuDrppv78a/cOBNiCm6O0UMWGx1mu7P00nu5I=
 github.com/containers/image/v5 v5.26.1-0.20230721194716-30c87d4a5b8d h1:g6DFcXXEMd1OwSVtbrUolGzmkMNyQDyc4OKHOFxbNeE=
@@ -820,8 +820,8 @@ github.com/opencontainers/runtime-spec v1.0.2-0.20190207185410-29686dbc5559/go.m
 github.com/opencontainers/runtime-spec v1.0.2/go.mod h1:jwyrGlmzljRJv/Fgzds9SsS/C5hL+LL3ko9hs6T5lQ0=
 github.com/opencontainers/runtime-spec v1.0.3-0.20200929063507-e6143ca7d51d/go.mod h1:jwyrGlmzljRJv/Fgzds9SsS/C5hL+LL3ko9hs6T5lQ0=
 github.com/opencontainers/runtime-spec v1.0.3-0.20210326190908-1c3f411f0417/go.mod h1:jwyrGlmzljRJv/Fgzds9SsS/C5hL+LL3ko9hs6T5lQ0=
-github.com/opencontainers/runtime-spec v1.1.0-rc.3 h1:l04uafi6kxByhbxev7OWiuUv0LZxEsYUfDWZ6bztAuU=
-github.com/opencontainers/runtime-spec v1.1.0-rc.3/go.mod h1:jwyrGlmzljRJv/Fgzds9SsS/C5hL+LL3ko9hs6T5lQ0=
+github.com/opencontainers/runtime-spec v1.1.0 h1:HHUyrt9mwHUjtasSbXSMvs4cyFxh+Bll4AjJ9odEGpg=
+github.com/opencontainers/runtime-spec v1.1.0/go.mod h1:jwyrGlmzljRJv/Fgzds9SsS/C5hL+LL3ko9hs6T5lQ0=
 github.com/opencontainers/runtime-tools v0.0.0-20181011054405-1d69bd0f9c39/go.mod h1:r3f7wjNzSs2extwzU3Y+6pKfobzPh+kKFJ3ofN+3nfs=
 github.com/opencontainers/runtime-tools v0.9.1-0.20230317050512-e931285f4b69 h1:NL4xDvl68WWqQ+8WPMM3l5PsZTxaT7Z4K3VSKDRuAGs=
 github.com/opencontainers/runtime-tools v0.9.1-0.20230317050512-e931285f4b69/go.mod h1:bNpfuSHA3DZRtD0TPWO8LzgtLpFPTVA/3jDkzD/OPyk=

hack/man-page-checker

@@ -78,6 +78,11 @@ function compare_usage() {
     local cmd="$1"
     local from_man="$2"
 
+    # Special case: this is an external call to docker
+    if [[ $cmd = "podman compose" ]] || [[ $cmd = "podmansh" ]]; then
+        return
+    fi
+
     # Sometimes in CI we run before podman gets built.
     test -x ../../../bin/podman || return
 

hack/xref-helpmsgs-manpages

@@ -95,6 +95,13 @@ my %Format_Option_Is_Special = map { $_ => 1 } (
     'inspect',                                  # ambiguous (container/image)
  );
 
+# Do not cross-reference these.
+my %Skip_Subcommand = map { $_ => 1 } (
+    "help",                     # has no man page
+    "completion",               # internal (hidden) subcommand
+    "compose",                  # external tool, outside of our control
+);
+
 # END   user-customizable section
 ###############################################################################
 
@@ -279,8 +286,8 @@ sub xref_by_man {
 
             next if "@subcommand" eq 'system' && $k eq 'service';
 
-            # Special case: podman completion is a hidden command
-            next if $k eq 'completion';
+            # Special case for hidden or external commands
+            next if $Skip_Subcommand{$k};
 
             warn "$ME: 'podman @subcommand': $k in $man, but not --help\n";
             ++$Errs;
@@ -346,7 +353,7 @@ sub podman_help {
                 }
 
                 $help{$subcommand} = podman_help(@_, $subcommand)
-                    unless $subcommand eq 'help';       # 'help' not in man
+                    unless $Skip_Subcommand{$subcommand};
             }
         }
         elsif ($section eq 'options') {

pkg/rootless/rootless_linux.c

@@ -387,6 +387,7 @@ can_use_shortcut (char **argv)
           || strcmp (argv[argc], "version") == 0
           || strcmp (argv[argc], "context") == 0
           || strcmp (argv[argc], "search") == 0
+          || strcmp (argv[argc], "compose") == 0
           || (strcmp (argv[argc], "system") == 0 && argv[argc+1] && strcmp (argv[argc+1], "service") != 0))
         {
           ret = false;

test/compose/test-compose

@@ -276,11 +276,12 @@ done
 # When rootless use a socket path accessible by the rootless user
 if is_rootless; then
     DOCKER_SOCK="$WORKDIR/docker.sock"
-    DOCKER_HOST="unix://$DOCKER_SOCK"
-    # export DOCKER_HOST docker-compose will use it
-    export DOCKER_HOST
 fi
 
+# export DOCKER_HOST docker-compose will use it
+DOCKER_HOST="unix://$DOCKER_SOCK"
+export DOCKER_HOST
+
 # Identify the tests to run. If called with args, use those as globs.
 tests_to_run=()
 if [ -n "$*" ]; then
@@ -331,12 +332,12 @@ for t in "${tests_to_run[@]}"; do
             trap '. teardown.sh' 0
         fi
 
-        docker-compose up -d     &> $logfile
+        podman compose up -d     &> $logfile
         docker_compose_rc=$?
         if [[ $docker_compose_rc -ne 0 ]]; then
             _show_ok 0 "$testname - up" "[ok]" "status=$docker_compose_rc"
             sed -e 's/^/#  /' <$logfile
-            docker-compose down >>$logfile 2>&1      # No status check here
+            podman compose down >>$logfile 2>&1      # No status check here
             exit 1
         fi
         _show_ok 1 "$testname - up"
@@ -354,7 +355,7 @@ for t in "${tests_to_run[@]}"; do
         fi
 
         # Done. Clean up.
-        docker-compose down     &>> $logfile
+        podman compose down     &>> $logfile
         rc=$?
         if [[ $rc -eq 0 ]]; then
             _show_ok 1 "$testname - down"

test/system/015-help.bats

@@ -17,6 +17,11 @@ function check_help() {
     local -A found
 
     for cmd in $(_podman_commands "$@"); do
+        # Skip the compose command which is calling `docker-compose --help`
+        # and hence won't match the assumptions made below.
+        if [[ "$cmd" == "compose" ]]; then
+            continue
+        fi
         # Human-readable podman command string, with multiple spaces collapsed
         command_string="podman $* $cmd"
         command_string=${command_string//  / }  # 'podman  x' -> 'podman x'

test/system/600-completion.bats

@@ -37,6 +37,11 @@ function check_shell_completion() {
 "
 
     for cmd in $(_podman_commands "$@"); do
+        # Skip the compose command which is calling `docker-compose --help`
+        # and hence won't match the assumptions made below.
+        if [[ "$cmd" == "compose" ]]; then
+            continue
+        fi
         # Human-readable podman command string, with multiple spaces collapsed
         name="podman"
         if is_remote; then

test/system/610-format.bats

@@ -55,6 +55,12 @@ can_run_stats=
 #        > run the command with --format '{{"\n"}}' and make sure it passes
 function check_subcommand() {
     for cmd in $(_podman_commands "$@"); do
+        # Skip the compose command which is calling `docker-compose --help`
+        # and hence won't match the assumptions made below.
+        if [[ "$cmd" == "compose" ]]; then
+            continue
+        fi
+        # Human-readable podman command string, with multiple spaces collapsed
         # Special case: 'podman machine' can only be run under ideal conditions
         if [[ "$cmd" = "machine" ]] && [[ -z "$can_run_podman_machine" ]]; then
             continue

test/system/850-compose.bats

@@ -0,0 +1,67 @@
+#!/usr/bin/env bats   -*- bats -*-
+#
+# Smoke tests for the podman-compose command.  test/compose takes care of functional tests.
+#
+
+load helpers
+
+@test "podman compose - smoke tests" {
+    fake_compose_bin="$PODMAN_TMPDIR/fake_compose"
+    cat >$fake_compose_bin <<EOF
+#!/bin/bash
+if [[ "\$@" == "fail" ]]; then
+    exit 42
+fi
+if [[ "\$@" == "env" ]]; then
+    printenv DOCKER_HOST DOCKER_BUILDKIT DOCKER_CONFIG
+    exit 0
+fi
+echo "arguments: \$@"
+EOF
+
+    compose_conf="$PODMAN_TMPDIR/compose.conf"
+    cat >$compose_conf <<EOF
+[engine]
+compose_providers = ["$fake_compose_bin"]
+compose_warning_logs = false
+EOF
+
+    random_data="--foo=bar --random=$(random_string 15) -f /path/to/file ignore me"
+
+    # Make sure that the fake compose binary is used and that error reporting works
+    PODMAN_COMPOSE_PROVIDER=$fake_compose_bin run_podman 125 compose --help
+    is "$output" ".*executing $fake_compose_bin --help: .*: permission denied"
+
+    # Make the fake one executable and check the --help output
+    chmod +x $fake_compose_bin
+    PODMAN_COMPOSE_PROVIDER=$fake_compose_bin run_podman compose --help
+    is "$output" "Run compose workloads via an external provider .*arguments: --help"
+
+    # No argument yields the help message as well
+    PODMAN_COMPOSE_PROVIDER=$fake_compose_bin run_podman compose
+    is "$output" "Run compose workloads via an external provider .*arguments: "
+
+    # Make sure that the provider can be specified via containers.conf and that
+    # the warning logs can be turned off
+    CONTAINERS_CONF_OVERRIDE=$compose_conf run_podman compose --help
+    is "$output" "Run compose workloads via an external provider .*arguments: --help"
+    assert "$output" !~ ".*Executing external compose provider.*"
+
+    # Run with bogus arguments and make sure they're being returned
+    CONTAINERS_CONF_OVERRIDE=$compose_conf run_podman compose $random_data
+    is "$output" "arguments: $random_data"
+
+    # Make sure Podman returns the exit code of the compose provider
+    CONTAINERS_CONF_OVERRIDE=$compose_conf run_podman 42 compose fail
+
+    # Make sure the three env variables are set (and parsed)
+    CONTAINERS_CONF_OVERRIDE=$compose_conf run_podman compose env
+    is "${lines[0]}" ".*/podman.sock"
+    is "${lines[1]}" "0"
+    is "${lines[2]}" ""
+
+    DOCKER_HOST="$random_data" DOCKER_CONFIG="$random_data" CONTAINERS_CONF_OVERRIDE=$compose_conf run_podman compose env
+    is "${lines[0]}" "$random_data"
+    is "${lines[1]}" "0"
+    is "${lines[2]}" "$random_data"
+}

vendor/github.com/containers/common/pkg/config/config.go

@@ -266,6 +266,17 @@ type EngineConfig struct {
 	// in containers-registries.conf(5).
 	CompatAPIEnforceDockerHub bool `toml:"compat_api_enforce_docker_hub,omitempty"`
 
+	// ComposeProviders specifies one or more external providers for the
+	// compose command.  The first found provider is used for execution.
+	// Can be an absolute and relative path or a (file) name.  Make sure to
+	// expand the return items via `os.ExpandEnv`.
+	ComposeProviders []string `toml:"compose_providers,omitempty"`
+
+	// ComposeWarningLogs emits logs on each invocation of the compose
+	// command indicating that an external compose provider is being
+	// executed.
+	ComposeWarningLogs bool `toml:"compose_warning_logs,omitempty"`
+
 	// DBBackend is the database backend to be used by Podman.
 	DBBackend string `toml:"database_backend,omitempty"`
 

vendor/github.com/containers/common/pkg/config/config_local.go

@@ -11,7 +11,7 @@ import (
 	"strings"
 	"syscall"
 
-	"github.com/container-orchestrated-devices/container-device-interface/pkg/cdi"
+	"github.com/container-orchestrated-devices/container-device-interface/pkg/parser"
 	units "github.com/docker/go-units"
 )
 
@@ -58,7 +58,7 @@ func (c *EngineConfig) validatePaths() error {
 
 func (c *ContainersConfig) validateDevices() error {
 	for _, d := range c.Devices {
-		if cdi.IsQualifiedName(d) {
+		if parser.IsQualifiedName(d) {
 			continue
 		}
 		_, _, _, err := Device(d)

vendor/github.com/containers/common/pkg/config/containers.conf

@@ -376,6 +376,20 @@ default_sysctls = [
 #
 #active_service = "production"
 
+# Enforces using docker.io for completing short names in Podman's compatibility
+# REST API. Note that this will ignore unqualified-search-registries and
+# short-name aliases defined in containers-registries.conf(5).
+#compat_api_enforce_docker_hub = true
+
+# Specify one or more external providers for the compose command.  The first
+# found provider is used for execution.  Can be an absolute and relative path
+# or a (file) name.
+#compose_providers=[]
+
+# Emit logs on each invocation of the compose command indicating that an
+# external compose provider is being executed.
+#compose_warning_logs = true
+
 # The compression format to use when pushing an image.
 # Valid options are: `gzip`, `zstd` and `zstd:chunked`.
 #

vendor/github.com/containers/common/pkg/config/containers.conf-freebsd

@@ -500,7 +500,7 @@ default_sysctls = [
 # List of the OCI runtimes that support --format=json. When json is supported
 # engine will use it for reporting nicer errors.
 #
-#runtime_supports_json = ["crun", "runc", "kata", "runsc", "youki", "krun"]
+#runtime_supports_json = ["crun", "runc", "kata", "runsc", "youki", "krun", "ocijail"]
 
 # List of the OCI runtimes that supports running containers with KVM Separation.
 #

vendor/github.com/containers/common/pkg/config/default.go

@@ -87,6 +87,16 @@ var (
 	// should be set during link-time, if different packagers put their
 	// helper binary in a different location.
 	additionalHelperBinariesDir string
+
+	defaultUnixComposeProviders = []string{
+		"docker-compose",
+		"$HOME/.docker/cli-plugins/docker-compose",
+		"/usr/local/lib/docker/cli-plugins/docker-compose",
+		"/usr/local/libexec/docker/cli-plugins/docker-compose",
+		"/usr/lib/docker/cli-plugins/docker-compose",
+		"/usr/libexec/docker/cli-plugins/docker-compose",
+		"podman-compose",
+	}
 )
 
 // nolint:unparam
@@ -260,6 +270,8 @@ func defaultConfigFromMemory() (*EngineConfig, error) {
 	c.EventsLogFileMaxSize = eventsLogMaxSize(DefaultEventsLogSizeMax)
 
 	c.CompatAPIEnforceDockerHub = true
+	c.ComposeProviders = getDefaultComposeProviders() // may vary across supported platforms
+	c.ComposeWarningLogs = true
 
 	if path, ok := os.LookupEnv("CONTAINERS_STORAGE_CONF"); ok {
 		if err := types.SetDefaultConfigFilePath(path); err != nil {
@@ -406,6 +418,7 @@ func defaultConfigFromMemory() (*EngineConfig, error) {
 		"runsc",
 		"youki",
 		"krun",
+		"ocijail",
 	}
 	c.RuntimeSupportsNoCgroups = []string{"crun", "krun"}
 	c.RuntimeSupportsKVM = []string{"kata", "kata-runtime", "kata-qemu", "kata-fc", "krun"}

vendor/github.com/containers/common/pkg/config/default_darwin.go

@@ -20,3 +20,14 @@ func getDefaultMachineVolumes() []string {
 		"/var/folders:/var/folders",
 	}
 }
+
+func getDefaultComposeProviders() []string {
+	return []string{
+		"docker-compose",
+		"$HOME/.docker/cli-plugins/docker-compose",
+		"/opt/homebrew/bin/docker-compose",
+		"/usr/local/bin/docker-compose",
+		"/Applications/Docker.app/Contents/Resources/cli-plugins/docker-compose",
+		"podman-compose",
+	}
+}

vendor/github.com/containers/common/pkg/config/default_freebsd.go

@@ -26,3 +26,7 @@ func getLibpodTmpDir() string {
 func getDefaultMachineVolumes() []string {
 	return []string{"$HOME:$HOME"}
 }
+
+func getDefaultComposeProviders() []string {
+	return defaultUnixComposeProviders
+}

vendor/github.com/containers/common/pkg/config/default_linux.go

@@ -74,3 +74,7 @@ func getLibpodTmpDir() string {
 func getDefaultMachineVolumes() []string {
 	return []string{"$HOME:$HOME"}
 }
+
+func getDefaultComposeProviders() []string {
+	return defaultUnixComposeProviders
+}

vendor/github.com/containers/common/pkg/config/default_windows.go

@@ -49,3 +49,8 @@ func getLibpodTmpDir() string {
 func getDefaultMachineVolumes() []string {
 	return []string{}
 }
+
+func getDefaultComposeProviders() []string {
+	// Rely on os.LookPath to do the trick on Windows.
+	return []string{"docker-compose", "podman-compose"}
+}

vendor/github.com/containers/common/pkg/util/util.go

@@ -27,7 +27,16 @@ func queryPackageVersion(cmdArg ...string) string {
 		cmd := exec.Command(cmdArg[0], cmdArg[1:]...)
 		if outp, err := cmd.Output(); err == nil {
 			output = string(outp)
-			if cmdArg[0] == "/usr/bin/dpkg" {
+			deb := false
+			if cmdArg[0] == "/usr/bin/dlocate" {
+				// can return multiple matches
+				l := strings.Split(output, "\n")
+				output = l[0]
+				deb = true
+			} else if cmdArg[0] == "/usr/bin/dpkg" {
+				deb = true
+			}
+			if deb {
 				r := strings.Split(output, ": ")
 				queryFormat := `${Package}_${Version}_${Architecture}`
 				cmd = exec.Command("/usr/bin/dpkg-query", "-f", queryFormat, "-W", r[0])
@@ -47,9 +56,14 @@ func queryPackageVersion(cmdArg ...string) string {
 // Note: This function is copied from containers/podman libpod/util.go
 // Please see https://github.com/containers/common/pull/1460
 func PackageVersion(program string) string { // program is full path
+	_, err := os.Stat(program)
+	if err != nil {
+		return UnknownPackage
+	}
 	packagers := [][]string{
 		{"/usr/bin/rpm", "-q", "-f"},
-		{"/usr/bin/dpkg", "-S"},                // Debian, Ubuntu
+		{"/usr/bin/dlocate", "-F"},             // Debian, Ubuntu (quick)
+		{"/usr/bin/dpkg", "-S"},                // Debian, Ubuntu (slow)
 		{"/usr/bin/pacman", "-Qo"},             // Arch
 		{"/usr/bin/qfile", "-qv"},              // Gentoo (quick)
 		{"/usr/bin/equery", "b"},               // Gentoo (slow)

vendor/github.com/opencontainers/runtime-spec/specs-go/version.go

@@ -11,7 +11,7 @@ const (
 	VersionPatch = 0
 
 	// VersionDev indicates development branch. Releases will be empty string.
-	VersionDev = "-rc.3"
+	VersionDev = ""
 )
 
 // Version is the specification version that the package types support.

vendor/modules.txt

@@ -157,7 +157,7 @@ github.com/containers/buildah/pkg/rusage
 github.com/containers/buildah/pkg/sshagent
 github.com/containers/buildah/pkg/util
 github.com/containers/buildah/util
-# github.com/containers/common v0.55.1-0.20230721175448-664d013a6ae2
+# github.com/containers/common v0.55.1-0.20230724161016-2966c705a7a3
 ## explicit; go 1.18
 github.com/containers/common/libimage
 github.com/containers/common/libimage/define
@@ -815,7 +815,7 @@ github.com/opencontainers/runc/libcontainer/devices
 github.com/opencontainers/runc/libcontainer/user
 github.com/opencontainers/runc/libcontainer/userns
 github.com/opencontainers/runc/libcontainer/utils
-# github.com/opencontainers/runtime-spec v1.1.0-rc.3
+# github.com/opencontainers/runtime-spec v1.1.0
 ## explicit
 github.com/opencontainers/runtime-spec/specs-go
 # github.com/opencontainers/runtime-tools v0.9.1-0.20230317050512-e931285f4b69