How to Run codebase-memory-mcp in a Docker Container: Complete Setup Guide

You can run codebase-memory-mcp in a Docker container by building one of the three provided Dockerfiles (Alpine, glibc, or lint) and mounting your source code to /src to generate a static binary at build/c/codebase-memory-mcp.

The DeusData/codebase-memory-mcp repository ships with containerized build infrastructure that produces portable binaries without requiring local toolchain installation. Whether you need a fully static Alpine binary for distribution or a glibc-linked build for Ubuntu environments, the Docker workflow handles compilation through the scripts/build.sh entrypoint.

Choosing the Right Dockerfile Variant

The test-infrastructure/ directory contains three purpose-built Dockerfiles for different deployment scenarios.

Alpine (Fully Static)

The test-infrastructure/Dockerfile.alpine creates a fully static binary that runs on any Linux distribution without external dependencies. This is the recommended choice for portable containers and minimal deployment footprints.

Standard glibc (Ubuntu 22.04)

The test-infrastructure/Dockerfile.glibc22 builds against Ubuntu 22.04 with glibc 2.35. Use this variant when you require glibc-specific features or compatibility with enterprise Linux distributions that use dynamic linking.

Lint (CI Environment)

The test-infrastructure/Dockerfile.lint provides a CI-style environment primarily used for automated checks. You can repurpose this image as a generic build container if you only need the compilation toolchain without optimization flags.

Building the Docker Image

Run docker build targeting your chosen Dockerfile. The following command builds the Alpine variant tagged as cbm-alpine:

docker build -f test-infrastructure/Dockerfile.alpine -t cbm-alpine test-infrastructure/

Running the Container and Building the Binary

Mount your repository into /src inside the container. The Dockerfile entrypoint invokes scripts/build.sh, which compiles the C sources using Makefile.cbm and outputs the binary to build/c/codebase-memory-mcp on the mounted volume.

docker run --rm -v "$(pwd)":/src cbm-alpine

After the container exits, the compiled binary persists at ./build/c/codebase-memory-mcp on your host filesystem.

Executing the Binary

Use the generated binary exactly as you would a native installation. The binary requires absolute paths for repository operations.

# Index a repository

./build/c/codebase-memory-mcp index_repository --repo-path "$(pwd)"

# Start the server (UI variant required for graphical interface)

./build/c/codebase-memory-mcp --ui=true --port=9749

Optional UI Variant

To enable the graphical web interface, build with the WITH_UI=1 build argument and expose port 9749.

docker build -f test-infrastructure/Dockerfile.alpine -t cbm-alpine-ui \
    --build-arg WITH_UI=1 test-infrastructure/

docker run --rm -p 9749:9749 -v "$(pwd)":/src cbm-alpine-ui

Access the interface at http://localhost:9749 after the container starts.

Environment Configuration

The binary respects standard environment variables inside the container. Pass these via docker run using the -e flag to control caching, worker threads, and memory budgets.

docker run --rm -v "$(pwd)":/src \
    -e CBM_CACHE_DIR=/src/.cache \
    -e CBM_WORKERS=2 \
    -e CBM_MEM_BUDGET_MB=4096 \
    cbm-alpine

This configuration stores the SQLite cache inside your mounted project directory at ./.cache, ensuring the index persists after container termination.

Summary

• Three build variants: Choose between Dockerfile.alpine (static), Dockerfile.glibc22 (Ubuntu/glibc), or Dockerfile.lint (CI environment) based on your portability requirements.
• Volume mounting: Always mount your source to /src so scripts/build.sh can access the code and write the binary to build/c/codebase-memory-mcp.
• UI support: Add --build-arg WITH_UI=1 and expose port 9749 when building if you need the web interface.
• Environment persistence: Set CBM_CACHE_DIR to a path inside /src to maintain indexes between container runs.

Frequently Asked Questions

Can I run the binary directly without building it first?

No. The container entrypoint executes scripts/build.sh to compile the C source code using Makefile.cbm. You must run the build container at least once to generate the build/c/codebase-memory-mcp binary on your host filesystem before executing commands.

Which Dockerfile should I use for production deployments?

Use test-infrastructure/Dockerfile.alpine for production. It produces a fully static binary with no glibc dependencies, allowing the executable to run on any Linux distribution including minimal containers like Distroless or Scratch.

How do I persist the search index between container runs?

Set the CBM_CACHE_DIR environment variable to a subdirectory of /src (such as /src/.cache). Since /src is typically a bind mount from your host, the SQLite database persists on your local filesystem after the container exits.

Does the Docker container run the MCP server directly?

No. The container only builds the binary. After the build completes, you execute ./build/c/codebase-memory-mcp directly on your host or in a separate runtime container. For the UI variant, the container runs the build process and then the server starts, exposing port 9749 for browser access.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}