Docker Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Docker deployment provides a containerized environment for the Infrahub MCP server, ensuring consistent behavior across development, testing, and production. The system uses Docker Compose to orchestrate the MCP server alongside its backend dependencies, such as the Infrahub server, databases, and task workers.
The deployment infrastructure supports three primary use cases:
- Production/Production-Ready Deployment: Standard containerized execution with managed configuration and observability.
- Development Environment: Local stacks using
docker-compose.ymland specialized anchors for environment variable management. - Integration Testing: Ephemeral stacks provisioned via
infrahub-testcontainersfor automated validation.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md, specs/001-infrahub-testcontainers/plan.md
Container Architecture
The Docker deployment model organizes the MCP server as a first-class component within the Infrahub ecosystem. It utilizes a stack of containers to provide a complete infrastructure automation environment.
The diagram shows the communication flow where the MCP server acts as the entry point for AI assistants, communicating with the backend Infrahub services over a shared container network.
Sources: specs/001-infrahub-testcontainers/plan.md, specs/001-infrahub-testcontainers/research.md:D7
Components and Services
| Component | Role | Description |
|---|---|---|
| Infrahub MCP Server | Primary Service | Runs the Python 3.13 FastMCP server, exposing tools and resources to AI clients. |
| Infrahub Server | Backend API | Provides the core infrastructure management API used by the MCP server. |
| Neo4j / Memgraph | Graph Database | Stores the infrastructure topology and node data. |
| Redis | Task/Cache Store | Handles task queuing for workers and backend caching. |
| Task Worker | Processor | Executes background tasks managed by the Infrahub server. |
Sources: specs/001-infrahub-testcontainers/research.md:D7, specs/001-infrahub-testcontainers/plan.md:Technical Context
Configuration Management
Environment variables control the behavior of the Docker containers. The project uses Pydantic-settings to load variables prefixed with INFRAHUB_MCP_ into the server configuration at startup.
Environment Anchors
The docker-compose.yml file utilizes a YAML anchor, x-infrahub-mcp-config, to centralize configuration. An automated task in tasks.py manages this anchor to prevent drift between the source code configuration and the Docker deployment files.
x-infrahub-mcp-config: &infrahub-mcp-config
INFRAHUB_ADDRESS: ${INFRAHUB_ADDRESS:-http://localhost:8000}
INFRAHUB_API_TOKEN: ${INFRAHUB_API_TOKEN:-06438eb2-8019-4776-878c-0941b1f1d1ec}
INFRAHUB_MCP_LOG_LEVEL: ${INFRAHUB_MCP_LOG_LEVEL:-info}
# ... additional variables
Sources: docker-compose.yml:1-10, tasks.py:108-140
Configuration Tasks
The following invoke tasks manage the Docker configuration:
uv run invoke gen-config-env --update: Regenerates thex-infrahub-mcp-configanchor indocker-compose.ymlbased on the currentServerConfigmodel.uv run invoke validate-dockercomposeenv: Validates that the committeddocker-compose.ymlis in sync with the configuration model by running a diff.
Sources: tasks.py:143-158
Integration Testing Deployment
The project employs infrahub-testcontainers for automated integration testing. This system provisions ephemeral Docker stacks for the duration of a test session.
The sequence illustrates the lifecycle of an ephemeral integration test stack. One stack is provisioned per session, with isolation achieved through per-test Infrahub branches.
Sources: specs/001-infrahub-testcontainers/research.md:D1, D6, specs/001-infrahub-testcontainers/plan.md:Summary
Testing Environment Details
- Isolation: One Infrahub container stack per
pytestsession and one fresh Infrahub branch per test. - Prerequisites: Requires a Docker engine reachable by the host; the suite fails fast if Docker is unavailable.
- Version Pinning: The Infrahub container image version is pinned via
INFRAHUB_TESTING_IMAGE_VERin CI to ensure reproducible results. - Cleanliness: Containers, networks, and volumes are automatically removed on exit, even if tests fail or are interrupted.
Sources: specs/001-infrahub-testcontainers/research.md:D4, D5, specs/001-infrahub-testcontainers/plan.md:Constraints
Observability in Docker
Dockerized deployments support production observability standards. The server provides specific endpoints and logging formats suitable for container orchestration.
- Health Checks: The server exposes a
/healthendpoint. In a Docker environment, this is used for container health probes to verify Infrahub backend connectivity. - Metrics: If
INFRAHUB_MCP_PROMETHEUS_ENABLEDis set totrue, the server exposes/metricsfor scraping by Prometheus. - Structured Logging: The server emits structured JSON logs to
stdout. Container logging drivers (e.g., Fluentd, Loki, CloudWatch) aggregate these for external analysis.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:FR-001, FR-002, FR-003, FR-030
Conclusion
Docker deployment is the standard method for running the Infrahub MCP server across all environments. By using Docker Compose, YAML anchors, and automated validation tasks, the project ensures that the containerized configuration remains synchronized with the server's requirements. This architecture enables high-fidelity integration testing and production-ready observability through structured logging and health monitoring.