0
# LocalStack
1
2
A fully functional local AWS cloud stack that emulates AWS services for local development and testing. LocalStack provides a comprehensive AWS cloud emulator running in a single container, supporting 45+ AWS services with high fidelity APIs, making it ideal for developing and testing cloud applications without the cost and complexity of real AWS infrastructure.
3
4
## Package Information
5
6
- **Package Name**: localstack-core
7
- **Language**: Python
8
- **Installation**: `pip install localstack-core`
9
- **Requirements**: Python >=3.9
10
11
## Core Imports
12
13
For CLI operations:
14
15
```python
16
from localstack.cli.main import main
17
```
18
19
For configuration access:
20
21
```python
22
from localstack import config
23
from localstack.config import Directories
24
```
25
26
For AWS client connectivity:
27
28
```python
29
from localstack.aws.connect import connect_to
30
```
31
32
## Basic Usage
33
34
```python
35
# Starting LocalStack programmatically
36
from localstack.cli.main import main
37
import sys
38
39
# Start LocalStack in Docker (equivalent to 'localstack start')
40
sys.argv = ['localstack', 'start', '--docker']
41
main()
42
43
# Using LocalStack's AWS client factory
44
from localstack.aws.connect import connect_to
45
import boto3
46
47
# Connect to LocalStack services using the factory
48
s3_client = connect_to().s3
49
dynamodb = connect_to().dynamodb
50
51
# Or use standard boto3 with LocalStack endpoint
52
s3 = boto3.client(
53
's3',
54
endpoint_url='http://localhost:4566',
55
aws_access_key_id='test',
56
aws_secret_access_key='test',
57
region_name='us-east-1'
58
)
59
60
# Create a bucket and upload a file
61
s3.create_bucket(Bucket='my-test-bucket')
62
s3.put_object(Bucket='my-test-bucket', Key='test.txt', Body=b'Hello LocalStack!')
63
64
# List buckets to verify
65
response = s3.list_buckets()
66
print(f"Buckets: {[b['Name'] for b in response['Buckets']]}")
67
```
68
69
CLI usage:
70
71
```bash
72
# Start LocalStack in Docker
73
localstack start
74
75
# Start with custom configuration
76
localstack start --docker -e DEBUG=1 -e SERVICES=s3,dynamodb
77
78
# Check service status
79
localstack status services
80
81
# View logs
82
localstack logs -f
83
84
# Stop LocalStack
85
localstack stop
86
```
87
88
## Architecture
89
90
LocalStack follows a modular, plugin-based architecture:
91
92
- **Container Runtime**: Runs in Docker with configurable networking and volumes
93
- **Gateway System**: Routes AWS API requests to appropriate service providers
94
- **Service Providers**: Pluggable implementations of AWS services via the ASF (AWS Service Framework)
95
- **Plugin System**: Extensible architecture for custom services and CLI commands
96
- **Configuration System**: Environment-based configuration with profile support
97
- **Testing Framework**: Integrated pytest fixtures and snapshot testing capabilities
98
99
The AWS Service Framework (ASF) enables high-fidelity AWS API emulation by using AWS service specifications to generate skeleton services that can be extended with custom implementations.
100
101
## Capabilities
102
103
### CLI Commands
104
105
Comprehensive command-line interface for managing LocalStack lifecycle, configuration, and package management.
106
107
```python { .api }
108
# Entry point function
109
def main() -> None:
110
"""Main CLI entry point with profile and environment loading"""
111
112
# Core lifecycle commands
113
localstack start [--docker|--host] [--detached] [options...]
114
localstack stop
115
localstack restart
116
localstack logs [-f] [-n N]
117
localstack wait [-t N]
118
localstack ssh
119
```
120
121
[CLI Commands](./cli-commands.md)
122
123
### Configuration System
124
125
Environment-based configuration management with profiles, directory management, and platform detection.
126
127
```python { .api }
128
# Configuration functions
129
def load_environment(profiles: str = None, env=os.environ) -> list[str]:
130
"""Load configuration from profiles and environment variables"""
131
132
def parse_boolean_env(env_var_name: str) -> bool | None:
133
"""Parse boolean environment variables with LocalStack conventions"""
134
135
def is_env_true(env_var_name: str) -> bool:
136
"""Check if environment variable is set to true"""
137
138
# Directory management
139
class Directories:
140
static_libs: str
141
var_libs: str
142
cache: str
143
tmp: str
144
data: str
145
config: str
146
logs: str
147
148
@classmethod
149
def defaults() -> 'Directories':
150
"""Get default directory paths"""
151
152
def mkdirs(self) -> None:
153
"""Create all directories"""
154
```
155
156
[Configuration](./configuration.md)
157
158
### AWS Services
159
160
Emulation of 45+ AWS services through a pluggable provider system with high-fidelity APIs.
161
162
```python { .api }
163
# Service management
164
class ServiceManager:
165
def get_service(self, name: str) -> Service | None:
166
"""Get service instance by name"""
167
168
def is_running(self, name: str) -> bool:
169
"""Check if service is running"""
170
171
def get_states(self) -> dict[str, ServiceState]:
172
"""Get status of all services"""
173
174
# Service provider decorator
175
def aws_provider(
176
api: str = None,
177
name: str = "default",
178
should_load: callable = None
179
) -> callable:
180
"""Decorator for registering AWS service providers"""
181
182
# Service states
183
class ServiceState(Enum):
184
UNKNOWN = "unknown"
185
AVAILABLE = "available"
186
RUNNING = "running"
187
ERROR = "error"
188
```
189
190
[AWS Services](./aws-services.md)
191
192
### Utilities and Testing
193
194
Comprehensive utility modules for file operations, networking, async operations, and integrated testing framework.
195
196
```python { .api }
197
# File utilities
198
def save_file(file_path: str, content: str, append: bool = False) -> None:
199
"""Save content to file"""
200
201
def load_file(file_path: str, default=None, mode: str = None) -> str:
202
"""Load file content with optional default"""
203
204
# Network utilities
205
def get_free_tcp_port() -> int:
206
"""Get available TCP port"""
207
208
def is_port_open(port_or_url: str | int, http_path: str = None) -> bool:
209
"""Check if port is open"""
210
211
# Async utilities
212
async def run_sync(func: callable, *args, **kwargs):
213
"""Run synchronous function in async context"""
214
215
def run_async(coro, loop=None):
216
"""Run async coroutine in sync context"""
217
```
218
219
[Utilities & Testing](./utils-testing.md)
220
221
### Plugins and Extensions
222
223
Extensible plugin system for custom CLI commands, service providers, and runtime extensions.
224
225
```python { .api }
226
# CLI plugin system
227
class LocalstackCliPlugin:
228
namespace: str = "localstack.plugins.cli"
229
230
def attach(self, cli) -> None:
231
"""Attach commands to CLI"""
232
233
# Service plugins
234
class ServicePlugin:
235
service: str
236
api: str
237
238
def create_service(self) -> Service:
239
"""Create service instance"""
240
241
# Plugin loading
242
def load_cli_plugins(cli) -> None:
243
"""Load all CLI plugins from namespace"""
244
```
245
246
[Plugins & Extensions](./plugins-extensions.md)
247
248
## Types
249
250
```python { .api }
251
class Service:
252
"""LocalStack service instance"""
253
254
def __init__(
255
self,
256
name: str,
257
start: callable = None,
258
check: callable = None,
259
skeleton=None,
260
active: bool = False,
261
stop: callable = None
262
): ...
263
264
def start(self, asynchronous: bool = True) -> None:
265
"""Start the service"""
266
267
def stop(self) -> None:
268
"""Stop the service"""
269
270
def check(self, expect_shutdown: bool = False, print_error: bool = False) -> bool:
271
"""Check service health"""
272
273
def is_enabled(self) -> bool:
274
"""Check if service is enabled"""
275
276
class ServiceState(Enum):
277
"""Service lifecycle states"""
278
UNKNOWN = "unknown"
279
AVAILABLE = "available"
280
DISABLED = "disabled"
281
STARTING = "starting"
282
RUNNING = "running"
283
STOPPING = "stopping"
284
STOPPED = "stopped"
285
ERROR = "error"
286
```