Merge branch 'main' into host-port-binding-ip-family

* main: chore: print Docker Info labels in banner (#2681) fix: incorrect parsing of exposedPorts in readiness check (#2658) feat: add grafana-lgtm module (#2660) Added valkey module (#2639) fix: container.Endpoint and wait.FortHTTP to use lowest internal port (#2641)
testcontainers · Aug 6, 2024 · 553e925 · 553e925
2 parents 6d43e19 + b78a351
commit 553e925
Show file tree

Hide file tree

Showing 29 changed files with 4,188 additions and 72 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -94,7 +94,7 @@ jobs:
       matrix:
         go-version: [1.21.x, 1.x]
         platform: [ubuntu-latest]
-        module: [artemis, azurite, cassandra, chroma, clickhouse, cockroachdb, compose, consul, couchbase, dolt, elasticsearch, gcloud, inbucket, influxdb, k3s, k6, kafka, localstack, mariadb, milvus, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, ollama, openfga, openldap, opensearch, postgres, pulsar, qdrant, rabbitmq, redis, redpanda, registry, surrealdb, vault, vearch, weaviate]
+        module: [artemis, azurite, cassandra, chroma, clickhouse, cockroachdb, compose, consul, couchbase, dolt, elasticsearch, gcloud, grafana-lgtm, inbucket, influxdb, k3s, k6, kafka, localstack, mariadb, milvus, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, ollama, openfga, openldap, opensearch, postgres, pulsar, qdrant, rabbitmq, redis, redpanda, registry, surrealdb, valkey, vault, vearch, weaviate]
     uses: ./.github/workflows/ci-test-go.yml
     with:
       go-version: ${{ matrix.go-version }}

diff --git a/.vscode/.testcontainers-go.code-workspace b/.vscode/.testcontainers-go.code-workspace
@@ -61,6 +61,10 @@
             "name": "module / gcloud",
             "path": "../modules/gcloud"
         },
+        {
+            "name": "module / grafana-lgtm",
+            "path": "../modules/grafana-lgtm"
+        },
         {
             "name": "module / inbucket",
             "path": "../modules/inbucket"
@@ -169,6 +173,10 @@
             "name": "module / surrealdb",
             "path": "../modules/surrealdb"
         },
