Merge remote-tracking branch 'origin/main' into gui/test-packages-for…

…-docs

.github/dependabot.yml

@@ -23,13 +23,6 @@ updates:
         day: sunday
       open-pull-requests-limit: 3
       rebase-strategy: disabled
-    - package-ecosystem: gomod
-      directory: /examples/consul
-      schedule:
-        interval: monthly
-        day: sunday
-      open-pull-requests-limit: 3
-      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /examples/nginx
       schedule:
@@ -86,6 +79,13 @@ updates:
         day: sunday
       open-pull-requests-limit: 3
       rebase-strategy: disabled
+    - package-ecosystem: gomod
+      directory: /modules/consul
+      schedule:
+        interval: monthly
+        day: sunday
+      open-pull-requests-limit: 3
+      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /modules/couchbase
       schedule:

.github/workflows/ci.yml

@@ -52,7 +52,7 @@ jobs:
     uses: ./.github/workflows/ci-test-go.yml
     with:
       go-version: ${{ matrix.go-version }}
-      fail-fast: true
+      fail-fast: false
       platform: "ubuntu-latest"
       project-directory: "."
       rootless-docker: false
@@ -72,7 +72,7 @@ jobs:
     uses: ./.github/workflows/ci-test-go.yml
     with:
       go-version: ${{ matrix.go-version }}
-      fail-fast: true
+      fail-fast: false
       platform: "ubuntu-latest"
       project-directory: "."
       rootless-docker: true
@@ -104,7 +104,7 @@ jobs:
       matrix:
         go-version: [1.20.x, 1.x]
         platform: [ubuntu-latest]
-        module: [artemis, cassandra, clickhouse, cockroachdb, compose, couchbase, elasticsearch, gcloud, inbucket, k3s, k6, kafka, localstack, mariadb, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, openldap, postgres, pulsar, rabbitmq, redis, redpanda, vault]
+        module: [artemis, cassandra, clickhouse, cockroachdb, compose, consul, couchbase, elasticsearch, gcloud, inbucket, k3s, k6, kafka, localstack, mariadb, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, openldap, postgres, pulsar, rabbitmq, redis, redpanda, vault]
         exclude:
           - go-version: 1.20.x
             module: compose
@@ -124,7 +124,7 @@ jobs:
     needs: test-modules
     strategy:
       matrix:
-        module: [consul, nginx, toxiproxy]
+        module: [nginx, toxiproxy]
     uses: ./.github/workflows/ci-test-go.yml
     with:
       go-version: "1.20.x"

.vscode/.testcontainers-go.code-workspace

@@ -5,10 +5,6 @@
             "name": "testcontainers-go",
             "path": "../"
         },
-        {
-            "name": "example / consul",
-            "path": "../examples/consul"
-        },
         {
             "name": "example / nginx",
             "path": "../examples/nginx"
@@ -37,6 +33,10 @@
             "name": "module / compose",
             "path": "../modules/compose"
         },
+        {
+            "name": "module / consul",
+            "path": "../modules/consul"
+        },
         {
             "name": "module / couchbase",
             "path": "../modules/couchbase"
@@ -134,4 +134,4 @@
             "path": "../modulegen"
         }
     ]
-}
+}

RELEASING.md

@@ -150,7 +150,6 @@ git add modules/**/go.*
 git commit -m chore: use new version (v0.20.1) in modules and examples
 git tag v0.20.1
 git tag examples/bigtable/v0.20.1
-git tag examples/consul/v0.20.1
 git tag examples/datastore/v0.20.1
 git tag examples/firestore/v0.20.1
 git tag examples/mongodb/v0.20.1
@@ -178,7 +177,6 @@ git commit -m chore: prepare for next minor development cycle (0.21.0)
 git push origin main --tags
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/bigtable/@v/v0.20.1.info
-curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/consul/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/datastore/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/firestore/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/mongodb/@v/v0.20.1.info

