Merge branch 'main' into rootless-docker

* main:
  docs: enrich docs for modules (testcontainers#1167)
  chore: prepare for next minor development cycle (0.21.0)
  chore: use new version (v0.20.1) in modules and examples
  Revert "fix: don't panic when logs waits for more than 5 seconds (testcontainers#947)" (testcontainers#1164)
  fix: define a two-phase release process (testcontainers#1163)
  ci(lint): enable misspell and gci linters (testcontainers#1162)

.github/workflows/golangci-lint.yml

@@ -35,7 +35,7 @@ jobs:
 
           # Optional: golangci-lint command line arguments.
           # args: --issues-exit-code=0
-          args: --timeout=3m
+          args: --verbose
 
           # Optional: show only new issues if it's a pull request. The default value is `false`.
           # only-new-issues: true

.golangci.yml

@@ -1,3 +1,16 @@
 linters:
   enable:
+    - gci
     - gofmt
+    - misspell
+
+
+linters-settings:
+  gci:
+    sections:
+    - standard
+    - default
+    - prefix(github.com/testcontainters)
+
+run:
+  timeout: 3m

container.go

@@ -13,7 +13,6 @@ import (
 	"github.com/docker/docker/api/types/network"
 	"github.com/docker/docker/pkg/archive"
 	"github.com/docker/go-connections/nat"
-
 	tcexec "github.com/testcontainers/testcontainers-go/exec"
 	"github.com/testcontainers/testcontainers-go/internal/testcontainersdocker"
 	"github.com/testcontainers/testcontainers-go/wait"

docker.go

@@ -18,12 +18,11 @@ import (
 	"sync"
 	"time"
 
-	"github.com/docker/docker/api/types/filters"
-
 	"github.com/cenkalti/backoff/v4"
 	"github.com/containerd/containerd/platforms"
 	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
 	"github.com/docker/docker/api/types/network"
 	"github.com/docker/docker/client"
 	"github.com/docker/docker/errdefs"
@@ -32,7 +31,6 @@ import (
 	"github.com/google/uuid"
 	"github.com/moby/term"
 	specs "github.com/opencontainers/image-spec/specs-go/v1"
-
 	tcexec "github.com/testcontainers/testcontainers-go/exec"
 	"github.com/testcontainers/testcontainers-go/internal"
 	"github.com/testcontainers/testcontainers-go/internal/testcontainersdocker"
@@ -69,7 +67,7 @@ type DockerContainer struct {
 	terminationSignal chan bool
 	consumers         []LogConsumer
 	raw               *types.ContainerJSON
-	stopProducer      context.CancelFunc
+	stopProducer      chan bool
 	logger            Logging
 	lifecycleHooks    []ContainerLifecycleHooks
 }
@@ -632,9 +630,9 @@ func (c *DockerContainer) StartLogProducer(ctx context.Context) error {
 		return errors.New("log producer already started")
 	}
 
-	ctx, c.stopProducer = context.WithCancel(ctx)
+	c.stopProducer = make(chan bool)
 
-	go func() {
+	go func(stop <-chan bool) {
 		since := ""
 		// if the socket is closed we will make additional logs request with updated Since timestamp
 	BEGIN:
@@ -645,22 +643,20 @@ func (c *DockerContainer) StartLogProducer(ctx context.Context) error {
 			Since:      since,
 		}
 
+		ctx, cancel := context.WithTimeout(ctx, time.Second*5)
+		defer cancel()
+
 		r, err := c.provider.client.ContainerLogs(ctx, c.GetContainerID(), options)
 		if err != nil {
-			// if we can't get the logs, retry in one second.
-			c.logger.Printf("cannot get logs for container %q: %v", c.ID, err)
-			if ctx.Err() != nil {
-				// context done.
-				return
-			}
-			time.Sleep(1 * time.Second)
-			goto BEGIN
+			// if we can't get the logs, panic, we can't return an error to anything
+			// from within this goroutine
+			panic(err)
 		}
 		defer c.provider.Close()
 
 		for {
 			select {
-			case <-ctx.Done():
+			case <-stop:
 				err := r.Close()
 				if err != nil {
 					// we can't close the read closer, this should never happen
@@ -711,7 +707,7 @@ func (c *DockerContainer) StartLogProducer(ctx context.Context) error {
 				}
 			}
 		}
-	}()
+	}(c.stopProducer)
 
 	return nil
 }
@@ -720,8 +716,7 @@ func (c *DockerContainer) StartLogProducer(ctx context.Context) error {
 // and sending them to each added LogConsumer
 func (c *DockerContainer) StopLogProducer() error {
 	if c.stopProducer != nil {
-		// Cancel the producer's context.
-		c.stopProducer()
+		c.stopProducer <- true
 		c.stopProducer = nil
 	}
 	return nil

docker_mounts.go

@@ -33,7 +33,7 @@ type DockerBindMountSource struct {
 	*mount.BindOptions
 
 	// HostPath is the path mounted into the container
-	// the same host path might be mounted to multiple locations withing a single container
+	// the same host path might be mounted to multiple locations within a single container
 	HostPath string
 }
 

docker_test.go

@@ -4,9 +4,8 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"log"
-
 	"io"
+	"log"
 	"math/rand"
 	"net/http"
 	"os"
@@ -16,19 +15,16 @@ import (
 	"testing"
 	"time"
 
+	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
 	"github.com/docker/docker/api/types/strslice"
+	"github.com/docker/docker/api/types/volume"
+	"github.com/docker/docker/errdefs"
 	"github.com/docker/go-units"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	"github.com/docker/docker/errdefs"
-
-	"github.com/docker/docker/api/types/volume"
-
-	"github.com/docker/docker/api/types"
-	"github.com/docker/docker/api/types/filters"
-
 	"github.com/testcontainers/testcontainers-go/internal/config"
 	"github.com/testcontainers/testcontainers-go/internal/testcontainersdocker"
 	"github.com/testcontainers/testcontainers-go/wait"

docs/modules/couchbase.md

@@ -68,6 +68,26 @@ By default, the container will use the following Docker image:
 [Default Docker image](../../modules/couchbase/couchbase.go) inside_block:defaultImage
 <!--/codeinclude-->
 
+#### Wait Strategies
+
+If you need to set a different wait strategy for Couchbase, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy
+for Couchbase.
+
+!!!info
+    The default deadline for the wait strategy is 60 seconds.
+
+At the same time, it's possible to set a wait strategy and a custom deadline with `testcontainers.WithWaitStrategyAndDeadline`.
+
+#### Docker type modifiers
+
+If you need an advanced configuration for Couchbase, you can leverage the following Docker type modifiers:
+
+- `testcontainers.WithConfigModifier`
+- `testcontainers.WithHostConfigModifier`
+- `testcontainers.WithEndpointSettingsModifier`
+
+Please read the [Create containers: Advanced Settings](../features/creating_container.md#advanced-settings) documentation for more information.
+
 #### 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.

docs/modules/mysql.md

@@ -31,23 +31,50 @@ func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomize
 - `context.Context`, the Go context.
 - `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
 
-## Container Options
+### Container Options
 
 When starting the MySQL container, you can pass options in a variadic way to configure it.
 
 !!!tip
 
     You can find all the available configuration and environment variables for the MySQL Docker image on [Docker Hub](https://hub.docker.com/_/mysql).
 
-### Set Image
+#### Image
 
-By default, the image used is `mysql:8`.  If you need to use a different image, you can use `testcontainers.WithImage` option.
+If you need to set a different MySQL Docker image, you can use `testcontainers.WithImage` with a valid Docker image
+for MySQL. E.g. `testcontainers.WithImage("mysql:5.6")`.
 
 <!--codeinclude-->
 [Custom Image](../../modules/mysql/mysql_test.go) inside_block:withConfigFile
 <!--/codeinclude-->
 
-### Set username, password and database name
+By default, the container will use the following Docker image:
+
+<!--codeinclude-->
+[Default Docker image](../../modules/mysql/mysql.go) inside_block:defaultImage
+<!--/codeinclude-->
+
+#### Wait Strategies
+
+If you need to set a different wait strategy for MySQL, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy
+for MySQL.
+
+!!!info
+    The default deadline for the wait strategy is 60 seconds.
+
+At the same time, it's possible to set a wait strategy and a custom deadline with `testcontainers.WithWaitStrategyAndDeadline`.
+
+#### Docker type modifiers
+
+If you need an advanced configuration for MySQL, you can leverage the following Docker type modifiers:
+
+- `testcontainers.WithConfigModifier`
+- `testcontainers.WithHostConfigModifier`
+- `testcontainers.WithEndpointSettingsModifier`
+
+Please read the [Create containers: Advanced Settings](../features/creating_container.md#advanced-settings) documentation for more information.
+
+#### Set username, password and database name
 
 If you need to set a different database, and its credentials, you can use `WithUsername`, `WithPassword`, `WithDatabase`
 options.  By default, the username, the password and the database name is `test`.
@@ -56,7 +83,10 @@ options.  By default, the username, the password and the database name is `test`
 [Custom Database initialization](../../modules/mysql/mysql_test.go) inside_block:customInitialization
 <!--/codeinclude-->
 
-### Init Scripts
+!!!info
+    The default values for the username is `root`, for password is `test` and for the default database name is `test`.
+
+#### Init Scripts
 
 If you would like to perform DDL or DML operations in the MySQL container, add one or more `*.sql`, `*.sql.gz`, or `*.sh`
 scripts to the container request. Those files will be copied under `/docker-entrypoint-initdb.d`.
@@ -65,10 +95,21 @@ scripts to the container request. Those files will be copied under `/docker-entr
 [Include init scripts](../../modules/mysql/mysql_test.go) inside_block:withScripts
 <!--/codeinclude-->
 
-### Custom configuration
+#### Custom configuration
 
 If you need to set a custom configuration, you can use `WithConfigFile` option.
 
 <!--codeinclude-->
 [Custom MySQL config file](../../modules/mysql/mysql_test.go) inside_block:withConfigFile
 <!--/codeinclude-->
+
+### Container Methods
+
+#### ConnectionString
+
+This method returns the connection string to connect to the MySQL container, using the default `3306` port.
+It's possible to pass extra parameters to the connection string, e.g. `sslmode=disable` or `application_name=myapp`, in a variadic way.
+
+<!--codeinclude-->
+[Get connection string](../../modules/mysql/mysql_test.go) inside_block:connectionString
+<!--/codeinclude-->

docs/modules/neo4j.md

@@ -56,6 +56,26 @@ By default, the container will use the following Docker image:
 [Default Docker image](../../modules/neo4j/neo4j.go) inside_block:defaultImage
 <!--/codeinclude-->
 
+#### Wait Strategies
+
+If you need to set a different wait strategy for Neo4j, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy
+for Neo4j.
+
+!!!info
+    The default deadline for the wait strategy is 60 seconds.
+
+At the same time, it's possible to set a wait strategy and a custom deadline with `testcontainers.WithWaitStrategyAndDeadline`.
+
+#### Docker type modifiers
+
+If you need an advanced configuration for Neo4j, you can leverage the following Docker type modifiers:
+
+- `testcontainers.WithConfigModifier`
+- `testcontainers.WithHostConfigModifier`
+- `testcontainers.WithEndpointSettingsModifier`
+
+Please read the [Create containers: Advanced Settings](../features/creating_container.md#advanced-settings) documentation for more information.
+
 #### Logger
 
 This option sets a custom logger to be used by the container. Consider calling this before other `With` functions as these may generate logs.

docs/modules/postgres.md

@@ -43,6 +43,30 @@ When starting the Postgres container, you can pass options in a variadic way to
 If you need to set a different Postgres Docker image, you can use `testcontainers.WithImage` with a valid Docker image
 for Postgres. E.g. `testcontainers.WithImage("docker.io/postgres:9.6")`.
 
+#### Wait Strategies
+
+If you need to set a different wait strategy for Postgres, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy
+for Postgres.
+
+!!!info
+    The default deadline for the wait strategy is 60 seconds.
+
+At the same time, it's possible to set a wait strategy and a custom deadline with `testcontainers.WithWaitStrategyAndDeadline`.
+
+<!--codeinclude-->
+[Set Wait Strategy](../../modules/postgres/postgres_test.go) inside_block:withWaitStrategy
+<!--/codeinclude-->
+
+#### Docker type modifiers
+
+If you need an advanced configuration for Postgres, you can leverage the following Docker type modifiers:
+
+- `testcontainers.WithConfigModifier`
+- `testcontainers.WithHostConfigModifier`
+- `testcontainers.WithEndpointSettingsModifier`
+
+Please read the [Create containers: Advanced Settings](../features/creating_container.md#advanced-settings) documentation for more information.
+
 #### Initial Database
 
 If you need to set a different database, and its credentials, you can use the `WithInitialDatabase`.
@@ -77,15 +101,6 @@ In the case you have a custom config file for Postgres, it's possible to copy th
 [Include custom configuration file](../../modules/postgres/postgres_test.go) inside_block:withConfigFile
 <!--/codeinclude-->
 
-#### Wait Strategies
-
-Given you could need to wait for different conditions, in particular using a wait.ForSQL strategy,
-the Postgres container exposes a `testcontainers.WithWaitStrategy` option to set a custom wait strategy.
-
-<!--codeinclude-->
-[Set Wait Strategy](../../modules/postgres/postgres_test.go) inside_block:withWaitStrategy
-<!--/codeinclude-->
-
 ### Container Methods
 
 #### ConnectionString