0
# Configuration
1
2
LocalStack's configuration system provides comprehensive environment-based configuration management with profile support, directory management, platform detection, and extensive customization options for services and runtime behavior.
3
4
## Capabilities
5
6
### Configuration Functions
7
8
Core functions for loading and parsing configuration from environment variables and profiles.
9
10
```python { .api }
11
def load_environment(profiles: str = None, env=os.environ) -> List[str]:
12
"""
13
Load configuration from profiles and environment variables.
14
15
Args:
16
profiles: Comma-separated list of profile names to load
17
env: Environment dictionary (defaults to os.environ)
18
19
Returns:
20
List of loaded profile names
21
22
Location: localstack.config
23
"""
24
25
def parse_boolean_env(env_var_name: str) -> bool | None:
26
"""
27
Parse boolean environment variables using LocalStack conventions.
28
29
Args:
30
env_var_name: Name of environment variable to parse
31
32
Returns:
33
True for TRUE_STRINGS ("1", "true", "True")
34
False for FALSE_STRINGS ("0", "false", "False")
35
None if variable not set or invalid value
36
37
Location: localstack.config
38
"""
39
40
def is_env_true(env_var_name: str) -> bool:
41
"""
42
Check if environment variable is set to a true value.
43
44
Args:
45
env_var_name: Name of environment variable
46
47
Returns:
48
True if variable equals TRUE_STRINGS, False otherwise
49
50
Location: localstack.config
51
"""
52
53
def is_env_not_false(env_var_name: str) -> bool:
54
"""
55
Check if environment variable is NOT explicitly set to false.
56
57
Args:
58
env_var_name: Name of environment variable
59
60
Returns:
61
True unless variable explicitly equals FALSE_STRINGS
62
63
Location: localstack.config
64
"""
65
66
def eval_log_type(env_var_name: str) -> str | bool:
67
"""
68
Parse logging-specific environment variable with boolean fallback.
69
70
Args:
71
env_var_name: Name of logging environment variable
72
73
Returns:
74
String log level or boolean based on content
75
76
Location: localstack.config
77
"""
78
```
79
80
### Platform Detection
81
82
Functions for detecting the runtime environment and platform capabilities.
83
84
```python { .api }
85
def is_linux() -> bool:
86
"""Check if running on Linux platform"""
87
88
def is_macos() -> bool:
89
"""Check if running on macOS platform"""
90
91
def is_windows() -> bool:
92
"""Check if running on Windows platform"""
93
94
def is_wsl() -> bool:
95
"""Check if running inside Windows Subsystem for Linux"""
96
97
def in_docker() -> bool:
98
"""Check if LocalStack is running inside a Docker container"""
99
100
def ping(host: str) -> bool:
101
"""
102
Test network connectivity to a host.
103
104
Args:
105
host: Hostname or IP address to ping
106
107
Returns:
108
True if host is reachable, False otherwise
109
"""
110
```
111
112
### Directory Management
113
114
Comprehensive directory structure management for LocalStack's file organization.
115
116
```python { .api }
117
class Directories:
118
"""
119
LocalStack directory structure management.
120
121
Location: localstack.config.Directories
122
"""
123
124
static_libs: str # Static binaries and libraries
125
var_libs: str # Runtime computed libraries
126
cache: str # Persistent cache storage
127
tmp: str # Temporary files
128
mounted_tmp: str # Shared temporary files (Docker mounts)
129
functions: str # Lambda container communication
130
data: str # LocalStack state and pods
131
config: str # Configuration files
132
init: str # Initialization/provisioning scripts
133
logs: str # Log files
134
135
@classmethod
136
def defaults() -> 'Directories':
137
"""
138
Get default directory paths based on environment.
139
140
Returns:
141
Directories instance with platform-appropriate defaults
142
"""
143
144
@classmethod
145
def for_container() -> 'Directories':
146
"""
147
Get directory paths optimized for container environments.
148
149
Returns:
150
Directories instance with container-specific paths
151
"""
152
153
@classmethod
154
def for_host() -> 'Directories':
155
"""
156
Get directory paths for host-mode execution.
157
158
Returns:
159
Directories instance for direct host execution
160
"""
161
162
@classmethod
163
def for_cli() -> 'Directories':
164
"""
165
Get directory paths optimized for CLI operations.
166
167
Returns:
168
Directories instance for CLI usage
169
"""
170
171
def mkdirs(self) -> None:
172
"""
173
Create all directories in the structure.
174
Creates parent directories as needed, ignores existing directories.
175
"""
176
```
177
178
### Core Configuration Variables
179
180
#### Runtime Control
181
182
Essential variables controlling LocalStack's basic operation and behavior.
183
184
```python { .api }
185
# Profile and environment
186
CONFIG_PROFILE: str # Active configuration profile name
187
CONFIG_DIR: str # Configuration directory (~/.localstack)
188
VOLUME_DIR: str # LocalStack volume directory
189
DATA_DIR: str # Data directory override
190
PERSISTENCE: bool # Enable state persistence across restarts
191
192
# Debugging and logging
193
DEBUG: bool # Enable debug mode with verbose logging
194
LS_LOG: str # Logging level (trace-internal, trace, debug, info, warn, error)
195
```
196
197
#### Docker and Runtime Configuration
198
199
Settings for Docker execution and container management.
200
201
```python { .api }
202
# Docker configuration
203
DOCKER_SOCK: str # Docker socket path (/var/run/docker.sock)
204
DOCKER_CMD: str # Docker command executable
205
DOCKER_FLAGS: str # Additional Docker CLI flags
206
MAIN_CONTAINER_NAME: str # Container name (default: localstack-main)
207
MAIN_DOCKER_NETWORK: str # Docker network name
208
```
209
210
#### Service Configuration
211
212
Settings controlling AWS service emulation and behavior.
213
214
```python { .api }
215
# Service management
216
SERVICES: str # Enabled services (deprecated, use EAGER_SERVICE_LOADING)
217
EAGER_SERVICE_LOADING: bool # Preload services on startup
218
STRICT_SERVICE_LOADING: bool # Strict service loading validation
219
220
# Network and gateway
221
GATEWAY_LISTEN: str # Gateway listen addresses (comma-separated)
222
EDGE_PORT: int # Main LocalStack port (default: 4566)
223
USE_SSL: bool # Enable SSL/TLS for endpoints
224
```
225
226
#### Lambda Configuration
227
228
Comprehensive settings for Lambda service emulation and execution.
229
230
```python { .api }
231
# Lambda execution
232
LAMBDA_EXECUTOR: str # Lambda executor type (docker, local)
233
LAMBDA_RUNTIME_EXECUTOR: str # Runtime executor implementation
234
LAMBDA_DOCKER_NETWORK: str # Docker network for Lambda containers
235
LAMBDA_DOCKER_DNS: str # DNS settings for Lambda containers
236
LAMBDA_DOCKER_FLAGS: str # Additional Docker flags for Lambda
237
238
# Lambda container management
239
LAMBDA_REMOVE_CONTAINERS: bool # Auto-remove Lambda containers after execution
240
LAMBDA_KEEPALIVE_MS: int # Container keepalive time in milliseconds
241
```
242
243
#### Service-Specific Settings
244
245
Fine-grained configuration for individual AWS service behaviors.
246
247
```python { .api }
248
# Error simulation
249
KINESIS_ERROR_PROBABILITY: float # Kinesis error simulation (0.0-1.0)
250
DYNAMODB_ERROR_PROBABILITY: float # DynamoDB error simulation (0.0-1.0)
251
252
# Service behavior
253
SQS_ENDPOINT_STRATEGY: str # SQS endpoint strategy (domain, path, off)
254
S3_SKIP_SIGNATURE_VALIDATION: bool # Skip S3 signature validation
255
256
# DNS configuration
257
DNS_ADDRESS: str # DNS server bind address
258
DNS_PORT: int # DNS server port (default: 53)
259
```
260
261
### Configuration Loading
262
263
Profile-based configuration system supporting multiple environments and inheritance.
264
265
```python { .api }
266
# Profile system
267
def load_profile(profile_name: str) -> dict[str, str]:
268
"""
269
Load configuration from named profile.
270
271
Profile files located at: ~/.localstack/profiles/{profile_name}
272
Format: KEY=VALUE pairs, one per line
273
Supports variable substitution and inheritance
274
275
Args:
276
profile_name: Name of profile to load
277
278
Returns:
279
Dictionary of configuration key-value pairs
280
"""
281
282
# Configuration precedence (highest to lowest):
283
# 1. Environment variables
284
# 2. Command line arguments
285
# 3. Profile files (~/.localstack/profiles/<profile>)
286
# 4. Default config file (~/.localstack/config)
287
# 5. Built-in defaults
288
```
289
290
Usage examples:
291
292
```bash
293
# Profile file: ~/.localstack/profiles/development
294
DEBUG=1
295
LS_LOG=debug
296
SERVICES=s3,lambda,dynamodb
297
LAMBDA_EXECUTOR=docker
298
PERSISTENCE=1
299
300
# Profile file: ~/.localstack/profiles/testing
301
DEBUG=0
302
LS_LOG=info
303
SERVICES=s3,sqs,sns
304
LAMBDA_EXECUTOR=local
305
KINESIS_ERROR_PROBABILITY=0.1
306
```
307
308
```python
309
# Loading profiles programmatically
310
from localstack.config import load_environment
311
312
# Load single profile
313
profiles = load_environment("development")
314
315
# Load multiple profiles (later profiles override earlier ones)
316
profiles = load_environment("base,development,local")
317
```
318
319
## Constants and Defaults
320
321
### Version Information
322
323
```python { .api }
324
# Version constants
325
VERSION: str # LocalStack version string
326
LOCALSTACK_MAVEN_VERSION: str # Java utilities version
327
```
328
329
### Default Values
330
331
```python { .api }
332
# Network defaults
333
DEFAULT_PORT_EDGE: int = 4566 # Main LocalStack port
334
LOCALHOST: str = "localhost" # Localhost hostname
335
LOCALHOST_IP: str = "127.0.0.1" # Localhost IP address
336
BIND_HOST: str = "0.0.0.0" # Default bind address
337
338
# Directory defaults
339
DEFAULT_VOLUME_DIR: str = "/var/lib/localstack" # Container volume directory
340
DEFAULT_AWS_ACCOUNT_ID: str = "000000000000" # Default AWS account ID
341
```
342
343
### Content Types
344
345
```python { .api }
346
# HTTP content types
347
APPLICATION_JSON: str = "application/json"
348
APPLICATION_XML: str = "application/xml"
349
APPLICATION_AMZ_JSON_1_0: str = "application/x-amz-json-1.0"
350
APPLICATION_AMZ_JSON_1_1: str = "application/x-amz-json-1.1"
351
TEXT_XML: str = "text/xml"
352
```
353
354
### Boolean Parsing
355
356
```python { .api }
357
# Boolean value parsing
358
TRUE_STRINGS: tuple[str, ...] = ("1", "true", "True")
359
FALSE_STRINGS: tuple[str, ...] = ("0", "false", "False")
360
```
361
362
### Log Levels
363
364
```python { .api }
365
# Logging configuration
366
LOG_LEVELS: tuple[str, ...] = (
367
"trace-internal", "trace", "debug",
368
"info", "warn", "error", "warning"
369
)
370
TRACE_LOG_LEVELS: list[str] = ["trace", "trace-internal"]
371
```
372
373
### Docker Images
374
375
```python { .api }
376
# Docker image names
377
DOCKER_IMAGE_NAME: str = "localstack/localstack"
378
DOCKER_IMAGE_NAME_PRO: str = "localstack/localstack-pro"
379
DOCKER_IMAGE_NAME_FULL: str = "localstack/localstack-full"
380
```
381
382
### API Endpoints
383
384
```python { .api }
385
# External service endpoints
386
API_ENDPOINT: str = "https://api.localstack.cloud/v1"
387
ANALYTICS_API: str = "https://analytics.localstack.cloud/v1"
388
ASSETS_ENDPOINT: str = "https://assets.localstack.cloud"
389
ARTIFACTS_REPO: str = "https://github.com/localstack/localstack-artifacts"
390
```
391
392
## Configuration Examples
393
394
### Basic Development Setup
395
396
```bash
397
# Environment variables for local development
398
export DEBUG=1
399
export LS_LOG=debug
400
export SERVICES=s3,lambda,dynamodb,sqs
401
export LAMBDA_EXECUTOR=docker
402
export PERSISTENCE=1
403
export DATA_DIR=/tmp/localstack-data
404
```
405
406
### Production-like Configuration
407
408
```bash
409
# Minimal logging and specific services
410
export DEBUG=0
411
export LS_LOG=info
412
export EAGER_SERVICE_LOADING=0
413
export STRICT_SERVICE_LOADING=1
414
export USE_SSL=1
415
export GATEWAY_LISTEN=0.0.0.0:4566,0.0.0.0:443
416
```
417
418
### Testing Configuration
419
420
```bash
421
# Error simulation for chaos testing
422
export KINESIS_ERROR_PROBABILITY=0.05
423
export DYNAMODB_ERROR_PROBABILITY=0.02
424
export S3_SKIP_SIGNATURE_VALIDATION=1
425
export LAMBDA_REMOVE_CONTAINERS=1
426
```
427
428
### Custom Docker Network
429
430
```bash
431
# Custom networking setup
432
export MAIN_DOCKER_NETWORK=my-app-network
433
export LAMBDA_DOCKER_NETWORK=my-app-network
434
export LAMBDA_DOCKER_DNS=8.8.8.8
435
export DNS_ADDRESS=0.0.0.0
436
```