docs: add RunContainer example for localstack

docs/modules/localstack.md

@@ -19,30 +19,47 @@ go get github.com/testcontainers/testcontainers-go/modules/localstack
 Running LocalStack as a stand-in for multiple AWS services during a test:
 
 <!--codeinclude-->
-[Creating a LocalStack container](../../modules/localstack/v1/s3_test.go) inside_block:localStackCreateContainer
+[Creating a LocalStack container](../../modules/localstack/examples_test.go) inside_block:runLocalstackContainer
 <!--/codeinclude-->
 
 Environment variables listed in [Localstack's README](https://github.com/localstack/localstack#configurations) may be used to customize Localstack's configuration. 
 Use the `OverrideContainerRequest` option when creating the `LocalStackContainer` to apply configuration settings.
 
-## Creating a client using the AWS SDK for Go
+## Module reference
+
+The LocalStack module exposes one single function to create the LocalStack container, and this function receives two parameters:
+
+```golang
+func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*LocalStackContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+### Container Options
+
+When starting the Localstack container, you can pass options in a variadic way to configure it.
+
+#### Image
 
-### Version 1
+By default, the image used is `localstack:1.4.0`.  If you need to use a different image, you can use `testcontainers.WithImage` option.
+
+#### Customize the container request
+
+It's possible to entirely override the default LocalStack container request:
 
 <!--codeinclude-->
-[Test for a LocalStack container, usinv AWS SDK v1](../../modules/localstack/v1/s3_test.go) inside_block:awsSDKClientV1
+[Customize container request](../../modules/localstack/localstack_test.go) inside_block:withCustomContainerRequest
 <!--/codeinclude-->
 
-For further reference on the SDK v1, please check out the AWS docs [here](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/setting-up.html).
+With simply passing the `testcontainers.CustomizeRequest` functional option to the `RunContainer` function, you'll be able to configure the LocalStack container with your own needs, as this new container request will be merged with the original one.
 
-### Version 2
+In the following example you check how it's possible to set certain environment variables that are needed by the tests, the most important of them the AWS services you want to use. Besides, the container runs in a separate Docker network with an alias:
 
 <!--codeinclude-->
-[Test for a LocalStack container, usinv AWS SDK v2](../../modules/localstack/v2/s3_test.go) inside_block:awsSDKClientV2
+[Overriding the default container request](../../modules/localstack/localstack_test.go) inside_block:withCustomContainerRequest
 <!--/codeinclude-->
 
-For further reference on the SDK v2, please check out the AWS docs [here](https://aws.github.io/aws-sdk-go-v2/docs/getting-started)
-
 ## Accessing hostname-sensitive services
 
 Some Localstack APIs, such as SQS, require the container to be aware of the hostname that it is accessible on - for example, for construction of queue URLs in responses.
@@ -56,62 +73,33 @@ Once the variable is set:
 
 * when running the Localstack container directly without a custom network defined, it is expected that all calls to the container will be from the test host. As such, the container address will be used (typically localhost or the address where the Docker daemon is running).
 
-    <!--codeinclude-->
-    [Localstack container running without a custom network](../../modules/localstack/localstack_test.go) inside_block:withoutNetwork
-    <!--/codeinclude-->
-
 * when running the Localstack container [with a custom network defined](/features/networking/#advanced-networking), it is expected that all calls to the container will be **from other containers on that network**. `HOSTNAME_EXTERNAL` will be set to the *last* network alias that has been configured for the Localstack container.
 
     <!--codeinclude-->
-    [Localstack container running with a custom network](../../modules/localstack/localstack_test.go) inside_block:withNetwork
+    [Localstack container running with a custom network](../../modules/localstack/examples_test.go) inside_block:localstackWithNetwork
     <!--/codeinclude-->
 
-* Other usage scenarios, such as where the Localstack container is used from both the test host and containers on a custom network are not automatically supported. If you have this use case, you should set `HOSTNAME_EXTERNAL` manually.
-
-## Module reference
-
-The LocalStack module exposes one single function to create the LocalStack container, and this function receives two parameters:
-
-```golang
-func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*LocalStackContainer, error)
-```
-
-- `context.Context`, the Go context.
-- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
-
-### Container Options
-
-When starting the Localstack container, you can pass options in a variadic way to configure it.
-
-#### Set Image
+* Other usage scenarios, such as where the Localstack container is used from both the test host and containers on a custom network, are not automatically supported. If you have this use case, you should set `HOSTNAME_EXTERNAL` manually.
 
-By default, the image used is `localstack:1.4.0`.  If you need to use a different image, you can use `testcontainers.WithImage` option.
-
-<!--codeinclude-->
-[Custom Image](../../modules/localstack/localstack_test.go) inside_block:withImage
-<!--/codeinclude-->
+## Obtaining a client using the AWS SDK for Go
 
-#### Customize the container request
+You can use the AWS SDK for Go to create a client for the LocalStack container. The following examples show how to create a client for the S3 service, using both the SDK v1 and v2.
 
-It's possible to entirely override the default LocalStack container request:
+### Using the AWS SDK v1
 
 <!--codeinclude-->
-[Customize container request](../../modules/localstack/localstack_test.go) inside_block:withCustomContainerRequest
+[AWS SDK v1](../../modules/localstack/v1/s3_test.go) inside_block:awsSDKClientV1
 <!--/codeinclude-->
 
-With simply passing the `testcontainers.CustomizeRequest` functional option to the `RunContainer` function, you'll be able to configure the LocalStack container with your own needs, as this new container request will be merged with the original one.
+For further reference on the SDK v1, please check out the AWS docs [here](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/setting-up.html).
 
-In the following example you check how it's possible to set certain environment variables that are needed by the tests, the most important of them the AWS services you want to use. Besides, the container runs in a separate Docker network with an alias:
+### Using the AWS SDK v2
 
 <!--codeinclude-->
-[Overriding the default container request](../../modules/localstack/localstack_test.go) inside_block:withNetwork
+[AWS SDK v2](../../modules/localstack/v2/s3_test.go) inside_block:awsSDKClientV2
 <!--/codeinclude-->
 
-If you do not need to override the container request, you can simply pass the Go context to the `RunContainer` function.
-
-<!--codeinclude-->
-[Skip overriding the default container request](../../modules/localstack/localstack_test.go) inside_block:noOverrideContainerRequest
-<!--/codeinclude-->
+For further reference on the SDK v2, please check out the AWS docs [here](https://aws.github.io/aws-sdk-go-v2/docs/getting-started)
 
 ## Testing the module
 
@@ -123,6 +111,5 @@ make test
 ```
 
 !!!info