+        {
+            "name": "module / valkey",
+            "path": "../modules/valkey"
+        },
         {
             "name": "module / vault",
             "path": "../modules/vault"

diff --git a/container.go b/container.go
@@ -36,7 +36,7 @@ type DeprecatedContainer interface {
 // Container allows getting info about and controlling a single container instance
 type Container interface {
 	GetContainerID() string                                         // get the container id from the provider
-	Endpoint(context.Context, string) (string, error)               // get proto://ip:port string for the first exposed port
+	Endpoint(context.Context, string) (string, error)               // get proto://ip:port string for the lowest exposed port
 	PortEndpoint(context.Context, nat.Port, string) (string, error) // get proto://ip:port string for the given exposed port
 	Host(context.Context) (string, error)                           // get host where the container port is exposed
 	Inspect(context.Context) (*types.ContainerJSON, error)          // get container info

diff --git a/docker.go b/docker.go
@@ -113,24 +113,23 @@ func (c *DockerContainer) IsRunning() bool {
 	return c.isRunning
 }
 
-// Endpoint gets proto://host:port string for the first exposed port
+// Endpoint gets proto://host:port string for the lowest numbered exposed port
 // Will returns just host:port if proto is ""
 func (c *DockerContainer) Endpoint(ctx context.Context, proto string) (string, error) {
 	inspect, err := c.Inspect(ctx)
 	if err != nil {
 		return "", err
 	}
 
-	ports := inspect.NetworkSettings.Ports
-
-	// get first port
-	var firstPort nat.Port
-	for p := range ports {
-		firstPort = p
-		break
+	// Get lowest numbered bound port.
+	var lowestPort nat.Port
+	for port := range inspect.NetworkSettings.Ports {
+		if lowestPort == "" || port.Int() < lowestPort.Int() {
+			lowestPort = port
+		}
 	}
 
-	return c.PortEndpoint(ctx, firstPort, proto)
+	return c.PortEndpoint(ctx, lowestPort, proto)
 }
 
 // PortEndpoint gets proto://host:port string for the given exposed port

diff --git a/docker_client.go b/docker_client.go
@@ -57,19 +57,29 @@ func (c *DockerClient) Info(ctx context.Context) (system.Info, error) {
   Server Version: %v
   API Version: %v
   Operating System: %v
-  Total Memory: %v MB
+  Total Memory: %v MB%s
   Testcontainers for Go Version: v%s
   Resolved Docker Host: %s - %s
   Resolved Docker Socket Path: %s
   Test SessionID: %s
   Test ProcessID: %s
 `
+	infoLabels := ""
+	if len(dockerInfo.Labels) > 0 {
+		infoLabels = `
+  Labels:`
+		for _, lb := range dockerInfo.Labels {
+			infoLabels += "\n    " + lb
+		}
+	}
 
 	dockerHost := core.ExtractDockerHost(ctx)
 
 	Logger.Printf(infoMessage, packagePath,
-		dockerInfo.ServerVersion, c.Client.ClientVersion(),
+		dockerInfo.ServerVersion,
+		c.Client.ClientVersion(),
 		dockerInfo.OperatingSystem, dockerInfo.MemTotal/1024/1024,
+		infoLabels,
 		internal.Version,
 		dockerHost,
 		core.GetDockerHostIPs(),

diff --git a/docs/features/wait/host_port.md b/docs/features/wait/host_port.md
@@ -3,7 +3,7 @@
 The host-port wait strategy will check if the container is listening to a specific port and allows to set the following conditions:
 
 - a port exposed by the container. The port and protocol to be used, which is represented by a string containing the port number and protocol in the format "80/tcp".
-- alternatively, wait for the first exposed port in the container.
+- alternatively, wait for the lowest exposed port in the container.
 - the startup timeout to be used, default is 60 seconds.
 - the poll interval to be used, default is 100 milliseconds.
 
@@ -19,9 +19,9 @@ req := ContainerRequest{
 }
 ```
 
-## First exposed port in the container
+## Lowest exposed port in the container
 
-The wait strategy will use the first exposed port from the container configuration.
+The wait strategy will use the lowest exposed port from the container configuration.
 
 ```golang
 req := ContainerRequest{
@@ -30,12 +30,12 @@ req := ContainerRequest{
 }
 ```
 
-Said that, it could be the case that the container request included ports to be exposed. Therefore using `wait.ForExposedPort` will wait for the first exposed port in the request, because the container configuration retrieved from Docker will already include them.
+Said that, it could be the case that the container request included ports to be exposed. Therefore using `wait.ForExposedPort` will wait for the lowest exposed port in the request, because the container configuration retrieved from Docker will already include them.
 
 ```golang
 req := ContainerRequest{
     Image:        "docker.io/nginx:alpine",
     ExposedPorts: []string{"80/tcp", "9080/tcp"},
     WaitingFor:   wait.ForExposedPort(),
 }
-```
+```
diff --git a/docs/features/wait/http.md b/docs/features/wait/http.md
@@ -2,7 +2,7 @@
 
 The HTTP wait strategy will check the result of an HTTP(S) request against the container and allows to set the following conditions:
 
-- the port to be used. If no port is passed, it will use the first exposed port in the image.
+- the port to be used. If no port is passed, it will use the lowest exposed port in the image.
 - the path to be used.
 - the HTTP method to be used.
 - the HTTP request body to be sent.

diff --git a/docs/modules/grafana-lgtm.md b/docs/modules/grafana-lgtm.md
@@ -0,0 +1,115 @@
+# Grafana LGTM
+
+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 Grafana LGTM.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the Grafana module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/grafanalgtm
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a Grafana LGTM container](../../modules/grafana-lgtm/examples_test.go) inside_block:runGrafanaLGTMContainer
+<!--/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>
+
+!!!info
+    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.
+
+The Grafana LGTM module exposes one entrypoint function to create the Grafana LGTM container, and this function receives three parameters:
+
+```golang
+func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*GrafanaLGTMContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `string`, the Docker image to use.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+### Container Options
+
+When starting the Grafana LGTM container, you can pass options in a variadic way to configure it.
+
+#### Image
+
+If you need to set a different Grafana LGTM Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "grafana/otel-lgtm:0.6.0")`.
+
+#### Admin Credentials
+
+- 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>
+
+If you need to set different admin credentials in the Grafana LGTM container, you can set them using the `WithAdminCredentials(user, password)` option.
+
+{% include "../features/common_functional_options.md" %}
+
+### Container Methods
+
+The Grafana LGTM container exposes the following methods:
+
+!!!info
+    All the endpoint methods return their endpoints in the format `<host>:<port>`, so please use them accordingly to configure your client.
+
+#### Grafana Endpoint
+
+- 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 `HttpEndpoint(ctx)` method returns the HTTP endpoint to connect to Grafana, using the default `3000` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+#### Loki Endpoint
+
+- 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 `LokiEndpoint(ctx)` method returns the HTTP endpoint to connect to Loki, using the default `3100` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+#### Tempo Endpoint
+
+- 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 `TempoEndpoint(ctx)` method returns the HTTP endpoint to connect to Tempo, using the default `3200` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+#### Otel HTTP Endpoint
+
+- 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 `OtelHTTPEndpoint(ctx)` method returns the endpoint to connect to Otel using HTTP, using the default `4318` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+#### Otel gRPC Endpoint
+
+- 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 `OtelGRPCEndpoint(ctx)` method returns the endpoint to connect to Otel using gRPC, using the default `4317` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+#### Prometheus Endpoint
+
+- 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 `PrometheusHttpEndpoint(ctx)` method returns the endpoint to connect to Prometheus, using the default `9090` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+## Examples
+
+### Traces, Logs and Prometheus metrics for a simple Go process
+
+In this example, a simple application is created to generate traces, logs, and Prometheus metrics.
+The application sends data to Grafana LGTM, and the Otel SDK is used to send the data.
+The example demonstrates how to set up the Otel SDK and run the Grafana LGTM module,
+configuring the Otel library to send data to Grafana LGTM thanks to the endpoints provided by the Grafana LGTM container.
+
+<!--codeinclude-->
+[App sending Otel data](../../modules/grafana-lgtm/examples_test.go) inside_block:rollDiceApp
+[Setup Otel SDK](../../modules/grafana-lgtm/examples_test.go) inside_block:setupOTelSDK
+[Run the Grafana LGTM container](../../modules/grafana-lgtm/examples_test.go) inside_block:ExampleRun_otelCollector
+<!--/codeinclude-->
diff --git a/docs/modules/valkey.md b/docs/modules/valkey.md
@@ -0,0 +1,75 @@
+# Valkey
+
+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 Valkey.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the Valkey module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/valkey
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a Valkey container](../../modules/valkey/examples_test.go) inside_block:runValkeyContainer
+<!--/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>
+
+!!!info
+    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.
+
+The Valkey module exposes one entrypoint function to create the Valkey container, and this function receives three parameters:
+
+```golang
+func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ValkeyContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `string`, the Docker image to use.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+### Container Options
+
+When starting the Valkey container, you can pass options in a variadic way to configure it.
+
+#### Image
+
+If you need to set a different Valkey Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "valkey/valkey:7.2.5")`.
+
+{% include "../features/common_functional_options.md" %}
+
+#### Snapshotting
+
+By default Valkey saves snapshots of the dataset on disk, in a binary file called dump.rdb. You can configure Valkey to have it save the dataset every `N` seconds if there are at least `M` changes in the dataset. E.g. `WithSnapshotting(10, 1)`.
+
+#### Log Level
+
+You can easily set the valkey logging level. E.g. `WithLogLevel(LogLevelDebug)`.
+
+#### Valkey configuration
+
+In the case you have a custom config file for Valkey, it's possible to copy that file into the container before it's started. E.g. `WithConfigFile(filepath.Join("testdata", "valkey.conf"))`.
+
+### Container Methods
+
+The Valkey container exposes the following methods:
+
+#### ConnectionString
+
+This method returns the connection string to connect to the Valkey container, using the default `6379` port.
+
+<!--codeinclude-->
+[Get connection string](../../modules/valkey/valkey_test.go) inside_block:connectionString
+<!--/codeinclude-->