0
# Docker Integration
1

2
Automated Docker and Docker Compose integration for LangGraph applications. Provides capability detection, file generation, and orchestration support for development and production deployments.
3

4
## Capabilities
5

6
### Docker Capability Detection
7

8
Detect available Docker and Docker Compose features on the system.
9

10
```python { .api }
11
def check_capabilities(runner) -> DockerCapabilities
12
```
13

14
**Purpose**: Detect Docker and Docker Compose capabilities and versions
15
**Parameters**:
16
- `runner`: Execution runner context for subprocess commands
17
**Returns**: DockerCapabilities named tuple with detected features
18

19
```python { .api }
20
class DockerCapabilities(NamedTuple):
21
    docker: bool
22
    compose: bool
23
    buildx: bool
24
    version: str
25
```
26

27
**DockerCapabilities Properties:**
28
- **docker**: Docker CLI availability
29
- **compose**: Docker Compose availability (v2+ preferred)
30
- **buildx**: Docker Buildx multi-platform build support
31
- **version**: Docker version string
32

33
**Usage Examples:**
34

35
```python
36
from langgraph_cli.docker import check_capabilities
37
from langgraph_cli.exec import Runner
38

39
with Runner() as runner:
40
    caps = check_capabilities(runner)
41

42
    if caps.docker:
43
        print(f"Docker {caps.version} available")
44

45
    if caps.compose:
46
        print("Docker Compose available")
47

48
    if caps.buildx:
49
        print("Multi-platform builds supported")
50
```
51

52
### Docker Compose Generation
53

54
Generate Docker Compose YAML files from configuration and runtime parameters.
55

56
```python { .api }
57
def compose(
58
    capabilities: DockerCapabilities,
59
    image: str,
60
    config: Config,
61
    port: int = DEFAULT_PORT,
62
    docker_compose: Optional[pathlib.Path] = None,
63
    watch: bool = False,
64
    debugger_port: Optional[int] = None,
65
    debugger_base_url: Optional[str] = None,
66
    postgres_uri: Optional[str] = None
67
) -> str
68
```
69

70
**Purpose**: Generate complete Docker Compose YAML for LangGraph deployment
71
**Parameters**:
72
- `capabilities` (DockerCapabilities): Docker system capabilities
73
- `image` (str): Docker image name to deploy
74
- `config` (Config): LangGraph configuration object
75
- `port` (int): Host port to expose (default: 8123)
76
- `docker_compose` (Optional[pathlib.Path]): Additional compose file to merge
77
- `watch` (bool): Enable file watching for development
78
- `debugger_port` (Optional[int]): Port for debugger UI
79
- `debugger_base_url` (Optional[str]): Base URL for debugger API access
80
- `postgres_uri` (Optional[str]): Custom PostgreSQL connection string
81
**Returns**: Complete Docker Compose YAML as string
82

83
**Usage Examples:**
84

85
```python
86
from langgraph_cli.docker import compose, check_capabilities
87
from langgraph_cli.config import validate_config_file
88
from langgraph_cli.exec import Runner
89
import pathlib
90

91
# Load configuration and check capabilities
92
config = validate_config_file(pathlib.Path("langgraph.json"))
93

94
with Runner() as runner:
95
    capabilities = check_capabilities(runner)
96

97
    # Generate compose file for production
98
    compose_yaml = compose(
99
        capabilities=capabilities,
100
        image="my-app:latest",
101
        config=config,
102
        port=8080
103
    )
104

105
    # Generate compose file for development with debugging
106
    dev_compose_yaml = compose(
107
        capabilities=capabilities,
108
        image="my-app:dev",
109
        config=config,
110
        port=2024,
111
        watch=True,
112
        debugger_port=8081,
113
        debugger_base_url="http://localhost:2024"
114
    )
115

116
    # Generate with additional services
117
    full_compose_yaml = compose(
118
        capabilities=capabilities,
119
        image="my-app:latest",
120
        config=config,
121
        docker_compose=pathlib.Path("docker-compose.services.yml"),
122
        postgres_uri="postgresql://user:pass@postgres:5432/db"
123
    )
124
```
125

126
### YAML Utilities
127

128
Convert Python data structures to properly formatted YAML.
129

130
```python { .api }
131
def dict_to_yaml(d: dict, *, indent: int = 0) -> str
132
```
133

134
**Purpose**: Convert dictionary to YAML format with proper indentation
135
**Parameters**:
136
- `d` (dict): Dictionary to convert to YAML
137
- `indent` (int): Base indentation level (default: 0)
138
**Returns**: YAML string representation
139

140
**Usage Examples:**
141

142
```python
143
from langgraph_cli.docker import dict_to_yaml
144

145
# Convert configuration to YAML
146
config_dict = {
147
    "services": {
148
        "app": {
149
            "image": "my-app:latest",
150
            "ports": ["8080:8080"],
151
            "environment": {
152
                "LOG_LEVEL": "INFO"
153
            }
154
        }
155
    }
156
}
157

158
yaml_output = dict_to_yaml(config_dict)
159
print(yaml_output)
160
# Output:
161
# services:
162
#   app:
163
#     image: my-app:latest
164
#     ports:
165
#       - "8080:8080"
166
#     environment:
167
#       LOG_LEVEL: INFO
168
```
169

170
## Docker Compose Templates
171

