0
# Service Management
1

2
Tools for running services in development and production environments with process management, configuration handling, graceful shutdown, and monitoring capabilities.
3

4
## Capabilities
5

6
### ServiceRunner
7

8
Class for programmatically running nameko services with full control over lifecycle, configuration, and worker management.
9

10
```python { .api }
11
class ServiceRunner:
12
    """
13
    Programmatic service runner for managing nameko services.
14
    
15
    Parameters:
16
    - config: Configuration dictionary or path to config file
17
    """
18
    
19
    def __init__(self, config=None): ...
20
    
21
    def add_service(self, service_cls):
22
        """Add a service class to be run by this runner"""
23
    
24
    def start(self):
25
        """Start all registered services"""
26
    
27
    def stop(self):
28
        """Stop all services gracefully"""
29
    
30
    def wait(self):
31
        """Wait for all services to stop"""
32
    
33
    def kill(self):
34
        """Force kill all services"""
35
```
36

37
**Usage Example:**
38

39
```python
40
from nameko.runners import ServiceRunner
41

42
# Define your services
43
class UserService:
44
    name = "user_service"
45
    # ... service implementation
46

47
class OrderService:
48
    name = "order_service" 
49
    # ... service implementation
50

51
# Create and configure runner
52
config = {
53
    'AMQP_URI': 'amqp://guest:guest@localhost:5672//',
54
    'WEB_SERVER_ADDRESS': '0.0.0.0:8000',
55
    'MAX_WORKERS': 10
56
}
57

58
runner = ServiceRunner(config)
59
runner.add_service(UserService)
60
runner.add_service(OrderService)
61

62
# Start services
63
try:
64
    runner.start()
65
    runner.wait()  # Block until services stop
66
except KeyboardInterrupt:
67
    runner.stop()  # Graceful shutdown
68
    runner.wait()
69
```
70

71
### run_services Function
72

73
Convenience function for quickly running multiple services with shared configuration.
74

75
```python { .api }
76
def run_services(services, config=None):
77
    """
78
    Run multiple services with shared configuration.
79
    
80
    Parameters:
81
    - services: List of service classes to run
82
    - config: Configuration dictionary, file path, or None for defaults
83
    
84
    This function blocks until services are stopped (Ctrl+C or signal).
85
    """
86
```
87

88
**Usage Example:**
89

90
```python
91
from nameko.runners import run_services
92

93
# Simple service startup
94
if __name__ == '__main__':
95
    services = [UserService, OrderService, NotificationService]
96
    
97
    # Run with default configuration
98
    run_services(services)
99
    
100
    # Or with custom config
101
    config = {
102
        'AMQP_URI': 'amqp://user:pass@rabbitmq:5672//',
103
        'MAX_WORKERS': 20
104
    }
105
    run_services(services, config)
106
```
107

108
### Configuration Management
109

110
Comprehensive configuration system supporting environment variables, YAML files, and programmatic configuration.
111

112
**Configuration Sources:**
113

114
```python
115
# 1. Dictionary configuration
116
config = {
117
    'AMQP_URI': 'amqp://localhost:5672//',
118
    'WEB_SERVER_ADDRESS': '0.0.0.0:8000',
119
    'MAX_WORKERS': 10,
120
    'SERIALIZER': 'json'
121
}
122

123
# 2. YAML file configuration
124
# config.yaml
125
"""
126
AMQP_URI: 'amqp://localhost:5672//'
127
WEB_SERVER_ADDRESS: '0.0.0.0:8000'
128
MAX_WORKERS: 10
129
RPC_TIMEOUT: 30
130

131
DATABASE:
132
  host: localhost
133
  port: 5432
134
  name: myapp
135
"""
136

137
# 3. Environment variables (automatically loaded)
138
# NAMEKO_AMQP_URI=amqp://localhost:5672//
139
# NAMEKO_MAX_WORKERS=10
140
```
141

142
**Configuration Access in Services:**
143

144
```python
145
from nameko.dependency_providers import Config
146

147
class ConfigurableService:
148
    name = "configurable_service"
149
    
150
    config = Config()
151
    
152
    @rpc
153
    def get_database_config(self):
154
        # Access nested configuration
155
        db_host = self.config['DATABASE']['host']
156
        db_port = self.config['DATABASE']['port']
157
        
158
        return {
159
            'host': db_host,
160
            'port': db_port,
161
            'max_workers': self.config['MAX_WORKERS']
162
        }
163
    
164
    @rpc  
165
    def get_api_key(self):
166
        # Access with defaults
167
        api_key = self.config.get('API_KEY', 'default-key')
168
        return api_key
169
```
170

171
### Process Management
172

173
Advanced process management with worker pools, graceful shutdown, and signal handling.
174

175
**Worker Pool Configuration:**
176

177
```python
178
# Automatic worker scaling based on load
179
config = {
180
    'MAX_WORKERS': 50,           # Maximum workers per service
181
    'WORKER_POOL_SIZE': 10,      # Initial worker pool size
182
    'WORKER_THREADS': 1000,      # Thread pool size per worker
183
    'HEARTBEAT_INTERVAL': 30,    # Worker heartbeat interval
184
    'WORKER_TIMEOUT': 300        # Worker timeout in seconds
185
}
186

187
class ScalableService:
188
    name = "scalable_service"
189
    
190
    @rpc
191
    def cpu_intensive_task(self, data):
192
        # This will be distributed across worker pool
193
        return self._process_data(data)
194
```
195

