docs: improve docker-compose documentation

Updates docker_compose.md with:
- Async-only requirement prominently noted at top
- Minimal example section (like Java docs)
- Installation/requirements section
- Better service access examples showing full RawContainer API
- Lifecycle section with explicit down() vs auto-drop
- Build and pull configuration examples
- Clearer structure aligned with Java testcontainers docs

Key additions:
- Minimal redis example at the start
- Note that compose is tokio-only (no blocking support yet)
- Examples showing service() returns full container with exec/logs
- Explicit down() consuming self explained

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: DDtKey

docs/features/docker_compose.md

@@ -2,6 +2,49 @@
 
 Testcontainers for Rust supports running multi-container applications defined in Docker Compose files. This is useful when your tests need multiple interconnected services or when you want to reuse existing docker-compose configurations from your development environment.
 
+> **Note:** Docker Compose support is currently only available for async runtimes (tokio). Synchronous/blocking support may be added in a future release.
+
+## Installation
+
+Add the `docker-compose` feature to your dependencies:
+
+```toml
+[dev-dependencies]
+testcontainers = { version = "0.25", features = ["docker-compose"] }
+```
+
+## Minimal Example
+
+```rust
+use testcontainers::compose::DockerCompose;
+
+#[tokio::test]
+async fn test_redis() -> Result<(), Box<dyn std::error::Error>> {
+    let mut compose = DockerCompose::with_local_client(&["tests/docker-compose.yml"]);
+    compose.up().await?;
+
+    let redis = compose.service("redis").expect("redis service");
+    let port = redis.get_host_port_ipv4(6379).await?;
+
+    // Use redis at localhost:{port}
+    let client = redis::Client::open(format!("redis://localhost:{}", port))?;
+    let mut con = client.get_connection()?;
+    redis::cmd("PING").query::<String>(&mut con)?;
+
+    Ok(())
+}
+```
+
+With `docker-compose.yml`:
+
+```yaml
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379"
+```
+
 ## Basic Usage
 
 Use [`DockerCompose`](https://docs.rs/testcontainers/latest/testcontainers/compose/struct.DockerCompose.html) to start services defined in your compose files:
@@ -15,10 +58,11 @@ async fn test_with_compose() -> Result<(), Box<dyn std::error::Error>> {
 
     compose.up().await?;
 
-    // Services are now running and accessible
-    let web_port = compose.get_host_port_ipv4("web", 8080).await?;
-    let response = reqwest::get(format!("http://localhost:{}", web_port)).await?;
+    // Access service by name
+    let web = compose.service("web").expect("web service");
+    let port = web.get_host_port_ipv4(8080).await?;
 
+    let response = reqwest::get(format!("http://localhost:{}", port)).await?;
     assert!(response.status().is_success());
 
     Ok(())
@@ -28,16 +72,19 @@ async fn test_with_compose() -> Result<(), Box<dyn std::error::Error>> {
 
 ## Accessing Services
 
-After calling `up()`, you can access individual services by name:
+After calling `up()`, you can access individual services by name. The `service()` method returns a reference to the container, providing full access to the container API:
 
-### Get Service Container ID
+### Get Service Container
 
 ```rust
 compose.up().await?;
 
-if let Some(container_id) = compose.service("redis") {
-    println!("Redis container ID: {}", container_id);
-}
+let redis = compose.service("redis").expect("redis service exists");
+
+// Full container API available
+let port = redis.get_host_port_ipv4(6379).await?;
+let logs = redis.stdout(true);
+redis.exec(ExecCommand::new(["redis-cli", "PING"])).await?;
 ```
 
 ### List All Services
@@ -50,19 +97,29 @@ for service_name in compose.services() {
 }
 ```
 
-### Get Mapped Ports
+### Access Ports, Logs, and Execute Commands
 
-Access the host ports mapped to your services:
+Services return a container reference with the full API:
 
 ```rust
 compose.up().await?;
 
-// IPv4
-let redis_port = compose.get_host_port_ipv4("redis", 6379).await?;
-let client = redis::Client::open(format!("redis://localhost:{}", redis_port))?;
+let redis = compose.service("redis").expect("redis service");
+
+// Get mapped ports
+let port = redis.get_host_port_ipv4(6379).await?;
+let ipv6_port = redis.get_host_port_ipv6(6379).await?;
+
+// Stream logs
+let stdout = redis.stdout(true);
+let stderr = redis.stderr(false);
 
-// IPv6
-let ipv6_port = compose.get_host_port_ipv6("web", 8080).await?;
+// Execute commands
+let result = redis.exec(ExecCommand::new(["redis-cli", "PING"])).await?;
+
+// Get container info
+let container_id = redis.id();
+let host = redis.get_host().await?;
 ```
 
 ## Client Modes
@@ -123,9 +180,26 @@ let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"])
 compose.up().await?;
 ```
 
-### Cleanup Options
+### Lifecycle and Cleanup
+
+You can either let the stack automatically clean up on drop, or explicitly tear it down:
+
+```rust
+// Option 1: Automatic cleanup (default behavior)
+{
+    let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"]);
+    compose.up().await?;
+    // Use services...
+} // Automatically cleaned up here
+
+// Option 2: Explicit teardown
+let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"]);
+compose.up().await?;
+// Use services...
+compose.down().await?; // Explicit cleanup, consumes compose
+```
 
-Control what gets removed when the compose stack is dropped:
+Control what gets removed during cleanup:
 
 ```rust
 let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"]);
@@ -139,6 +213,18 @@ compose.with_remove_images(false);
 compose.up().await?;
 ```
 
+### Build and Pull Options
+
+Configure whether to build or pull images before starting:
+
+```rust
+let mut compose = DockerCompose::with_local_client(&["docker-compose.yml"])
+    .with_build(true)   // Build images defined in compose file
+    .with_pull(true);   // Pull latest images before starting
+
+compose.up().await?;
+```
+
 ## Multiple Compose Files
 
 You can use multiple compose files (e.g., base + override):
@@ -298,24 +384,34 @@ If `up()` returns an error:
 
 ## Limitations
 
-### Wait Strategies
+### Synchronous API
 
-Custom per-service wait strategies (beyond compose's `--wait`) are not yet implemented. For now, use compose file healthchecks or add explicit waits:
-
-```rust
-compose.up().await?;
-tokio::time::sleep(std::time::Duration::from_secs(2)).await;
-```
+Docker Compose support is currently only available for async runtimes (tokio). If you need synchronous/blocking support, please open an issue on GitHub.
 
 ### Containerised Client Environment Variables
 
 Environment variable support for the containerised client is not yet implemented. Use the local client if you need env vars.
 
-## Feature Flag
+## Requirements
 
-Docker Compose support requires the `docker-compose` feature:
+Docker Compose support requires:
 
-```toml
-[dependencies]
-testcontainers = { version = "0.25", features = ["docker-compose"] }
-```
+1. **Feature flag:**
+   ```toml
+   [dev-dependencies]
+   testcontainers = { version = "0.25", features = ["docker-compose"] }
+   ```
+
+2. **Async runtime:** Currently only tokio is supported
+   ```toml
+   [dev-dependencies]
+   tokio = { version = "1", features = ["macros"] }
+   ```
+
+3. **Local Docker Compose CLI** (for local client mode):
+   ```bash
+   docker compose version
+   # Docker Compose version v2.20.0 or later
+   ```
+
+   Or use containerised client mode (no local installation needed)

testcontainers/src/compose/mod.rs

@@ -3,8 +3,7 @@ use std::{collections::HashMap, path::Path, sync::Arc};
 use crate::{
     compose::client::ComposeInterface,
     core::{
-        async_container::raw::RawContainer, async_drop, client::Client, wait::WaitStrategy,
-        WaitFor,
+        async_container::raw::RawContainer, async_drop, client::Client, wait::WaitStrategy, WaitFor,
     },
 };
 
@@ -175,7 +174,7 @@ impl DockerCompose {
         self
     }
 
-    /// Remove volumes when dropping the docker compose or not
+    /// Remove volumes when dropping the docker compose or not (removed by default)
     pub fn with_remove_volumes(&mut self, remove_volumes: bool) -> &mut Self {
         self.remove_volumes = remove_volumes;
         self
@@ -241,20 +240,6 @@ mod tests {
 
     use super::*;
 
-    // #[tokio::test]
-    // async fn test_containerised_docker_compose() {
-    //     let path_to_compose = PathBuf::from(format!(
-    //         "{}/tests/test-compose.yml",
-    //         env!("CARGO_MANIFEST_DIR")
-    //     ));
-    //     let docker_compose =
-    //         DockerCompose::with_containerised_client(&[path_to_compose.as_path()]).await;
-    //     docker_compose.up().await;
-    //     tokio::time::sleep(std::time::Duration::from_secs(1)).await;
-    //     let res = reqwest::get("http://localhost:8081/").await.unwrap();
-    //     assert!(res.status().is_success());
-    // }
-
     #[tokio::test]
     async fn test_local_docker_compose() -> anyhow::Result<()> {
         let _ = pretty_env_logger::try_init();
@@ -265,13 +250,18 @@ mod tests {
         ));
 
         let mut compose = DockerCompose::with_local_client(&[path_to_compose.as_path()])
-            .with_wait_for_service("redis", WaitFor::message_on_stdout("Ready to accept connections"));
+            .with_wait_for_service(
+                "redis",
+                WaitFor::message_on_stdout("Ready to accept connections"),
+            );
 
         compose.up().await?;
 
         println!("Services: {:?}", compose.services());
 
-        let _redis = compose.service("redis").expect("Redis service should exist");
+        let _redis = compose
+            .service("redis")
+            .expect("Redis service should exist");
         let web = compose.service("web1").expect("Web service should exist");
 
         let web_port = web.get_host_port_ipv4(80).await?;