Docker Build and Deployment Guide (mcpo project)

Thanks to @BigUncle for the pull request

This guide systematically outlines the build, deployment, troubleshooting, and best practices for the mcpo project in Docker container environments, reflecting the project's current state.

---

I. Project Overview and Architecture

This project uses Docker and Docker Compose for containerized deployment of mcpo (Model Context Protocol OpenAPI Proxy). Core design principles include:

- Dynamic Dependency Installation: At container startup, the start.sh script reads config.json and dynamically installs required Python (uvx) and Node.js (npx) tools based on defined mcpServers.
- Non-Root User Execution: The container ultimately runs as non-root user appuser to enhance security.
- Dependency and Data Persistence: Through Docker Compose volume mounts, configuration, logs, data, and cache directories for uv and npm are persisted to the host machine.
- Flexible Source Configuration: Supports dynamic configuration of pip sources via build argument (PIP_SOURCE), and uses Aliyun mirror by default to accelerate apt.
- Environment Isolation: In start.sh, each MCP tool installation occurs in a sub-shell to avoid environment variable conflicts.

---

II. Build and Deployment Process

1. Environment Preparation

- Docker & Docker Compose: Docker 24+ and Docker Compose 2.x recommended.
- .env File: Create an .env file in the project root directory for sensitive information and configuration. Include MCPO_API_KEY. Refer to .env.example.

  # .env file example
  # pip source used during Docker build (optional, uses default source if empty)
  PIP_SOURCE=https://mirrors.aliyun.com/pypi/simple/
# API Key required for mcpo runtime (required)

  MCPO_API_KEY=your_mcpo_api_key_here
# Other API Keys that may be needed for mcp servers (according to config.json)

  # AMAP_MAPS_API_KEY=your_amap_key

  # ... other required environment variables

  

- config.json: Configure MCP servers to start. Refer to config.example.json.
- Network: Ensure access to Debian (Aliyun mirror), NodeSource, PyPI (or specified PIP_SOURCE).

2. Directory Structure and Key Files

- Dockerfile: Defines image build process.
- Base image: python:3.13-slim
- Installs: bash, curl, jq, nodejs (v22.x), git, uv (via pip)
- User: Creates and runs as appuser.
- Configuration: Supports PIP_SOURCE build argument.
- start.sh: Container entrypoint script.
- Sets HOME, UV_CACHE_DIR, NPM_CONFIG_CACHE.
- Creates persistence directories.
- Reads config.json and dynamically installs MCP tools (using uvx or npx).
- Starts mcpo main service.
- docker-compose.yml: Defines services, build parameters, volume mounts, environment variables.
- Passes PIP_SOURCE to Dockerfile.
- Mounts ./config.json, ./logs, ./data, ./node_modules, ./.npm, ./.uv_cache.
- Loads .env as runtime environment variables via env_file.
- readme-docker.md: This document.
- test_mcp_tools.sh: Basic functionality test script.

3. Building the Image

```bash