Merge branch 'main' into prune-sshd-container

* main:
  docs: document disabling ryuk with properties (testcontainers#2603)
  fix: allow compose files and readers to be used together (testcontainers#2598)
  chore(deps): bump urllib3 from 2.2.1 to 2.2.2 (testcontainers#2590)
  docs: example for NATS cluster (testcontainers#2591)

docs/features/configuration.md

@@ -49,7 +49,7 @@ Please read more about customizing images in the [Image name substitution](image
 1. Ryuk must be started as a privileged container. For that, you can set the `TESTCONTAINERS_RYUK_CONTAINER_PRIVILEGED` **environment variable**, or the  `ryuk.container.privileged` **property** to `true`.
 1. If your environment already implements automatic cleanup of containers after the execution,
 but does not allow starting privileged containers, you can turn off the Ryuk container by setting
-`TESTCONTAINERS_RYUK_DISABLED` **environment variable** to `true`.
+`TESTCONTAINERS_RYUK_DISABLED` **environment variable** , or the  `ryuk.disabled` **property** to `true`.
 1. You can specify the connection timeout for Ryuk by setting the `TESTCONTAINERS_RYUK_CONNECTION_TIMEOUT` **environment variable**, or the `ryuk.connection.timeout` **property**. The default value is 1 minute.
 1. You can specify the reconnection timeout for Ryuk by setting the `TESTCONTAINERS_RYUK_RECONNECTION_TIMEOUT` **environment variable**, or the `ryuk.reconnection.timeout` **property**. The default value is 10 seconds.
 1. You can configure Ryuk to run in verbose mode by setting any of the `ryuk.verbose` **property** or the `TESTCONTAINERS_RYUK_VERBOSE` **environment variable**. The default value is `false`.

docs/modules/nats.md

@@ -44,22 +44,54 @@ for NATS. E.g. `testcontainers.WithImage("nats:2.9")`.
 
 #### Set username and password
 
+- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>
+
 If you need to set different credentials, you can use `WithUsername` and `WithPassword`
 options. By default, the username, the password are not set. To establish the connection with the NATS container:
 
 <!--codeinclude-->
 [Connect using the credentials](../../modules/nats/examples_test.go) inside_block:natsConnect
 <!--/codeinclude-->
 
+#### Cmd Arguments
+
+- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>
+
+It's possible to pass extra arguments to the NATS container using the `testcontainers.WithArgument` option. E.g. `nats.WithArgument("cluster_name", "c1")`.
+These arguments are passed to the NATS server when it starts, as part of the command line arguments of the entrypoint.
+
+!!! note
+    Arguments do not need to be prefixed with `--`: the NATS container will add them automatically.
+
+<!--codeinclude-->
+[Passing arguments](../../modules/nats/examples_test.go) inside_block:withArguments
+<!--/codeinclude-->
+
 ### Container Methods
 
 The NATS container exposes the following methods:
 
 #### ConnectionString
 
+- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>
+
 This method returns the connection string to connect to the NATS container, using the default `4222` port.
 It's possible to pass extra parameters to the connection string, in a variadic way.
 
 <!--codeinclude-->
 [Get connection string](../../modules/nats/nats_test.go) inside_block:connectionString
 <!--/codeinclude-->
+
+#### MustConnectionString
+
+- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>
+
+Exactly like `ConnectionString`, but it panics if an error occurs, returning just a string.
+
+## Examples
+
+### NATS Cluster
+
+<!--codeinclude-->
+[NATS Cluster](../../modules/nats/examples_test.go) inside_block:cluster
+<!--/codeinclude-->

modules/compose/compose_api.go

@@ -22,8 +22,8 @@ import (
 	"github.com/docker/docker/client"
 	"golang.org/x/sync/errgroup"
 
-	testcontainers "github.com/testcontainers/testcontainers-go"
-	wait "github.com/testcontainers/testcontainers-go/wait"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/wait"
 )
 
 type stackUpOptionFunc func(s *stackUpOptions)
@@ -149,15 +149,15 @@ func (r ComposeStackReaders) applyToComposeStack(o *composeStackOptions) error {
 		o.temporaryPaths[f[i]] = true
 	}
 
-	o.Paths = f
+	o.Paths = append(o.Paths, f...)
 
 	return nil
 }
 
 type ComposeStackFiles []string
 
 func (f ComposeStackFiles) applyToComposeStack(o *composeStackOptions) error {
-	o.Paths = f
+	o.Paths = append(o.Paths, f...)
 	return nil
 }
 

modules/compose/compose_api_test.go

@@ -472,6 +472,53 @@ services:
 	require.Nil(t, f, "File should be removed")
 }
 
+func TestDockerComposeAPIWithStackReaderAndComposeFile(t *testing.T) {
+	identifier := testNameHash(t.Name())
+	simple, _ := RenderComposeSimple(t)
+	composeContent := `version: '3.7'
+services:
+  api-postgres:
+    image: docker.io/postgres:14
+    environment:
+      POSTGRES_PASSWORD: s3cr3t
+`
+
+	compose, err := NewDockerComposeWith(
+		identifier,
+		WithStackFiles(simple),
+		WithStackReaders(strings.NewReader(composeContent)),
+	)
+	require.NoError(t, err, "NewDockerCompose()")
+
+	t.Cleanup(func() {
+		require.NoError(t, compose.Down(context.Background(), RemoveOrphans(true), RemoveImagesLocal), "compose.Down()")
+	})
+
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+
+	err = compose.
+		WithEnv(map[string]string{
+			"bar": "BAR",
+			"foo": "FOO",
+		}).
+		Up(ctx, Wait(true))
+	require.NoError(t, err, "compose.Up()")
+
+	serviceNames := compose.Services()
+
+	assert.Len(t, serviceNames, 2)
+	assert.Contains(t, serviceNames, "api-nginx")
+	assert.Contains(t, serviceNames, "api-postgres")
+
+	present := map[string]string{
+		"bar": "BAR",
+		"foo": "FOO",
+	}
+	absent := map[string]string{}
+	assertContainerEnvironmentVariables(t, identifier.String(), "api-nginx", present, absent)
+}
+
 func TestDockerComposeAPIWithEnvironment(t *testing.T) {
 	identifier := testNameHash(t.Name())
 

modules/nats/examples_test.go

@@ -4,11 +4,13 @@ import (
 	"context"
 	"fmt"
 	"log"
+	"time"
 
 	natsgo "github.com/nats-io/nats.go"
 
 	"github.com/testcontainers/testcontainers-go"
 	"github.com/testcontainers/testcontainers-go/modules/nats"
+	"github.com/testcontainers/testcontainers-go/network"
 )
 
 func ExampleRunContainer() {
@@ -74,3 +76,156 @@ func ExampleRunContainer_connectWithCredentials() {
 	// Output:
 	// true
 }
+
+func ExampleRunContainer_cluster() {
+	ctx := context.Background()
+
+	nwr, err := network.New(ctx)
+	if err != nil {
+		log.Fatalf("failed to create network: %s", err)
+	}
+
+	// withArguments {
+	natsContainer1, err := nats.RunContainer(ctx,
+		network.WithNetwork([]string{"nats1"}, nwr),
+		nats.WithArgument("name", "nats1"),
+		nats.WithArgument("cluster_name", "c1"),
+		nats.WithArgument("cluster", "nats://nats1:6222"),
+		nats.WithArgument("routes", "nats://nats1:6222,nats://nats2:6222,nats://nats3:6222"),
+		nats.WithArgument("http_port", "8222"),
+	)
+	// }
+	if err != nil {
+		log.Fatalf("failed to start container: %s", err)
+	}
+	// Clean up the container
+	defer func() {
+		if err := natsContainer1.Terminate(ctx); err != nil {
+			log.Fatalf("failed to terminate container: %s", err)
+		}
+	}()
+
+	natsContainer2, err := nats.RunContainer(ctx,
+		network.WithNetwork([]string{"nats2"}, nwr),
+		nats.WithArgument("name", "nats2"),
+		nats.WithArgument("cluster_name", "c1"),
+		nats.WithArgument("cluster", "nats://nats2:6222"),
+		nats.WithArgument("routes", "nats://nats1:6222,nats://nats2:6222,nats://nats3:6222"),
+		nats.WithArgument("http_port", "8222"),
+	)
+	if err != nil {
+		log.Fatalf("failed to start container: %s", err) // nolint:gocritic
+	}
+	// Clean up the container
+	defer func() {
+		if err := natsContainer2.Terminate(ctx); err != nil {
+			log.Fatalf("failed to terminate container: %s", err)
+		}
+	}()
+
+	natsContainer3, err := nats.RunContainer(ctx,
+		network.WithNetwork([]string{"nats3"}, nwr),
+		nats.WithArgument("name", "nats3"),
+		nats.WithArgument("cluster_name", "c1"),
+		nats.WithArgument("cluster", "nats://nats3:6222"),
+		nats.WithArgument("routes", "nats://nats1:6222,nats://nats2:6222,nats://nats3:6222"),
+		nats.WithArgument("http_port", "8222"),
+	)
+	if err != nil {
+		log.Fatalf("failed to start container: %s", err) // nolint:gocritic
+	}
+	defer func() {
+		if err := natsContainer3.Terminate(ctx); err != nil {
+			log.Fatalf("failed to terminate container: %s", err)
+		}
+	}()
+
+	// cluster URL
+	servers := natsContainer1.MustConnectionString(ctx) + "," + natsContainer2.MustConnectionString(ctx) + "," + natsContainer3.MustConnectionString(ctx)
+
+	nc, err := natsgo.Connect(servers, natsgo.MaxReconnects(5), natsgo.ReconnectWait(2*time.Second))
+	if err != nil {
+		log.Fatalf("connecting to nats container failed:\n\t%v\n", err) // nolint:gocritic
+	}
+
+	{
+		// Simple Publisher
+		err = nc.Publish("foo", []byte("Hello World"))
+		if err != nil {
+			log.Fatalf("failed to publish message: %s", err) // nolint:gocritic
+		}
+	}
+
+	{
+		// Channel subscriber
+		ch := make(chan *natsgo.Msg, 64)
+		sub, err := nc.ChanSubscribe("channel", ch)
+		if err != nil {
+			log.Fatalf("failed to subscribe to message: %s", err) // nolint:gocritic
+		}
+
+		// Request
+		err = nc.Publish("channel", []byte("Hello NATS Cluster!"))
+		if err != nil {
+			log.Fatalf("failed to publish message: %s", err) // nolint:gocritic
+		}
+
+		msg := <-ch
+		fmt.Println(string(msg.Data))
+
+		err = sub.Unsubscribe()
+		if err != nil {
+			log.Fatalf("failed to unsubscribe: %s", err) // nolint:gocritic
+		}
+
+		err = sub.Drain()
+		if err != nil {
+			log.Fatalf("failed to drain: %s", err) // nolint:gocritic
+		}
+	}
+
+	{
+		// Responding to a request message
+		sub, err := nc.Subscribe("request", func(m *natsgo.Msg) {
+			err1 := m.Respond([]byte("answer is 42"))
+			if err1 != nil {
+				log.Fatalf("failed to respond to message: %s", err1) // nolint:gocritic
+			}
+		})
+		if err != nil {
+			log.Fatalf("failed to subscribe to message: %s", err) // nolint:gocritic
+		}
+
+		// Request
+		msg, err := nc.Request("request", []byte("what is the answer?"), 1*time.Second)
+		if err != nil {
+			log.Fatalf("failed to send request: %s", err) // nolint:gocritic
+		}
+
+		fmt.Println(string(msg.Data))
+
+		err = sub.Unsubscribe()
+		if err != nil {
+			log.Fatalf("failed to unsubscribe: %s", err) // nolint:gocritic
+		}
+
+		err = sub.Drain()
+		if err != nil {
+			log.Fatalf("failed to drain: %s", err) // nolint:gocritic
+		}
+	}
+
+	// Drain connection (Preferred for responders)
+	// Close() not needed if this is called.
+	err = nc.Drain()
+	if err != nil {
+		log.Fatalf("failed to drain connection: %s", err) // nolint:gocritic
+	}
+
+	// Close connection
+	nc.Close()
+
+	// Output:
+	// Hello NATS Cluster!
+	// answer is 42
+}