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
```