docker.go

@@ -203,6 +203,13 @@ func (c *DockerContainer) Start(ctx context.Context) error {
 		return err
 	}
 
+	c.isRunning = true
+
+	err = c.readiedHook(ctx)
+	if err != nil {
+		return err
+	}
+
 	return nil
 }
 
@@ -893,86 +900,6 @@ func (p *DockerProvider) BuildImage(ctx context.Context, img ImageBuildInfo) (st
 	return buildOptions.Tags[0], nil
 }
 
-// DefaultDockerLifecycleHook returns the default hooks for a Docker container
-func (p *DockerProvider) DefaultDockerLifecycleHook(req ContainerRequest, dockerInput *container.Config, hostConfig *container.HostConfig, networkingConfig *network.NetworkingConfig) ContainerLifecycleHooks {
-	return ContainerLifecycleHooks{
-		PreCreates: []ContainerRequestHook{
-			func(ctx context.Context, req ContainerRequest) error {
-				return p.preCreateContainerHook(ctx, req, dockerInput, hostConfig, networkingConfig)
-			},
-		},
-		PostCreates: []ContainerHook{
-			// copy files to container after it's created
-			func(ctx context.Context, c Container) error {
-				for _, f := range req.Files {
-					err := c.CopyFileToContainer(ctx, f.HostFilePath, f.ContainerFilePath, f.FileMode)
-					if err != nil {
-						return fmt.Errorf("can't copy %s to container: %w", f.HostFilePath, err)
-					}
-				}
-
-				return nil
-			},
-		},
-		PostStarts: []ContainerHook{
-			// first post-start hook is to produce logs and start log consumers
-			func(ctx context.Context, c Container) error {
-				dockerContainer := c.(*DockerContainer)
-
-				logConsumerConfig := req.LogConsumerCfg
-				if logConsumerConfig == nil {
-					return nil
-				}
-
-				for _, consumer := range logConsumerConfig.Consumers {
-					dockerContainer.followOutput(consumer)
-				}
-
-				if len(logConsumerConfig.Consumers) > 0 {
-					return dockerContainer.startLogProduction(ctx, logConsumerConfig.Opts...)
-				}
-				return nil
-			},
-			// second post-start hook is to wait for the container to be ready
-			func(ctx context.Context, c Container) error {
-				dockerContainer := c.(*DockerContainer)
-
-				// if a Wait Strategy has been specified, wait before returning
-				if dockerContainer.WaitingFor != nil {
-					dockerContainer.logger.Printf(
-						"🚧 Waiting for container id %s image: %s. Waiting for: %+v",
-						dockerContainer.ID[:12], dockerContainer.Image, dockerContainer.WaitingFor,
-					)
-					if err := dockerContainer.WaitingFor.WaitUntilReady(ctx, c); err != nil {
-						return err
-					}
-				}
-
-				dockerContainer.isRunning = true
-
-				return nil
-			},
-		},
-		PreTerminates: []ContainerHook{
-			// first pre-terminate hook is to stop the log production
-			func(ctx context.Context, c Container) error {
-				logConsumerConfig := req.LogConsumerCfg
-
-				if logConsumerConfig == nil {
-					return nil
-				}
-				if len(logConsumerConfig.Consumers) == 0 {
-					return nil
-				}
-
-				dockerContainer := c.(*DockerContainer)
-
-				return dockerContainer.stopLogProduction()
-			},
-		},
-	}
-}
-
 // CreateContainer fulfills a request for a container without starting it
 func (p *DockerProvider) CreateContainer(ctx context.Context, req ContainerRequest) (Container, error) {
 	var err error
@@ -1146,11 +1073,13 @@ func (p *DockerProvider) CreateContainer(ctx context.Context, req ContainerReque
 	// default hooks include logger hook and pre-create hook
 	defaultHooks := []ContainerLifecycleHooks{
 		DefaultLoggingHook(p.Logger),
-		p.DefaultDockerLifecycleHook(req, dockerInput, hostConfig, networkingConfig),
+		DefaultPreCreateHook(p, dockerInput, hostConfig, networkingConfig),
+		DefaultCopyFileToContainerHook(req.Files),
+		DefaultLogConsumersHook(req.LogConsumerCfg),
+		DefaultReadinessHook(),
 	}
 
-	// always prepend default lifecycle hooks to user-defined hooks
-	req.LifecycleHooks = append(defaultHooks, req.LifecycleHooks...)
+	req.LifecycleHooks = []ContainerLifecycleHooks{CombineContainerHooks(defaultHooks, req.LifecycleHooks)}
 
 	err = req.creatingHook(ctx)
 	if err != nil {

docker_files_test.go

@@ -82,7 +82,7 @@ func TestCopyFileToRunningContainer(t *testing.T) {
 	require.NoError(t, err)
 
 	// Give some time to the wait script to catch the hello script being created
-	err = wait.ForLog("done").WithStartupTimeout(200*time.Millisecond).WaitUntilReady(ctx, container)
+	err = wait.ForLog("done").WithStartupTimeout(2*time.Second).WaitUntilReady(ctx, container)
 	require.NoError(t, err)
 
 	require.NoError(t, container.Terminate(ctx))

docs/features/common_functional_options.md

@@ -17,7 +17,7 @@ Using the `WithImageSubstitutors` options, you could define your own substitutio
 
 #### WithLogConsumers
 
-- 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>
+- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>
 
 If you need to consume the logs of the container, you can use `testcontainers.WithLogConsumers` with a valid log consumer. An example of a log consumer is the following:
 
@@ -58,6 +58,19 @@ It also exports an `Executable` interface, defining the following methods:
 
 You could use this feature to run a custom script, or to run a command that is not supported by the module right after the container is started.
 
+#### Ready Commands
+
+- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>
+
+Testcontainers exposes the `WithAfterReadyCommand(e ...Executable)` option to run arbitrary commands in the container right after it's ready, which happens when the defined wait strategies have finished with success.
+
+!!!info
+    To better understand how this feature works, please read the [Create containers: Lifecycle Hooks](/features/creating_container/#lifecycle-hooks) documentation.
+
+It leverages the `Executable` interface to represent the command and positional arguments to be executed in the container.
+
+You could use this feature to run a custom script, or to run a command that is not supported by the module right after the container is ready.
+
 #### WithNetwork
 
 - Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

docs/features/creating_container.md

@@ -91,19 +91,32 @@ func TestIntegrationNginxLatestReturn(t *testing.T) {
 
 _Testcontainers for Go_ allows you to define your own lifecycle hooks for better control over your containers. You just need to define functions that return an error and receive the Go context as first argument, and a `ContainerRequest` for the `Creating` hook, and a `Container` for the rest of them as second argument.
 
-You'll be able to pass multiple lifecycle hooks at the `ContainerRequest` as an array of `testcontainers.ContainerLifecycleHooks`, which will be processed one by one in the order they are passed.
-
-The `testcontainers.ContainerLifecycleHooks` struct defines the following lifecycle hooks, each of them backed by an array of functions representing the hooks:
+You'll be able to pass multiple lifecycle hooks at the `ContainerRequest` as an array of `testcontainers.ContainerLifecycleHooks`. The `testcontainers.ContainerLifecycleHooks` struct defines the following lifecycle hooks, each of them backed by an array of functions representing the hooks:
 
 * `PreCreates` - hooks that are executed before the container is created
 * `PostCreates` - hooks that are executed after the container is created
 * `PreStarts` - hooks that are executed before the container is started
 * `PostStarts` - hooks that are executed after the container is started
+* `PostReadies` - hooks that are executed after the container is ready
 * `PreStops` - hooks that are executed before the container is stopped
 * `PostStops` - hooks that are executed after the container is stopped
 * `PreTerminates` - hooks that are executed before the container is terminated
 * `PostTerminates` - hooks that are executed after the container is terminated
 
+_Testcontainers for Go_ defines some default lifecycle hooks that are always executed in a specific order with respect to the user-defined hooks. The order of execution is the following:
+
+1. default `pre` hooks.
+2. user-defined `pre` hooks.
+3. user-defined `post` hooks.
+4. default `post` hooks.
+
+Inside each group, the hooks will be executed in the order they were defined.
+
+!!!info
+	The default hooks are for logging (applied to all hooks), customising the Docker config (applied to the pre-create hook), copying files in to the container (applied to the post-create hook), adding log consumers (applied to the post-start and pre-terminate hooks), and running the wait strategies as a readiness check (applied to the post-start hook).
+
+It's important to notice that the `Readiness` of a container is defined by the wait strategies defined for the container. **This hook will be executed right after the `PostStarts` hook**. If you want to add your own readiness checks, you can do it by adding a `PostReadies` hook to the container request, which will execute your own readiness check after the default ones. That said, the `PostStarts` hooks don't warrant that the container is ready, so you should not rely on that.
+
 In the following example, we are going to create a container using all the lifecycle hooks, all of them printing a message when any of the lifecycle hooks is called:
 
 <!--codeinclude-->
@@ -112,10 +125,11 @@ In the following example, we are going to create a container using all the lifec
 
 #### Default Logging Hook
 
-_Testcontainers for Go_ comes with a default logging hook that will print a log message for each container lifecycle event. You can enable it by passing the `testcontainers.DefaultLoggingHook` option to the `ContainerRequest`, passing a reference to the container logger like this:
+_Testcontainers for Go_ comes with a default logging hook that will print a log message for each container lifecycle event, using the default logger. You can add your own logger by passing the `testcontainers.DefaultLoggingHook` option to the `ContainerRequest`, passing a reference to your preferred logger:
 
 <!--codeinclude-->
-[Extending container with life cycle hooks](../../lifecycle_test.go) inside_block:reqWithDefaultLogginHook
+[Use a custom logger for container hooks](../../lifecycle_test.go) inside_block:reqWithDefaultLogginHook
+[Custom Logger implementation](../../lifecycle_test.go) inside_block:customLoggerImplementation
 <!--/codeinclude-->
 
 ### Advanced Settings

docs/modules/cockroachdb.md

@@ -1,6 +1,6 @@
 # CockroachDB
 
-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>
+Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>
 
 ## Introduction
 

docs/modules/consul.md

@@ -0,0 +1,58 @@
+# Consul
+
+Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>
+
+## Introduction
+
+The Testcontainers module for Consul.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the Consul module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/consul
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a Consul container](../../modules/consul/examples_test.go) inside_block:runConsulContainer
+<!--/codeinclude-->
+
+## Module reference
+
+The Consul module exposes one entrypoint function to create the Consul container, and this function receives two parameters:
+
+```golang
+func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*ConsulContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+### Container Options
+
+When starting the Consul container, you can pass options in a variadic way to configure it.
+
+#### 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")`.
+
+{% include "../features/common_functional_options.md" %}
+
+#### Configuration File
+If you need to customize the behavior for the deployed node you can use either `WithConfigString(config string)` or `WithConfigFile(configPath string)`.
+The configuration has to be in JSON format and will be loaded at the node startup.
+
+### Container Methods
+
+The Consul container exposes the following method:
+
+#### ApiEndpoint
+This method returns the connection string to connect to the Consul container API, using the default `8500` port.
+
+<!--codeinclude-->
+[Using ApiEndpoint with the Consul client](../../modules/consul/examples_test.go) inside_block:connectConsul
+<!--/codeinclude-->

docs/modules/inbucket.md

@@ -1,6 +1,6 @@
 # Inbucket
 
-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>
+Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>
 
 ## Introduction