Merge branch 'main' into fix-reuse-stopped-container

* main:
  feat(postgres): add WithOrderedInitScripts for Postgres testcontainers (testcontainers#3121)
  feat(redis): add TLS support (testcontainers#3115)
  feat: add Docker Model Runner module (testcontainers#3106)
  feat: add toxiproxy module (testcontainers#3092)
  chore(ci): run core tests on Testcontainers Cloud (testcontainers#3117)
  deps(aerospike): replace core module in go.mod (testcontainers#3116)

Author: mdelapenya

.github/dependabot.yml

@@ -14,7 +14,6 @@ updates:
       directories:
         - /
         - /examples/nginx
-        - /examples/toxiproxy
         - /modulegen
         - /modules/aerospike
         - /modules/arangodb
@@ -30,6 +29,7 @@ updates:
         - /modules/couchbase
         - /modules/databend
         - /modules/dind
+        - /modules/dockermodelrunner
         - /modules/dolt
         - /modules/dynamodb
         - /modules/elasticsearch
@@ -67,6 +67,7 @@ updates:
         - /modules/scylladb
         - /modules/socat
         - /modules/surrealdb
+        - /modules/toxiproxy
         - /modules/valkey
         - /modules/vault
         - /modules/vearch

.github/workflows/ci-test-go.yml

@@ -18,6 +18,11 @@ on:
         type: string
         default: "."
         description: "The directory where the Go project is located."
+      testcontainers-cloud:
+        required: false
+        type: boolean
+        default: false
+        description: "Run the tests on Testcontainers Cloud"
       rootless-docker:
         required: false
         type: boolean
@@ -81,6 +86,13 @@ jobs:
             echo "No dependencies script found at $SCRIPT_PATH - skipping installation"
           fi
 
+      # Setup Testcontainers Cloud Client right before your Testcontainers tests
+      - name: Setup Testcontainers Cloud Client
+        if: ${{ inputs.testcontainers-cloud }}
+        uses: atomicjar/testcontainers-cloud-setup-action@c335bdbb570ec7c48f72c7d450c077f0a002293e # v1.3
+        with:
+          token: ${{ secrets.TCC_TOKEN }}
+
       - name: go test
         working-directory: ./${{ inputs.project-directory }}
         timeout-minutes: 30
@@ -90,6 +102,13 @@ jobs:
         run: |
             ./scripts/check_environment.sh
 
+      # (Optionally) When you don't need Testcontainers Cloud anymore, you could terminate sessions eagerly
+      - name: Terminate Testcontainers Cloud Client active sessions
+        if: ${{ inputs.testcontainers-cloud }}
+        uses: atomicjar/testcontainers-cloud-setup-action@c335bdbb570ec7c48f72c7d450c077f0a002293e # v1.3
+        with:
+          action: terminate
+
       - name: Test Summary
         uses: test-summary/action@31493c76ec9e7aa675f1585d3ed6f1da69269a86 # v2.4
         with:

.github/workflows/ci.yml

@@ -71,10 +71,31 @@ jobs:
       go-version: ${{ matrix.go-version }}
       platforms: ${{ matrix.module == 'modulegen' && '["ubuntu-latest", "macos-latest", "windows-latest"]' || '["ubuntu-latest"]' }}
       project-directory: "${{ matrix.module }}"
+      testcontainers-cloud: false
       rootless-docker: false
       ryuk-disabled: false
     secrets: inherit
 
+  # The job below is a copy of the job above, but using Docker Cloud.
+  test-testcontainers-cloud:
+    # the core module is identified by the empty string (the root path)
+    if: ${{ contains(fromJSON(needs.detect-modules.outputs.modules), '') }}
+    needs:
+      - detect-modules
+      - lint
+    name: "Test using Testcontainers Cloud"
+    strategy:
+      matrix:
+        go-version: [1.23.x, 1.24.x]
+    uses: ./.github/workflows/ci-test-go.yml
+    with:
+      go-version: ${{ matrix.go-version }}
+      platforms: '["ubuntu-latest"]'
+      project-directory: "."
+      testcontainers-cloud: true
+      rootless-docker: false
+      ryuk-disabled: false
+
   # The job below is a copy of the job above, but with ryuk disabled.
   # It's executed in the first stage to avoid concurrency issues.
   test-reaper-off:
@@ -92,6 +113,7 @@ jobs:
       go-version: ${{ matrix.go-version }}
       platforms: '["ubuntu-latest"]'
       project-directory: "."
+      testcontainers-cloud: false
       rootless-docker: false
       ryuk-disabled: true
 
@@ -112,6 +134,7 @@ jobs:
       go-version: ${{ matrix.go-version }}
       platforms: '["ubuntu-latest"]'
       project-directory: "."
+      testcontainers-cloud: false
       rootless-docker: true
       ryuk-disabled: false
 

.vscode/.testcontainers-go.code-workspace

@@ -10,8 +10,8 @@
             "path": "../examples/nginx"
         },
         {
-            "name": "example / toxiproxy",
-            "path": "../examples/toxiproxy"
+            "name": "module / aerospike",
+            "path": "../modules/aerospike"
         },
         {
             "name": "module / arangodb",
@@ -65,6 +65,10 @@
             "name": "module / dind",
             "path": "../modules/dind"
         },
+        {
+            "name": "module / dockermodelrunner",
+            "path": "../modules/dockermodelrunner"
+        },
         {
             "name": "module / dolt",
             "path": "../modules/dolt"
@@ -213,6 +217,10 @@
             "name": "module / surrealdb",
             "path": "../modules/surrealdb"
         },
+        {
+            "name": "module / toxiproxy",
+            "path": "../modules/toxiproxy"
+        },
         {
             "name": "module / valkey",
             "path": "../modules/valkey"

docs/examples/toxiproxy.md

@@ -0,0 +1,110 @@
+# Docker Model Runner
+
+Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+## Introduction
+
+The Testcontainers module for DockerModelRunner.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the DockerModelRunner module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/dockermodelrunner
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a DockerModelRunner container](../../modules/dockermodelrunner/examples_test.go) inside_block:runWithModel
+<!--/codeinclude-->
+
+## Module Reference
+
+### Run function
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The Docker Model Runner module exposes two entrypoint functions to create the Docker Model Runner container:
+
+#### Run
+
+This function receives two parameters:
+
+```golang
+func Run(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*Container, error)
+```
+
+- `context.Context`, the Go context.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+!!! info
+    This function will use the default `socat` image under the hood. Please refer to the [socat module](../socat.md) for more information.
+
+### Container Options
+
+When starting the Docker Model Runner container, you can pass options in a variadic way to configure it.
+
+#### Image
+
+Use the second argument in the `Run` function to set a valid Docker image.
+In example: `Run(context.Background(), "alpine/socat:1.8.0.1")`.
+
+{% include "../features/common_functional_options.md" %}
+
+#### WithModel
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+Use the `WithModel` option to set the model to pull when the container is started. Please be aware, that only Models as OCI Artifacts are compatible with Docker Model Runner.
+
+```golang
+dockermodelrunner.WithModel("ai/llama3.2:latest")
+```
+
+!!! warning
+    Multiple calls to this function overrides the previous value.
+
+ You can find a curated collection of cutting-edge AI models as OCI Artifacts, from lightweight on-device models to high-performance LLMs on [Docker Hub](https://hub.docker.com/u/ai).
+
+### Container Methods
+
+The Docker Model Runner container exposes the following methods:
+
+#### PullModel
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+Use the `PullModel` method to pull a model from the Docker Model Runner.
+
+<!--codeinclude-->
+[Pulling a model at runtime](../../modules/dockermodelrunner/examples_test.go) inside_block:runPullModel
+<!--/codeinclude-->
+
+!!! info
+     You can find a curated collection of cutting-edge AI models as OCI Artifacts, from lightweight on-device models to high-performance LLMs on [Docker Hub](https://hub.docker.com/u/ai).
+
+#### InspectModel
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+Use the `InspectModel` method to inspect a model from the Docker Model Runner, by providing the model namespace and name.
+
+<!--codeinclude-->
+[Getting a model at runtime](../../modules/dockermodelrunner/examples_test.go) inside_block:runInspectModel
+<!--/codeinclude-->
+
+The namespace and name of the model is in the format of `<name>:<tag>`, which defines Models as OCI Artifacts in Docker Hub, therefore the namespace is the organization and the name is the repository.
+
+E.g. `ai/smollm2:360M-Q4_K_M`. See [Models as OCI Artifacts](https://hub.docker.com/u/ai) for more information.
+
+#### ListModels
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+Use the `ListModels` method to list all models that are already pulled locally, using the Docker Model Runner format.
+
+<!--codeinclude-->
+[Listing all models](../../modules/dockermodelrunner/examples_test.go) inside_block:runListModels
+<!--/codeinclude-->

docs/modules/dockermodelrunner.md

@@ -70,6 +70,14 @@ An example of a `*.sh` script that creates a user and database is shown below:
 [Init script content](../../modules/postgres/testdata/init-user-db.sh)
 <!--/codeinclude-->
 
+#### Ordered Init Scripts
+
+If you would like to run the init scripts in a specific order, you can use the `WithOrderedInitScripts` function, which copies the given scripts in the order they are provided to the container, prefixed with the order number so that Postgres executes them in the correct order.
+
+<!--codeinclude-->
+[Ordered init scripts](../../modules/postgres/postgres_test.go) inside_block:orderedInitScripts
+<!--/codeinclude-->
+
 #### Database configuration
 
 In the case you have a custom config file for Postgres, it's possible to copy that file into the container before it's started, using the `WithConfigFile(cfgPath string)` function.

docs/modules/postgres.md

@@ -62,7 +62,7 @@ By default Redis saves snapshots of the dataset on disk, in a binary file called
 
 #### Log Level
 
-By default Redis saves snapshots of the dataset on disk, in a binary file called dump.rdb. You can configure Redis to have it save the dataset every N seconds if there are at least M changes in the dataset. E.g. `WithLogLevel(LogLevelDebug)`.
+By default Redis produces a log message to the standard Redis log, the format accepts printf-alike specifiers, while level is a string describing the log level to use when emitting the log, and must be one of the following: `LogLevelDebug`, `LogLevelVerbose`, `LogLevelNotice`, `LogLevelWarning`. E.g. `WithLogLevel(LogLevelDebug)`. If the specified log level is invalid, verbose is used by default.
 
 !!!tip
     Please check [Redis docs on logging](https://redis.io/docs/reference/modules/modules-api-ref/#redismodule_log) for more information.
@@ -71,24 +71,33 @@ By default Redis saves snapshots of the dataset on disk, in a binary file called
 
 In the case you have a custom config file for Redis, it's possible to copy that file into the container before it's started. E.g. `WithConfigFile(filepath.Join("testdata", "redis7.conf"))`.
 
+#### WithTLS
+
+In the case you want to enable TLS for the Redis container, you can use the `WithTLS()` option. This options enables TLS on the `6379/tcp` port and uses a secure URL (e.g. `rediss://host:port`).
+
+!!!info
+    In case you want to use Non-mutual TLS (i.e. client authentication is not required), you can customize the CMD arguments by using the `WithCmdArgs` option. E.g. `WithCmdArgs("--tls-auth-clients no")`.
+
+The module automatically generates three certificates, a CA certificate, a client certificate and a Redis certificate. Please use the `TLSConfig()` container method to get the TLS configuration and use it to configure the Redis client. See more details in the [TLSConfig](#tlsconfig) section.
+
 ### Container Methods
 
 #### ConnectionString
 
-This method returns the connection string to connect to the Redis container, using the default `6379` port.
+This method returns the connection string to connect to the Redis container, using the default `6379` port, and `redis` schema.
 
 <!--codeinclude-->
 [Get connection string](../../modules/redis/redis_test.go) inside_block:connectionString
 <!--/codeinclude-->
 
-### Redis variants
+If the container is started with TLS enabled, the connection string is `rediss://host:port`, using the `rediss` schema.
 
-It's possible to use the Redis container with Redis-Stack. You simply need to update the image name.
+#### TLSConfig
 
-<!--codeinclude-->
-[Image for Redis-Stack](../../modules/redis/redis_test.go) inside_block:redisStackImage
-<!--/codeinclude-->
+This method returns the TLS configuration for the Redis container, nil if TLS is not enabled.
 
 <!--codeinclude-->
-[Image for Redis-Stack Server](../../modules/redis/redis_test.go) inside_block:redisStackServerImage
+[Get TLS config](../../modules/redis/redis_test.go) inside_block:tlsConfig
 <!--/codeinclude-->
+
+In the above example, the options are used to configure a Redis client with TLS enabled.

docs/modules/redis.md

@@ -47,8 +47,14 @@ When starting the Socat container, you can pass options in a variadic way to con
 
 #### Image
 
+The module exposes a default image:
+
+<!--codeinclude-->
+[Default Image](../../modules/socat/socat.go) inside_block:defaultImage
+<!--/codeinclude-->
+
 Use the second argument in the `Run` function to set a valid Docker image.
-In example: `Run(context.Background(), "alpine/socat:1.8.0.1")`.
+In example: `Run(context.Background(), DefaultImage)`.
 
 {% include "../features/common_functional_options.md" %}