Merge branch 'main' into v1

* main:
  feat: prepare modules for the new API (#2610)

docs/features/common_functional_options.md

@@ -22,7 +22,7 @@ Using the `WithImageSubstitutors` options, you could define your own substitutio
 If you need to either pass additional environment variables to a container or override them, you can use `testcontainers.WithEnv` for example:
 
 ```golang
-postgres, err = postgresModule.RunContainer(ctx, testcontainers.WithEnv(map[string]string{"POSTGRES_INITDB_ARGS": "--no-sync"}))
+postgres, err = postgresModule.Run(ctx, "postgres:15-alpine", testcontainers.WithEnv(map[string]string{"POSTGRES_INITDB_ARGS": "--no-sync"}))
 ```
 
 #### WithHostPortAccess
@@ -32,7 +32,7 @@ postgres, err = postgresModule.RunContainer(ctx, testcontainers.WithEnv(map[stri
 If you need to access a port that is already running in the host, you can use `testcontainers.WithHostPortAccess` for example:
 
 ```golang
-postgres, err = postgresModule.RunContainer(ctx, testcontainers.WithHostPortAccess(8080))
+postgres, err = postgresModule.Run(ctx, "postgres:15-alpine", testcontainers.WithHostPortAccess(8080))
 ```
 
 To understand more about this feature, please read the [Exposing host ports to the container](/features/networking/#exposing-host-ports-to-the-container) documentation.
@@ -70,7 +70,7 @@ useful context instead of appearing out of band.
 ```golang
 func TestHandler(t *testing.T) {
     logger := TestLogger(t)
-    _, err := postgresModule.RunContainer(ctx, testcontainers.WithLogger(logger))
+    _, err := postgresModule.Run(ctx, "postgres:15-alpine", testcontainers.WithLogger(logger))
     require.NoError(t, err)
     // Do something with container.
 }
@@ -145,14 +145,14 @@ If you need an advanced configuration for the container, you can leverage the fo
 
 Please read the [Create containers: Advanced Settings](/features/creating_container.md#advanced-settings) documentation for more information.
 
-#### Customising the ContainerRequest
+#### Customising the Container Request
 
-This option will merge the customized request into the module's own `ContainerRequest`.
+This option will merge the customized request into the module's own `testcontainers.Request`.
 
 ```go
-container, err := RunContainer(ctx,
+ctr, err := Run(ctx, "postgres:13-alpine",
     /* Other module options */
-    testcontainers.CustomizeRequest(container.Request{
+    testcontainers.CustomizeRequest(testcontainers.Request{
         Cmd: []string{"-c", "log_statement=all"},
     }),
 )

docs/modules/artemis.md

@@ -26,13 +26,14 @@ go get github.com/testcontainers/testcontainers-go/modules/artemis
 
 ## Module reference
 
-The Artemis module exposes one entrypoint function to create the Artemis container, and this function receives two parameters:
+The Artemis module exposes one entrypoint function to create the Artemis container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.RequestCustomizer) (*Container, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
+- `string`, the Docker image to use.
 - `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 ### Container Options
@@ -41,8 +42,8 @@ When starting the Artemis container, you can pass options in a variadic way to c
 
 #### Image
 
-If you need to set a different Artemis Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for Artemis. E.g. `testcontainers.WithImage("docker.io/apache/activemq-artemis:2.30.0")`.
+If you need to set a different Artemis Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "docker.io/apache/activemq-artemis:2.30.0")`.
 
 {% include "../features/common_functional_options.md" %}
 

docs/modules/azurite.md

@@ -22,14 +22,15 @@ go get github.com/testcontainers/testcontainers-go/modules/azurite
 
 ## Module reference
 
-The Azurite module exposes one entrypoint function to create the Azurite container, and this function receives two parameters:
+The Azurite module exposes one entrypoint function to create the Azurite container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*AzuriteContainer, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
-- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+- `string`, the Docker image to use.
+- `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 ### Default Credentials
 
@@ -45,8 +46,8 @@ When starting the Azurite container, you can pass options in a variadic way to c
 
 #### Image
 
-If you need to set a different Azurite Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for Azurite. E.g. `testcontainers.WithImage("mcr.microsoft.com/azure-storage/azurite:3.28.0")`.
+If you need to set a different Azurite Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "mcr.microsoft.com/azure-storage/azurite:3.28.0")`.
 
 {% include "../features/common_functional_options.md" %}
 

docs/modules/cassandra.md

@@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/cassandra
 
 ## Module reference
 
-The Cassandra module exposes one entrypoint function to create the Cassandra container, and this function receives two parameters:
+The Cassandra module exposes one entrypoint function to create the Cassandra container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.RequestCustomizer) (*CassandraContainer, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
+- `string`, the Docker image to use.
 - `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 ### Container Options
@@ -37,8 +38,8 @@ When starting the Cassandra container, you can pass options in a variadic way to
 
 #### Image
 
-If you need to set a different Cassandra Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for Cassandra. E.g. `testcontainers.WithImage("cassandra:4.1.3")`.
+If you need to set a different Cassandra Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "cassandra:4.1.3")`.
 
 {% include "../features/common_functional_options.md" %}
 

docs/modules/chroma.md

@@ -27,13 +27,14 @@ go get github.com/testcontainers/testcontainers-go/modules/chroma
 
 ## Module reference
 
-The Chroma module exposes one entrypoint function to create the Chroma container, and this function receives two parameters:
+The Chroma module exposes one entrypoint function to create the Chroma container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.RequestCustomizer) (*ChromaContainer, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
+- `string`, the Docker image to use.
 - `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 ### Container Options
@@ -42,8 +43,8 @@ When starting the Chroma container, you can pass options in a variadic way to co
 
 #### Image
 
-If you need to set a different Chroma Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for Chroma. E.g. `testcontainers.WithImage("chromadb/chroma:0.4.24")`.
+If you need to set a different Chroma Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "chromadb/chroma:0.4.24")`.
 
 {% include "../features/common_functional_options.md" %}
 

docs/modules/clickhouse.md

@@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/clickhouse
 
 ## Module reference
 
-The ClickHouse module exposes one entrypoint function to create the ClickHouse container, and this function receives two parameters:
+The ClickHouse module exposes one entrypoint function to create the ClickHouse container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.RequestCustomizer) (*ClickHouseContainer, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
+- `string`, the Docker image to use.
 - `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 ### Container Ports
@@ -45,8 +46,8 @@ When starting the ClickHouse container, you can pass options in a variadic way t
 
 #### Image
 
-If you need to set a different ClickHouse Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for ClickHouse. E.g. `testcontainers.WithImage("clickhouse/clickhouse-server:23.3.8.21-alpine")`.
+If you need to set a different ClickHouse Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "clickhouse/clickhouse-server:23.3.8.21-alpine")`.
 
 {% include "../features/common_functional_options.md" %}
 

docs/modules/cockroachdb.md

@@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/cockroachdb
 
 ## Module reference
 
-The CockroachDB module exposes one entrypoint function to create the CockroachDB container, and this function receives two parameters:
+The CockroachDB module exposes one entrypoint function to create the CockroachDB container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.RequestCustomizer) (*CockroachDBContainer, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
+- `string`, the Docker image to use.
 - `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 !!!warning
@@ -40,8 +41,8 @@ When starting the CockroachDB container, you can pass options in a variadic way
 
 #### Image
 
-If you need to set a different CockroachDB Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for CockroachDB. E.g. `testcontainers.WithImage("cockroachdb/cockroach:latest-v23.1")`.
+If you need to set a different CockroachDB Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "cockroachdb/cockroach:latest-v23.1")`.
 
 {% include "../features/common_functional_options.md" %}
 

docs/modules/consul.md

@@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/consul
 
 ## Module reference
 
-The Consul module exposes one entrypoint function to create the Consul container, and this function receives two parameters:
+The Consul module exposes one entrypoint function to create the Consul container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.RequestCustomizer) (*ConsulContainer, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
+- `string`, the Docker image to use.
 - `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 ### Container Options
@@ -37,8 +38,8 @@ When starting the Consul container, you can pass options in a variadic way to co
 
 #### Image
 
-If you need to set a different Consul Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for Consul. E.g. `testcontainers.WithImage("docker.io/hashicorp/consul:1.15")`.
+If you need to set a different Consul Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "docker.io/hashicorp/consul:1.15")`.
 
 {% include "../features/common_functional_options.md" %}
 

docs/modules/couchbase.md

@@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/couchbase
 
 ## Module Reference
 
-The Couchbase module exposes one entrypoint function to create the Couchbase container, and this function receives two parameters:
+The Couchbase module exposes one entrypoint function to create the Couchbase container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.RequestCustomizer) (*CouchbaseContainer, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
+- `string`, the Docker image to use.
 - `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 Once the container is started, it will perform the following operations, **in this particular order**:
@@ -64,14 +65,8 @@ When starting the Couchbase container, you can pass options in a variadic way to
 
 #### Image
 
-If you need to set a different Couchbase Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for Couchbase. E.g. `testcontainers.WithImage("docker.io/couchbase:6.5.1")`.
-
-By default, the container will use the following Docker image:
-
-<!--codeinclude-->
-[Default Docker image](../../modules/couchbase/couchbase.go) inside_block:defaultImage
-<!--/codeinclude-->
+If you need to set a different Couchbase Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "docker.io/couchbase:6.5.1")`.
 
 You can find the Docker images that are currently tested in this module, for the Enterprise and Community editions, in the following list:
 
@@ -84,7 +79,7 @@ You can find the Docker images that are currently tested in this module, for the
 #### Credentials
 
 If you need to change the default credentials for the admin user, you can use `WithAdminCredentials(user, password)` with a valid username and password.
-When the password has less than 6 characters, the container won't be created and the `RunContainer` function will throw an error.
+When the password has less than 6 characters, the container won't be created and the `New` function will throw an error.
 
 !!!info
 	In the case this optional function is not called, the default username is `Administrator` and the default password is `password`.

docs/modules/dolt.md

@@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/dolt
 
 ## Module reference
 
-The Dolt module exposes one entrypoint function to create the Dolt container, and this function receives two parameters:
+The Dolt module exposes one entrypoint function to create the Dolt container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.RequestCustomizer) (*DoltContainer, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
+- `string`, the Docker image to use.
 - `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 ### Container Options
@@ -37,8 +38,8 @@ When starting the Dolt container, you can pass options in a variadic way to conf
 
 #### Image
 
-If you need to set a different Dolt Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for Dolt. E.g. `testcontainers.WithImage("dolthub/dolt-sql-server:1.32.4")`.
+If you need to set a different Dolt Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "dolthub/dolt-sql-server:1.32.4")`.
 
 {% include "../features/common_functional_options.md" %}
 

docs/modules/elasticsearch.md

@@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/elasticsearch
 
 ## Module reference
 
-The Elasticsearch module exposes one entrypoint function to create the Elasticsearch container, and this function receives two parameters:
+The Elasticsearch module exposes one entrypoint function to create the Elasticsearch container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.RequestCustomizer) (*ElasticsearchContainer, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
+- `string`, the Docker image to use.
 - `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 ### Container Options
@@ -37,8 +38,8 @@ When starting the Elasticsearch container, you can pass options in a variadic wa
 
 #### Image
 
-If you need to set a different Elasticsearch Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for Elasticsearch. E.g. `testcontainers.WithImage("docker.elastic.co/elasticsearch/elasticsearch:8.0.0")`.
+If you need to set a different Elasticsearch Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "docker.elastic.co/elasticsearch/elasticsearch:8.0.0")`.
 
 {% include "../features/common_functional_options.md" %}
 
@@ -66,7 +67,7 @@ The Elasticsearch container exposes its settings in order to configure the clien
 [Create an HTTP client](../../modules/elasticsearch/elasticsearch_test.go) inside_block:createHTTPClient
 <!--/codeinclude-->
 
-The `esContainer` instance is obtained from the `elasticsearch.RunContainer` function.
+The `esContainer` instance is obtained from the `elasticsearch.New` function.
 
 In the case you configured the Elasticsearch container to set up a password, you'll need to add the `Authorization` header to the request. You can use the `SetBasicAuth` method from the HTTP request to generate the header value.
 

docs/modules/gcloud.md

@@ -97,8 +97,8 @@ When starting any of the GCloud containers, you can pass options in a variadic w
 
 #### Image
 
-If you need to set a different GCloud Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for GCloud. E.g. `testcontainers.WithImage("gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators")`.
+If you need to set a different GCloud Docker image, you can set a valid Docker image as the second argument in the `RunXXX` function (`RunBigQuery, RunDatastore`, ...).
+E.g. `RunXXX(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators")`.
 
 {% include "../features/common_functional_options.md" %}
 

docs/modules/inbucket.md

@@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/inbucket
 
 ## Module reference
 
-The Inbucket module exposes one entrypoint function to create the Inbucket container, and this function receives two parameters:
+The Inbucket module exposes one entrypoint function to create the Inbucket container, and this function receives three parameters:
 
 ```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.RequestCustomizer) (*InbucketContainer, error)
+func Run(ctx context.Context, img string, opts ...testcontainers.RequestCustomizer) (*Container, error)
 ```
 
 - `context.Context`, the Go context.
+- `string`, the Docker image to use.
 - `testcontainers.RequestCustomizer`, a variadic argument for passing options.
 
 ### Container Options
@@ -37,8 +38,8 @@ When starting the Inbucket container, you can pass options in a variadic way to
 
 #### Image
 
-If you need to set a different Inbucket Docker image, you can use `testcontainers.WithImage` with a valid Docker image
-for Inbucket. E.g. `testcontainers.WithImage("inbucket/inbucket:sha-2d409bb")`.
+If you need to set a different Inbucket Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "inbucket/inbucket:sha-2d409bb")`.
 
 {% include "../features/common_functional_options.md" %}