@debugmcp/mcp-debugger/docs/archive/DOCKER_OPTIMIZATION_SUMMARY.md

Run-time step-through debugging for LLM agents.

# Docker Image Optimization Summary

## Date: January 13, 2025

## Objective
Reduce the MCP debugger Docker image size from 670MB to under 100MB.

## Results

### Size Reduction Achieved
- **Original Size**: 670MB
- **Optimized Size**: 240MB
- **Reduction**: 430MB (64% reduction)

### Optimization Techniques Applied

#### Phase 1: JavaScript Bundling
- Used esbuild to bundle all Node.js dependencies into a single file
- Bundle size: 1.11MB (includes all JavaScript dependencies)
- Eliminated the need to copy node_modules to production image

#### Phase 2: Base Image Optimization
- Switched from `python:3.11-slim` (Debian-based) to `python:3.11-alpine`
- Alpine Linux is significantly smaller than Debian
- Installed only Node.js runtime (no npm) in production image

#### Phase 3: Multi-stage Build
- Build stage uses full Node.js image with npm for building
- Production stage only copies the bundled JavaScript file
- Minimal runtime dependencies

## Technical Implementation

### Bundle Configuration
```javascript
{
  format: 'cjs',
  platform: 'node',
  target: 'node18',
  minify: true,
  external: ['fsevents'] // Only native modules kept external
}
```

### Dockerfile Structure
```dockerfile
# Build stage - 2GB+ (temporary)
FROM node:20-slim AS builder
# ... build and bundle ...

# Production stage - 240MB (final)
FROM python:3.11-alpine
# Only runtime dependencies
```

## Why Not Under 100MB?

The 240MB size is primarily due to:
1. **Python 3.11 runtime**: ~100MB (required for debugpy)
2. **Node.js runtime**: ~80MB (required to run JavaScript)
3. **debugpy package**: ~30MB (Python debugging library)
4. **Alpine base + system libraries**: ~30MB

Getting under 100MB would require:
- Removing either Python or Node.js (not possible for functionality)
- Using a custom-compiled minimal runtime (high complexity, maintenance burden)

## Verification

The optimized image was tested with all debugging functionality:
- ✅ Session creation and management
- ✅ Breakpoint setting
- ✅ Step debugging
- ✅ Variable inspection
- ✅ Stack trace analysis

## Recommendations

1. **Current 240MB is Production-Ready**: 64% reduction is significant
2. **Further Optimization**: Consider using distroless images if stricter size requirements
3. **Bundle Maintenance**: Update bundle.js when adding new dependencies
4. **CI/CD Integration**: Add automated Docker build with size checks

## Conclusion

While the target of <100MB wasn't achieved, the 64% size reduction from 670MB to 240MB represents a substantial optimization. The image maintains full functionality while being significantly more efficient for deployment and distribution.