0
# Container Configuration
1
2
Core functionality for creating and configuring LocalStack containers with service specifications and Docker image management.
3
4
## Capabilities
5
6
### Main Constructor
7
8
Creates a LocalStack container with the specified Docker image. Automatically detects version compatibility and configures appropriate behavior.
9
10
```java { .api }
11
/**
12
* Creates a LocalStack container with the specified Docker image
13
* @param dockerImageName Docker image name for LocalStack (localstack/localstack or localstack/localstack-pro)
14
*/
15
public LocalStackContainer(DockerImageName dockerImageName);
16
```
17
18
**Usage Example:**
19
20
```java
21
import org.testcontainers.containers.localstack.LocalStackContainer;
22
import org.testcontainers.utility.DockerImageName;
23
24
// Use specific LocalStack version
25
DockerImageName localstackImage = DockerImageName.parse("localstack/localstack:3.5.0");
26
LocalStackContainer localstack = new LocalStackContainer(localstackImage);
27
28
// Use LocalStack Pro
29
DockerImageName localstackProImage = DockerImageName.parse("localstack/localstack-pro:3.5.0");
30
LocalStackContainer localstackPro = new LocalStackContainer(localstackProImage);
31
```
32
33
### Deprecated Constructors
34
35
Legacy constructors maintained for backward compatibility.
36
37
```java { .api }
38
/**
39
* @deprecated use LocalStackContainer(DockerImageName) instead
40
*/
41
@Deprecated
42
public LocalStackContainer();
43
44
/**
45
* @deprecated use LocalStackContainer(DockerImageName) instead
46
* @param version LocalStack version string
47
*/
48
@Deprecated
49
public LocalStackContainer(String version);
50
51
/**
52
* @deprecated use LocalStackContainer(DockerImageName) instead
53
* @param dockerImageName Docker image name
54
* @param useLegacyMode whether to use legacy mode (different ports per service)
55
*/
56
@Deprecated
57
public LocalStackContainer(DockerImageName dockerImageName, boolean useLegacyMode);
58
```
59
60
### Service Configuration with Service Enum
61
62
Configure AWS services using the predefined Service enumeration.
63
64
```java { .api }
65
/**
66
* Declare a set of simulated AWS services using predefined Service enum values
67
* @param services one or more Service enum values
68
* @return this container object for method chaining
69
*/
70
public LocalStackContainer withServices(Service... services);
71
```
72
73
**Usage Examples:**
74
75
```java
76
// Configure single service
77
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
78
.withServices(Service.S3);
79
80
// Configure multiple services
81
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
82
.withServices(Service.S3, Service.SQS, Service.LAMBDA, Service.DYNAMODB);
83
84
// All major services
85
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
86
.withServices(
87
Service.S3,
88
Service.LAMBDA,
89
Service.SQS,
90
Service.SNS,
91
Service.DYNAMODB,
92
Service.KINESIS,
93
Service.CLOUDFORMATION,
94
Service.IAM,
95
Service.STS
96
);
97
```
98
99
### Service Configuration with EnabledService Interface
100
101
Configure AWS services using the EnabledService interface, allowing for custom service names.
102
103
```java { .api }
104
/**
105
* Declare a set of simulated AWS services using EnabledService interface
106
* @param services one or more EnabledService instances
107
* @return this container object for method chaining
108
*/
109
public LocalStackContainer withServices(EnabledService... services);
110
```
111
112
**Usage Examples:**
113
114
```java
115
// Mix predefined and custom services
116
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
117
.withServices(
118
Service.S3,
119
Service.SQS,
120
EnabledService.named("events"),
121
EnabledService.named("logs")
122
);
123
124
// All custom services
125
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
126
.withServices(
127
EnabledService.named("s3"),
128
EnabledService.named("lambda"),
129
EnabledService.named("apigateway")
130
);
131
```
132
133
### Version Detection and Compatibility
134
135
The container automatically detects LocalStack version and configures appropriate behavior:
136
137
- **Legacy Mode**: Versions < 0.11.0 use different ports for each service
138
- **Modern Mode**: Versions >= 0.11.0 use single port (4566) for all services
139
- **Services Environment Variable**: Required for versions < 0.13.0
140
- **Version 2**: Additional features for LocalStack 2.0+
141
142
```java { .api }
143
// Internal version detection methods (static utility)
144
static boolean shouldRunInLegacyMode(String version);
145
```
146
147
### Constants
148
149
```java { .api }
150
public static final int PORT = 4566;
151
152
/**
153
* @deprecated use specific version in DockerImageName instead
154
*/
155
@Deprecated
156
public static final String VERSION = "0.11.2";
157
```
158
159
### Environment Variable Support
160
161
LocalStack supports configuration via environment variables. Use the inherited `withEnv()` method:
162
163
```java
164
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
165
.withServices(Service.S3)
166
.withEnv("DEBUG", "1")
167
.withEnv("LAMBDA_EXECUTOR", "docker")
168
.withEnv("DOCKER_HOST", "unix:///var/run/docker.sock");
169
```
170
171
### Network Configuration
172
173
The container automatically handles hostname resolution:
174
175
- **Without custom network**: Uses container host address
176
- **With custom network**: Uses network aliases for inter-container communication
177
- **Manual override**: Set `LOCALSTACK_HOST` environment variable manually if needed
178
179
```java
180
Network network = Network.newNetwork();
181
182
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
183
.withServices(Service.S3)
184
.withNetwork(network)
185
.withNetworkAliases("localstack");
186
```