CrewAI Tutorial (Python): deploying with Docker for intermediate developers

This tutorial shows you how to package a CrewAI Python project into a Docker image, run it locally, and keep the setup reproducible across machines. You need this when your agent works on your laptop but breaks on someone else’s because of Python version drift, missing dependencies, or messy environment variables.

What You'll Need

• •Python 3.10 or 3.11
• •Docker Desktop or Docker Engine
• •A CrewAI project with at least one agent and one task
• •crewai installed in your project
• •An LLM API key, such as:
  • •OPENAI_API_KEY
  • •or another provider supported by your CrewAI setup
• •A .env file for local secrets
• •Basic familiarity with:
  • •Dockerfile
  • •docker build
  • •docker run

Step-by-Step

1. •Start with a minimal CrewAI project that runs locally before you containerize it. The goal is to prove the agent logic works on your machine first, then move that exact code into Docker.

# main.py
from crewai import Agent, Task, Crew, Process

agent = Agent(
    role="Research Analyst",
    goal="Summarize company news clearly",
    backstory="You are a concise analyst who writes short summaries.",
    verbose=True,
)

task = Task(
    description="Summarize the latest news about CrewAI in 3 bullet points.",
    expected_output="Three concise bullets",
    agent=agent,
)

crew = Crew(
    agents=[agent],
    tasks=[task],
    process=Process.sequential,
)

if __name__ == "__main__":
    result = crew.kickoff()
    print(result)

2. •Add a proper dependency file so Docker installs the same packages every time. Keep this lean; for a simple deployment you only need CrewAI and dotenv handling for environment variables.

# requirements.txt
crewai>=0.86.0
python-dotenv>=1.0.1

3. •Load secrets from .env and keep them out of source control. In production, this pattern maps cleanly to Docker environment variables or orchestration secrets later.

# .env
OPENAI_API_KEY=your_api_key_here

__pycache__/
*.pyc
.env
venv/
dist/
build/

4. •Create a Dockerfile that installs dependencies, copies your app, and runs it with Python. Use a slim base image so your container stays small and starts quickly.

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

RUN pip install --no-cache-dir --upgrade pip

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "main.py"]

5. •Build the image and pass your API key at runtime instead of baking it into the image. That keeps credentials out of the image layers and makes the container portable across environments.

docker build -t crewai-docker-tutorial .
docker run --rm \
  --env-file .env \
  crewai-docker-tutorial

6. •If you want cleaner local development, add a Compose file so you can standardize the run command and keep flags out of your shell history. This becomes useful once you have multiple services or want to mount code for faster iteration.

services:
  crewai-app:
    build: .
    env_file:
      - .env
    command: python main.py

Testing It

Run docker build first and make sure the image builds without pulling in anything unexpected from your host machine. Then run the container with --env-file .env and confirm the agent prints output instead of failing on missing credentials.

If it fails, check these three things first:

• •The API key is present inside the container environment.
• •Your installed CrewAI version matches the imports in main.py.
• •The model provider configured by CrewAI is available in your account.

For debugging, you can drop into the container interactively:

docker run --rm -it --env-file .env crewai-docker-tutorial bash

From there, inspect installed packages with pip show crewai, then run python main.py manually.

Next Steps

• •Add tools to your agent using real integrations like web search or internal APIs.
• •Split agents and tasks into separate modules once the project grows beyond one file.
• •Move from plain Docker to Docker Compose plus secrets management when deploying to shared environments.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.