feat(docker-compose): support auto-detection of docker-compose client (#898)

- Introduce auto-client detection (local if exists, or containerised
otherwise) as an explicit option
- Enhance containerised client with additional option
"project-directory" - it matters because compose is called from Docker,
but volumes and configs in compose files will mount from host system


Backward compatibility preserved

Author: DDtKey

docs/features/docker_compose.md

@@ -151,6 +151,32 @@ compose.up().await?;
 - Consistent compose version across environments
 - Useful for CI/CD where Docker CLI might not be available
 
+If your compose files use relative paths for bind mounts, set an explicit project directory so
+docker compose resolves those paths against the host location:
+
+```rust
+use testcontainers::compose::{ContainerisedComposeOptions, DockerCompose};
+
+let options = ContainerisedComposeOptions::new(&["/home/me/app/docker-compose.yml"])
+    .with_project_directory("/home/me/app");
+
+let mut compose = DockerCompose::with_containerised_client(options).await?;
+compose.up().await?;
+```
+
+### Auto Client
+
+Tries the local `docker compose` CLI first and falls back to the containerised client:
+
+```rust
+use testcontainers::compose::{AutoComposeOptions, DockerCompose};
+
+let options = AutoComposeOptions::new(&["docker-compose.yml"]);
+
+let mut compose = DockerCompose::with_auto_client(options).await?;
+compose.up().await?;
+```
+
 ## Configuration Options
 
 ### Environment Variables

testcontainers/src/compose/client.rs

@@ -1,6 +1,6 @@
 use std::{fmt, path::PathBuf};
 
-use crate::compose::error::Result;
+use crate::compose::{error::Result, ContainerisedComposeOptions};
 
 pub(super) mod containerised;
 pub(super) mod local;
@@ -15,9 +15,9 @@ impl ComposeClient {
         ComposeClient::Local(local::LocalComposeCli::new(compose_files))
     }
 
-    pub(super) async fn new_containerised(compose_files: Vec<PathBuf>) -> Result<Self> {
+    pub(super) async fn new_containerised(options: ContainerisedComposeOptions) -> Result<Self> {
         Ok(ComposeClient::Containerised(Box::new(
-            containerised::ContainerisedComposeCli::new(compose_files).await?,
+            containerised::ContainerisedComposeCli::new(options).await?,
         )))
     }
 }

testcontainers/src/compose/client/containerised.rs

@@ -1,11 +1,10 @@
-use std::path::PathBuf;
-
 use crate::{
     compose::{
         client::{ComposeInterface, DownCommand, UpCommand},
         error::Result,
+        ContainerisedComposeOptions,
     },
-    core::{CmdWaitFor, ExecCommand, Mount},
+    core::{CmdWaitFor, ExecCommand},
     images::docker_cli::DockerCli,
     runners::AsyncRunner,
     ContainerAsync, ContainerRequest, ImageExt,
@@ -14,32 +13,33 @@ use crate::{
 pub(crate) struct ContainerisedComposeCli {
     container: ContainerAsync<DockerCli>,
     compose_files_in_container: Vec<String>,
+    project_directory: Option<String>,
 }
 
 impl ContainerisedComposeCli {
-    pub(super) async fn new(compose_files: Vec<PathBuf>) -> Result<Self> {
+    pub(super) async fn new(options: ContainerisedComposeOptions) -> Result<Self> {
+        let (compose_files, project_directory) = options.into_parts();
         let mut image = ContainerRequest::from(DockerCli::new("/var/run/docker.sock"));
 
         let compose_files_in_container: Vec<String> = compose_files
             .iter()
             .enumerate()
             .map(|(i, _)| format!("/docker-compose-{i}.yml"))
             .collect();
-        let mounts: Vec<_> = compose_files
-            .iter()
+        for (path, file_name) in compose_files
+            .into_iter()
             .zip(compose_files_in_container.iter())
-            .filter_map(|(path, file_name)| path.to_str().map(|p| Mount::bind_mount(p, file_name)))
-            .collect();
-
-        for mount in mounts {
-            image = image.with_mount(mount);
+        {
+            image = image.with_copy_to(file_name, path);
         }
 
         let container = image.start().await?;
+        let project_directory = project_directory.map(|path| path.to_string_lossy().into_owned());
 
         Ok(Self {
             container,
             compose_files_in_container,
+            project_directory,
         })
     }
 }
@@ -52,12 +52,15 @@ impl ComposeInterface for ContainerisedComposeCli {
             cmd_parts.push(format!("{}={}", key, value));
         }
 
-        cmd_parts.extend([
-            "docker".to_string(),
-            "compose".to_string(),
-            "--project-name".to_string(),
-            command.project_name.clone(),
-        ]);
+        cmd_parts.extend(["docker".to_string(), "compose".to_string()]);
+
+        if let Some(project_directory) = &self.project_directory {
+            cmd_parts.push("--project-directory".to_string());
+            cmd_parts.push(project_directory.clone());
+        }
+
+        cmd_parts.push("--project-name".to_string());
+        cmd_parts.push(command.project_name.clone());
 
         for file in &self.compose_files_in_container {
             cmd_parts.push("-f".to_string());
@@ -87,13 +90,18 @@ impl ComposeInterface for ContainerisedComposeCli {
     }
 
     async fn down(&self, command: DownCommand) -> Result<()> {
-        let mut cmd = vec![
-            "docker".to_string(),
-            "compose".to_string(),
+        let mut cmd = vec!["docker".to_string(), "compose".to_string()];
+
+        if let Some(project_directory) = &self.project_directory {
+            cmd.push("--project-directory".to_string());
+            cmd.push(project_directory.clone());
+        }
+
+        cmd.extend([
             "--project-name".to_string(),
             command.project_name.clone(),
             "down".to_string(),
-        ];
+        ]);
 
         if command.volumes {
             cmd.push("--volumes".to_string());