> For the complete documentation index, see [llms.txt](https://docs.dorg.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dorg.pro/create-competency/develop-a-competency/dockerizing-an-open-source-mcp-server.md). # Dockerizing an Open-Source MCP Server When working with an open-source MCP server, the approach depends on the level of Docker support provided by the project. In practice, three scenarios cover almost all cases: a prebuilt image is available, a Dockerfile is provided but no image, or there is no Docker support at all. *** #### a) Docker image provided by the project In this scenario, the project already publishes a ready-to-use Docker image on a registry such as Docker Hub or GitHub Container Registry. No build process is required. The workflow consists of retrieving the image, optionally validating it, and exporting it. The first step is to identify the exact image reference, including registry, name, and tag. A fixed version tag must be used to ensure reproducibility. Avoid `latest`, since it is not stable over time. Once identified, pull the image locally: ```shellscript docker pull ghcr.io/vendor/mcp-server:1.2.3 ``` After pulling, the image is stored in the local Docker cache. It is recommended to verify it before exporting, especially if the MCP server requires runtime configuration such as environment variables, ports, or volumes. A basic test run can be performed with: ```shellscript docker run --rm -it ghcr.io/vendor/mcp-server:1.2.3 ``` If the container starts correctly, the image can be exported. The correct operation is `docker save`, which serializes the image into a tar archive. This archive can optionally be compressed. On Linux: ```shellscript docker save ghcr.io/vendor/mcp-server:1.2.3 | gzip > mcp-server.tar.gz ``` On Windows (PowerShell): ```shellscript docker save ghcr.io/vendor/mcp-server:1.2.3 -o mcp-server.tar Compress-Archive -Path mcp-server.tar -DestinationPath mcp-server.tar.gz ``` The resulting file is a portable image archive that can be imported into **Dorg University**. *** #### b) Docker image not provided, but Dockerfile is available If the project provides a Dockerfile but no prebuilt image, the image must be built locally. The containerization logic already exists, but it must be executed and validated. Start by cloning or downloading the repository: ```shellscript git clone cd ``` Before building, review the Dockerfile. This is necessary to understand the base image, dependency installation, entrypoint, and any assumptions about the build context. Dockerfiles are often written for development and may not be production-ready. Build the image with: ```shellscript docker build -t mcp-image-name:tag . ``` If multiple Dockerfiles are present: ```shellscript docker build -f path/to/Dockerfile -t mcp-image-name:tag . ``` Once built, verify that the image exists: ```shellscript docker images | grep mcp-image-name ``` Then run the container to confirm that it behaves correctly: ```shellscript docker run --rm -it mcp-image-name:tag ``` At this stage, any required runtime parameters (ports, environment variables, volumes) must be applied based on project documentation. After validation, export the image using the same process: On Linux: ```shellscript docker save mcp-image-name:tag | gzip > mcp-image-name.tar.gz ``` On Windows (PowerShell): ```shellscript docker save mcp-image-name:tag -o mcp-image-name.tar Compress-Archive -Path mcp-image-name.tar -DestinationPath mcp-image-name.tar.gz ``` This scenario often requires handling build arguments: ```shellscript docker build --build-arg VAR=value -t mcp-image-name:tag . ``` In addition, some projects define runtime behavior in `docker-compose.yml` rather than in the Dockerfile, so those files should also be reviewed. *** #### c) No Docker support provided If the project does not provide either a Docker image or a Dockerfile, the containerization must be implemented from scratch. The first step is to analyze the application. This includes identifying the runtime (Node.js, Python, Go, etc.), the dependency management system, and the command used to start the server. It is also necessary to determine required ports, configuration files, and environment variables. Based on this analysis, a Dockerfile must be created. Example for a Node.js application: ```docker FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --omit=dev COPY . . CMD ["node", "index.js"] ``` Example for a Python application: ```docker FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["python", "main.py"] ``` Once the Dockerfile is ready, build the image: ```bash docker build -t mcp-image-name:tag . ``` Then run it to validate behavior: ```shellscript docker run --rm -it mcp-image-name:tag ``` After verification, export the image: On Linux: ```shellscript docker save mcp-image-name:tag | gzip > mcp-image-name.tar.gz ``` On Windows (PowerShell): ```shellscript docker save mcp-image-name:tag -o mcp-image-name.tar Compress-Archive -Path mcp-image-name.tar -DestinationPath mcp-image-name.tar.gz ``` This scenario requires full responsibility for container design. Errors are more likely, especially around entrypoints, dependency installation, and runtime assumptions. Testing should therefore be thorough and performed with realistic configurations. *** #### General best practices Across all scenarios, reproducibility, validation, and minimalism are the key principles. Always use explicit version tags for both images and dependencies. Avoid `latest`. Prefer lightweight base images such as `alpine` or `slim`, and use multi-stage builds when compilation is required. Containers should run as non-root whenever possible: ``` USER 1000:1000 ``` Builds should be deterministic, using lock files such as `package-lock.json`, `poetry.lock`, or equivalent. An image should never be exported without being tested. The container must start and behave correctly under realistic conditions. Finally, all runtime requirements must be clearly documented. This includes environment variables, exposed ports, mounted volumes, credentials, and startup commands. Without this information, the exported image is not practically usable. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.dorg.pro/create-competency/develop-a-competency/dockerizing-an-open-source-mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.