-
 	At this moment, the tests for the module include tests for the S3 service, only. They live in two different Go packages of the LocalStack module,
     `v1` and `v2`, where it'll be easier to add more examples for the rest of services.

modules/localstack/examples_test.go

@@ -0,0 +1,115 @@
+package localstack_test
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/localstack"
+	"github.com/testcontainers/testcontainers-go/wait"
+)
+
+func ExampleRunContainer() {
+	// runLocalstackContainer {
+	ctx := context.Background()
+
+	localstackContainer, err := localstack.RunContainer(ctx,
+		testcontainers.WithImage("localstack/localstack:1.4.0"),
+	)
+	if err != nil {
+		panic(err)
+	}
+
+	// Clean up the container
+	defer func() {
+		if err := localstackContainer.Terminate(ctx); err != nil {
+			panic(err)
+		}
+	}()
+	// }
+
+	state, err := localstackContainer.State(ctx)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(state.Running)
+
+	// Output:
+	// true
+}
+
+func ExampleRunContainer_withNetwork() {
+	// localstackWithNetwork {
+	ctx := context.Background()
+
+	nwName := "localstack-network"
+
+	_, err := testcontainers.GenericNetwork(ctx, testcontainers.GenericNetworkRequest{
+		NetworkRequest: testcontainers.NetworkRequest{
+			Name: nwName,
+		},
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	localstackContainer, err := localstack.RunContainer(
+		ctx,
+		testcontainers.CustomizeRequest(testcontainers.GenericContainerRequest{
+			ContainerRequest: testcontainers.ContainerRequest{
+				Image:          "localstack/localstack:0.13.0",
+				Env:            map[string]string{"SERVICES": "s3,sqs"},
+				Networks:       []string{nwName},
+				NetworkAliases: map[string][]string{nwName: {"localstack"}},
+			},
+		}),
+	)
+	if err != nil {
+		panic(err)
+	}
+	// }
+
+	// Clean up the container
+	defer func() {
+		if err := localstackContainer.Terminate(ctx); err != nil {
+			panic(err)
+		}
+	}()
+
+	networks, err := localstackContainer.Networks(ctx)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(len(networks))
+	fmt.Println(networks[0])
+
+	// Output:
+	// 1
+	// localstack-network
+}
+
+func ExampleRunContainer_legacyMode() {
+	ctx := context.Background()
+
+	_, err := localstack.RunContainer(
+		ctx,
+		testcontainers.CustomizeRequest(testcontainers.GenericContainerRequest{
+			ContainerRequest: testcontainers.ContainerRequest{
+				Image:      "localstack/localstack:0.10.0",
+				Env:        map[string]string{"SERVICES": "s3,sqs"},
+				WaitingFor: wait.ForLog("Ready.").WithStartupTimeout(5 * time.Minute).WithOccurrence(1),
+			},
+		}),
+	)
+	if err == nil {
+		panic(err)
+	}
+
+	fmt.Println(err)
+
+	// Output:
+	// version=localstack/localstack:0.10.0. Testcontainers for Go does not support running LocalStack in legacy mode. Please use a version >= 0.11.0
+}

modules/localstack/localstack.go

@@ -61,7 +61,6 @@ func isVersion2(image string) bool {
 // RunContainer creates an instance of the LocalStack container type, being possible to pass a custom request and options:
 // - overrideReq: a function that can be used to override the default container request, usually used to set the image version, environment variables for localstack, etc.
 func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*LocalStackContainer, error) {
-	// defaultContainerRequest {
 	dockerHost := testcontainersdocker.ExtractDockerSocket(ctx)
 
 	req := testcontainers.ContainerRequest{
@@ -71,7 +70,6 @@ func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomize
 		ExposedPorts: []string{fmt.Sprintf("%d/tcp", defaultPort)},
 		Env:          map[string]string{},
 	}
-	// }
 
 	localStackReq := LocalStackContainerRequest{
 		GenericContainerRequest: testcontainers.GenericContainerRequest{