196
**Graceful Shutdown Handling:**
197

198
```python
199
import signal
200
from nameko.runners import ServiceRunner
201

202
class ManagedServiceRunner:
203
    def __init__(self, services, config):
204
        self.runner = ServiceRunner(config)
205
        for service in services:
206
            self.runner.add_service(service)
207
        
208
        # Setup signal handlers for graceful shutdown
209
        signal.signal(signal.SIGTERM, self._handle_shutdown)
210
        signal.signal(signal.SIGINT, self._handle_shutdown)
211
    
212
    def _handle_shutdown(self, signum, frame):
213
        print(f"Received signal {signum}, shutting down gracefully...")
214
        self.runner.stop()
215
    
216
    def run(self):
217
        try:
218
            self.runner.start()
219
            self.runner.wait()
220
        except Exception as e:
221
            print(f"Error running services: {e}")
222
            self.runner.kill()  # Force shutdown on error
223
```
224

225
### Health Checks and Monitoring
226

227
Built-in health check endpoints and monitoring capabilities.
228

229
```python { .api }
230
# Health check service (automatically registered)
231
class HealthCheckService:
232
    name = "health_check"
233
    
234
    @http('GET', '/health')
235
    def health_check(self, request):
236
        """Standard health check endpoint"""
237
        return {
238
            'status': 'healthy',
239
            'timestamp': time.time(),
240
            'services': self._get_service_status()
241
        }
242
    
243
    @http('GET', '/metrics')
244
    def metrics(self, request):
245
        """Service metrics endpoint"""
246
        return {
247
            'active_workers': self._get_worker_count(),
248
            'processed_requests': self._get_request_count(),
249
            'memory_usage': self._get_memory_usage(),
250
            'uptime': self._get_uptime()
251
        }
252
```
253

254
### Development vs Production Configuration
255

256
Different configuration patterns for development and production environments.
257

258
**Development Configuration:**
259

260
```python
261
# development.yaml
262
AMQP_URI: 'amqp://guest:guest@localhost:5672//'
263
WEB_SERVER_ADDRESS: '127.0.0.1:8000'
264
MAX_WORKERS: 1  # Single worker for debugging
265
DEBUG: true
266
LOG_LEVEL: 'DEBUG'
267
RELOAD_ON_CHANGE: true  # Auto-reload on code changes
268
```
269

270
**Production Configuration:**
271

272
```python
273
# production.yaml  
274
AMQP_URI: 'amqp://user:password@rabbitmq-cluster:5672//'
275
WEB_SERVER_ADDRESS: '0.0.0.0:8000'
276
MAX_WORKERS: 50
277
DEBUG: false
278
LOG_LEVEL: 'INFO'
279

280
# Production-specific settings
281
WORKER_POOL_SIZE: 20
282
CONNECTION_POOL_SIZE: 50
283
RPC_TIMEOUT: 60
284
HEARTBEAT_INTERVAL: 60
285

286
# Security settings
287
SSL_ENABLED: true
288
AUTH_REQUIRED: true
289
```
290

291
### Command Line Interface
292

293
Built-in CLI tools for service management and development.
294

295
```bash
296
# Run services from command line
297
nameko run myapp.services
298

299
# Run with specific config
300
nameko run myapp.services --config production.yaml
301

302
# Run in development mode with auto-reload
303
nameko run myapp.services --development
304

305
# Shell for testing services
306
nameko shell --config config.yaml
307

308
# Show service information
309
nameko show myapp.services
310
```
311

312
### Docker and Container Integration
313

314
Configuration patterns for containerized deployments.
315

316
**Dockerfile Example:**
317

318
```dockerfile
319
FROM python:3.9
320
WORKDIR /app
321
COPY requirements.txt .
322
RUN pip install -r requirements.txt
323
COPY . .
324

325
# Use environment variables for configuration
326
ENV NAMEKO_AMQP_URI=amqp://rabbitmq:5672//
327
ENV NAMEKO_MAX_WORKERS=10
328

329
CMD ["nameko", "run", "myapp.services"]
330
```
331

332
**Docker Compose Example:**
333

334
```yaml
335
version: '3.8'
336
services:
337
  rabbitmq:
338
    image: rabbitmq:3-management
339
    ports:
340
      - "5672:5672"
341
      - "15672:15672"
342
  
343
  user-service:
344
    build: .
345
    environment:
346
      - NAMEKO_AMQP_URI=amqp://rabbitmq:5672//
347
      - NAMEKO_WEB_SERVER_ADDRESS=0.0.0.0:8000
348
    ports:
349
      - "8000:8000"
350
    depends_on:
351
      - rabbitmq
352
    command: nameko run services.user_service
353
  
354
  order-service:
355
    build: .
356
    environment:
357
      - NAMEKO_AMQP_URI=amqp://rabbitmq:5672//
358
    depends_on:
359
      - rabbitmq
360
    command: nameko run services.order_service
361
```