172
The CLI generates different Docker Compose configurations based on use case:
173

174
### Basic Production Deployment
175

176
```yaml
177
version: '3.8'
178
services:
179
  langgraph-api:
180
    image: my-app:latest
181
    ports:
182
      - "8123:8000"
183
    environment:
184
      - PORT=8000
185
      - HOST=0.0.0.0
186
    healthcheck:
187
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
188
      interval: 30s
189
      timeout: 10s
190
      retries: 3
191
```
192

193
### Development with Debugging
194

195
```yaml
196
version: '3.8'
197
services:
198
  langgraph-api:
199
    image: my-app:dev
200
    ports:
201
      - "2024:8000"
202
      - "8081:8001"  # debugger port
203
    environment:
204
      - PORT=8000
205
      - HOST=0.0.0.0
206
      - DEBUGGER_PORT=8001
207
    volumes:
208
      - ./src:/app/src:ro  # watch mode
209
    develop:
210
      watch:
211
        - action: rebuild
212
          path: ./src
213
```
214

215
### Production with PostgreSQL
216

217
```yaml
218
version: '3.8'
219
services:
220
  langgraph-api:
221
    image: my-app:latest
222
    ports:
223
      - "8123:8000"
224
    environment:
225
      - PORT=8000
226
      - HOST=0.0.0.0
227
      - DATABASE_URL=postgresql://postgres:password@postgres:5432/langgraph
228
    depends_on:
229
      postgres:
230
        condition: service_healthy
231

232
  postgres:
233
    image: postgres:15
234
    environment:
235
      - POSTGRES_USER=postgres
236
      - POSTGRES_PASSWORD=password
237
      - POSTGRES_DB=langgraph
238
    volumes:
239
      - postgres_data:/var/lib/postgresql/data
240
    healthcheck:
241
      test: ["CMD-SHELL", "pg_isready -U postgres"]
242
      interval: 5s
243
      timeout: 5s
244
      retries: 5
245

246
volumes:
247
  postgres_data:
248
```
249

250
## Multi-Platform Support
251

252
Docker integration supports multi-platform builds using Docker Buildx:
253

254
### Platform Detection
255

256
The system automatically detects Buildx support and enables multi-platform builds when available:
257

258
```python
259
# Capability detection includes Buildx support
260
capabilities = check_capabilities(runner)
261
if capabilities.buildx:
262
    # Multi-platform builds available
263
    platforms = ["linux/amd64", "linux/arm64"]
264
```
265

266
### Build Commands
267

268
Generated Docker commands support platform specification:
269

270
```bash
271
# Single platform
272
docker build -t my-app:latest .
273

274
# Multi-platform with Buildx
275
docker buildx build --platform linux/amd64,linux/arm64 -t my-app:latest .
276
```
277

278
## File Generation Workflow
279

280
The CLI follows this workflow for Docker file generation:
281

282
1. **Capability Detection**: Check Docker, Compose, and Buildx availability
283
2. **Configuration Validation**: Validate langgraph.json configuration
284
3. **Dockerfile Generation**: Create Dockerfile from configuration and templates
285
4. **Compose Generation**: Create docker-compose.yml with services and networking
286
5. **Additional Files**: Generate .dockerignore, environment files, and health checks
287

288
### Generated Files
289

290
- **Dockerfile**: Multi-stage build with Python/Node.js setup
291
- **docker-compose.yml**: Service orchestration and networking
292
- **.dockerignore**: Optimized build context exclusions
293
- **docker-compose.override.yml**: Development-specific overrides (when applicable)
294

295
## Environment Integration
296

297
Docker containers are configured with proper environment variable handling:
298

299
### Configuration Sources
300

301
1. **langgraph.json env field**: File path or dictionary
302
2. **Command-line overrides**: Runtime environment variables
303
3. **Docker Compose environment**: Container-specific variables
304
4. **External .env files**: Mounted or copied environment files
305

306
### Variable Precedence
307

308
1. Command-line arguments (highest priority)
309
2. Docker Compose environment section
310
3. Container environment variables
311
4. Configuration file env dictionary
312
5. External .env files (lowest priority)
313

314
## Health Checks and Monitoring
315

316
Generated Docker configurations include health checks and monitoring:
317

318
### Application Health Checks
319

320
```yaml
321
healthcheck:
322
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
323
  interval: 30s
324
  timeout: 10s
325
  retries: 3
326
  start_period: 60s
327
```
328

329
### Dependency Health Checks
330

331
```yaml
332
# PostgreSQL health check
333
healthcheck:
334
  test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
335
  interval: 5s
336
  timeout: 5s
337
  retries: 5
338
```
339

340
### Resource Limits
341

342
Production configurations include resource constraints:
343

344
```yaml
345
deploy:
346
  resources:
347
    limits:
348
      cpus: '2.0'
349
      memory: 2G
350
    reservations:
351
      cpus: '0.5'
352
      memory: 512M
353
```
354

355
## Error Handling
356

357
Docker integration provides detailed error handling:
358

359
- **Missing Docker**: Clear error message with installation instructions
360
- **Version compatibility**: Warnings for older Docker/Compose versions
361
- **Build failures**: Detailed build logs and troubleshooting steps
362
- **Network conflicts**: Port availability checking and suggestions
363
- **Image pull failures**: Registry authentication and connectivity guidance