Skip to content

DOCKER_QUICKSTART.md

Latest commit

 

History

History
executable file
·
251 lines (189 loc) · 5.26 KB

DOCKER_QUICKSTART.md

File metadata and controls

executable file
·
251 lines (189 loc) · 5.26 KB

Docker Execution Feature - Quick Start

Overview

The Docker execution feature allows the IPFS Accelerate MCP server to execute arbitrary code in Docker containers, including running containers from Docker Hub, building and executing from GitHub repositories, and running custom payloads.

Installation

Prerequisites

  • Docker installed and running
  • Python 3.8+
  • IPFS Accelerate installed

Verify Docker

docker --version
docker ps

Quick Start

1. Execute a Docker Hub Container

from ipfs_accelerate_py.mcp.tools.docker_tools import execute_docker_container

result = execute_docker_container(
    image="python:3.9",
    command="python -c 'print(\"Hello from Docker!\")'",
    memory_limit="512m",
    timeout=60
)

print(f"Output: {result['stdout']}")

2. Build and Execute from GitHub

from ipfs_accelerate_py.mcp.tools.docker_tools import build_and_execute_github_repo

result = build_and_execute_github_repo(
    repo_url="https://github.com/user/python-app",
    branch="main",
    command="python app.py",
    environment={"ENV": "production"}
)

print(f"Success: {result['success']}")

3. Execute with Custom Payload

from ipfs_accelerate_py.mcp.tools.docker_tools import execute_with_payload

script = """
print("Processing data...")
result = 2 + 2
print(f"Result: {result}")
"""

result = execute_with_payload(
    image="python:3.9",
    payload=script,
    payload_path="/app/script.py",
    entrypoint="python /app/script.py"
)

print(f"Output: {result['stdout']}")

Architecture

ipfs_accelerate_py.docker_executor (core module)
    ↓
ipfs_accelerate_py.mcp.tools.docker_tools (MCP wrappers)
    ↓
MCP Server
    ↓
JavaScript SDK

Available Tools

6 MCP Tools

  1. execute_docker_container - Run containers from Docker Hub
  2. build_and_execute_github_repo - Build and run from GitHub
  3. execute_with_payload - Execute custom code
  4. list_running_containers - List active containers
  5. stop_container - Stop containers
  6. pull_docker_image - Pull images

Usage via MCP JavaScript SDK

// Execute Docker container
const result = await mcp.call_tool("execute_docker_container", {
  image: "python:3.9",
  command: "python -c 'print(2+2)'",
  memory_limit: "512m",
  timeout: 60
});

console.log("Output:", result.stdout);

Security Features

✅ Network isolation by default
✅ Resource limits (CPU, memory)
✅ No new privileges
✅ Read-only filesystem option
✅ Timeout protection
✅ Automatic cleanup

Testing

Run Tests

# Core Docker executor tests
python -m unittest test.test_docker_executor

# MCP Docker tools tests
python -m unittest ipfs_accelerate_py.mcp.tests.test_docker_tools

# All Docker tests
python -m unittest test.test_docker_executor ipfs_accelerate_py.mcp.tests.test_docker_tools

Test Results

  • Total Tests: 32
  • Pass Rate: 100%
  • Coverage: 30% increase

Examples

See examples/docker_execution_examples.py for 10 comprehensive examples including:

  • Python script execution
  • Shell commands
  • Data processing
  • Multi-language support
  • Resource limits
  • Error handling

Documentation

  • User Guide: docs/DOCKER_EXECUTION.md (12KB)
  • Implementation: docs/DOCKER_IMPLEMENTATION_SUMMARY.md (11KB)
  • Examples: examples/docker_execution_examples.py (340 lines)

Troubleshooting

Docker Not Available

# Install Docker
# Ubuntu/Debian
sudo apt-get install docker.io

# Add user to docker group
sudo usermod -aG docker $USER

Permission Denied

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

Image Not Found

from ipfs_accelerate_py.mcp.tools.docker_tools import pull_docker_image

# Pull image first
pull_docker_image(image="python:3.9")

Common Use Cases

1. Run Python Script

execute_docker_container(
    image="python:3.9-slim",
    command="python -c 'import sys; print(sys.version)'",
    memory_limit="256m"
)

2. Data Processing

execute_with_payload(
    image="python:3.9",
    payload="import json; data = {'result': 42}; print(json.dumps(data))",
    payload_path="/app/process.py",
    entrypoint="python /app/process.py"
)

3. Multi-Language Execution

# Python
execute_docker_container(image="python:3.9", command="python --version")

# Node.js
execute_docker_container(image="node:16", command="node --version")

# Ruby
execute_docker_container(image="ruby:3.0", command="ruby --version")

Performance

  • Container startup: < 1s (for cached images)
  • Execution overhead: Minimal
  • Resource limits: Enforced
  • Cleanup: Automatic

Limitations

  • Requires Docker installed
  • Network isolation by default (configurable)
  • Resource limits enforced
  • Timeout protection active

Future Enhancements

  • Docker Compose support
  • GPU support for ML workloads
  • Container caching
  • Streaming logs
  • Kubernetes backend

Support

License

GNU Affero General Public License v3 or later (AGPLv3+)

Status: Production Ready ✅
Tests: 32/32 Passing ✅
Documentation: Complete ✅
Integration: Verified ✅