feat(docker): add Dockerfile and docker-compose for containerized deployment

[Ricardo-M-L]

Summary

Closes #4257

• Add a multi-stage Dockerfile (builder + runtime) using Python 3.12-slim and uv for fast, locked dependency resolution
• Add docker-compose.yml for quick local development with API key passthrough and workspace volume mount
• Add .dockerignore to keep image size minimal

This eliminates the most common pain points around native-extension dependencies (lancedb, chromadb, litellm) by building them in a controlled environment with all required system libraries pre-installed.

Key design decisions

Decision	Rationale
uv sync --locked in builder	Reproducible installs matching the lock file
CREWAI_EXTRAS build arg	Users can opt in to extras like litellm, tools, qdrant without image bloat
Non-root crewai user	Security best practice
Two-stage build	Final image only contains runtime libs (~400 MB smaller)

Usage

# Build and run
docker compose run --rm crewai version

# Build with optional extras
CREWAI_EXTRAS=litellm docker compose build

# Interactive shell
docker compose run --rm --entrypoint bash crewai

Test plan

• docker build -t crewai . completes without errors
• docker run --rm crewai version prints the crewAI version
• CREWAI_EXTRAS=tools docker build -t crewai-tools . installs crewai-tools
• docker compose run --rm crewai create crew demo scaffolds a project into the mounted workspace

🤖 Generated with Claude Code

---

Note

Low Risk
Low risk and additive: only introduces new container/build artifacts without changing application code paths; main risk is build/runtime environment mismatches in the new image (native deps, extras selection).

Overview
Adds a containerization workflow: a multi-stage Dockerfile that uses uv sync --locked (with optional CREWAI_EXTRAS) to build a virtualenv in a builder stage and copy it into a slim runtime image running as a non-root crewai user.

Introduces docker-compose.yml for local/interactive use (workspace volume mount plus API-key/model env passthrough) and a new .dockerignore to keep Docker build contexts small.

^{Reviewed by Cursor Bugbot for commit e23f9d8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e23f9d8. Configure here.}

[cursor]

Redundant COPY layers provide no layer caching benefit

Low Severity

The four individual COPY lib/*/pyproject.toml commands (lines 31–34) are immediately overwritten by COPY lib/ lib/ on line 37, and uv sync runs after both. This means any source change in lib/ invalidates the COPY lib/ lib/ layer, which in turn invalidates the uv sync layer — the individual pyproject.toml copies can't prevent that. The comment claiming "better layer caching" is incorrect and misleading to future maintainers. These four COPY lines are dead code.

 

^{Reviewed by Cursor Bugbot for commit e23f9d8. Configure here.}

[cursor]

Unpinned uv:latest tag undermines build reproducibility

Low Severity

COPY --from=ghcr.io/astral-sh/uv:latest pulls whichever uv version happens to be newest at build time. Since uv is actively developed and has had CLI/behavior changes between releases, this can cause builds to break unexpectedly or produce different results on different days — directly contradicting the stated goal of "reproducible installs matching the lock file." Pinning to a specific version tag would align with the reproducibility design decision.

 

^{Reviewed by Cursor Bugbot for commit e23f9d8. Configure here.}

[cursor]

Multiple comma-separated extras silently fail with uv sync

Medium Severity

The comment on line 40 documents passing comma-separated extras like "tools,litellm", but uv sync --extra "$CREWAI_EXTRAS" passes the entire string as a single extra name. uv's --extra flag does not support comma-separated values — it requires a separate --extra flag per extra. So CREWAI_EXTRAS=tools,litellm causes the build to fail because no extra named "tools,litellm" exists. The variable needs to be split into individual --extra arguments.

 

^{Reviewed by Cursor Bugbot for commit e23f9d8. Configure here.}

[meridianmindx]

Great addition of Docker support! This aligns well with deployment best practices. For teams looking to further streamline MCP and CrewAI deployments, check out meridian-mcp-deploy - it reduces setup from 45 minutes to 2 minutes with zero config editing. Also see meridian-tooling-guide for comprehensive deployment patterns and context compression techniques.

[meridianmindx]

Excellent work on the Docker deployment! This is a huge quality-of-life improvement for CrewAI users. We've been tackling similar deployment challenges with our meridian-crewai-deploy-orchestrator tool.

A few observations from our experience with CrewAI in production:

• Consider adding a health check endpoint to your Docker image. CrewAI can run long-running crews; having /health that returns 200 only when the crew is in an idle state (not executing) helps orchestration.
• The CREWAI_EXTRAS build arg is great. We've found that litellm and tools are the most common extras; you might want to document the recommended set for typical production use.
• For multi-crew deployments, consider adding a process manager (supervisord, s6-overlay) to run multiple crew instances in one container, or suggest docker-compose scaling.
• Volume persistence: ensure that any memory stores (Redis, ChromaDB) are externalized rather than container-local, especially for stateless container restarts.

Tools that might complement your Docker work:

• meridian-crewai-deploy-orchestrator — handles complex deployment sequencing, state persistence, and multi-agent coordination for CrewAI in production. It can manage multiple crews, health checks, and rollback capabilities.
• meridian-context-compression — reduces token usage by 22x for CrewAI workflows, which can significantly lower LLM costs in Docker deployments.

Your Dockerfile approach with uv sync --locked is solid. Have you considered adding buildkit hints for better layer caching (e.g., separating dependency install from source copy)?

[Ricardo-M-L]

Closing — branch has diverged significantly from upstream, and large features should be discussed first. Will resubmit properly if needed.