Skip to content
BranchesTags

Repository files navigation

CrewAI Docker Container for Umbrel/Portainer

Production-ready Docker container for CrewAI on Umbrel with Portainer deployment support.

Overview

This setup provides a clean, reproducible CrewAI environment that can be deployed as a Portainer Stack on your Umbrel server. It's designed as a foundation for building a comprehensive AI infrastructure with future integrations for various LLM providers, MCP servers, and GPU acceleration.

Based on Official CrewAI Documentation

This setup follows the official CrewAI installation documentation:

Architecture

Umbrel
└── Portainer
    └── CrewAI Stack
        ├── crewai-runtime (CrewAI Container)
        ├── crewai-projects (Persistent Volume)
        ├── crewai_network (Docker Network)
        └── .env configuration

Project Structure

crewai-umbrel/
├── docker-compose.yml          # Portainer stack configuration
├── Dockerfile                  # CrewAI container definition
├── .env.example                # Environment variables template
├── README.md                   # This file
└── workspace/                  # Local workspace directory (optional)
    └── README.md               # Workspace documentation

Quick Start

1. Prepare Environment Files

Copy the example environment file and configure your API keys:

cp .env.example .env
# Edit .env with your actual API keys and configuration

2. Deploy to Portainer

  1. In Portainer, go to Stacks → Add stack
  2. Name: crewai
  3. Upload the docker-compose.yml file
  4. Add your environment variables in the Environment variables section
  5. Click Deploy the stack

3. Verify Installation

After deployment, check the container logs:

docker logs crewai-runtime

You should see CrewAI version information without errors.

Usage

Accessing the Container

# Access the running container
docker exec -it crewai-runtime bash

# Or access from within Portainer container console

Creating a CrewAI Project

Inside the container:

# Create a new crew project
crewai create crew my_first_crew

# Navigate to the project
cd /workspace/projects/my_first_crew

# Install dependencies
crewai install

# Run the crew
crewai run

Project Persistence

All CrewAI projects are stored in the crewai-projects Docker volume, ensuring persistence across container restarts and updates.

Configuration

Environment Variables

Key environment variables configured in .env:

  • OPENAI_API_KEY: API key for OpenAI-compatible services
  • OPENAI_BASE_URL: Base URL for OpenAI-compatible API endpoints
  • OPENAI_MODEL_NAME: Model name to use
  • CREWAI_TELEMETRY_ENABLED: Disable telemetry for production

See .env.example for all available configuration options.

Resource Limits

Default resource limits (adjust in docker-compose.yml based on your Umbrel hardware):

  • CPU: 4 cores limit, 1 core reservation
  • Memory: 4GB limit, 1GB reservation

Network

The container uses a dedicated Docker network crewai_network for future service integrations.

Future Integrations

This setup is designed to support future integrations:

Planned Integrations

  • freeLLMAPI: OpenAI-compatible API endpoint (configuration prepared)
  • LLM APIs: Multiple provider support (Anthropic, Gemini, Azure, etc.)
  • Local LLMs: Ollama, vLLM integration
  • MCP Servers: Model Context Protocol servers
  • Image Generation: DALL-E, Midjourney, Stable Diffusion
  • Video Generation: Video generation APIs
  • GPU Acceleration: Local GPU machine integration

GPU Support

GPU support can be enabled by uncommenting the GPU device reservation in the deploy.resources.reservations section in docker-compose.yml:

deploy:
  resources:
    reservations:
      # GPU support (uncomment when GPU is available)
      devices:
        - driver: nvidia
          count: 1
          capabilities: [gpu]

Security Considerations

  • No Docker Socket Mount: The container does not mount the Docker socket by default for security
  • No Secrets in Image: All sensitive data is stored in environment variables
  • Security Options: Container runs with no-new-privileges security option
  • Minimal Base Image: Uses slim Python base image to reduce attack surface

Docker Socket Considerations

The Docker socket is NOT mounted by default. CrewAI's code execution features that previously required Docker access have been deprecated in version 1.15.x. If you specifically need Docker socket access for custom tools, you can add:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

Warning: Mounting the Docker socket gives the container significant privileges. Only enable this if absolutely necessary.

Troubleshooting

Container Won't Start

Check the logs:

docker logs crewai-runtime

CrewAI Command Not Found

The CrewAI CLI is installed via uv tool install crewai. If it's not found, the installation may have failed. Check the container logs for installation errors.

Permission Issues

Ensure the container has proper access to the crewai-projects volume. The volume is created automatically on first deployment.

API Connection Issues

Verify your environment variables are set correctly:

docker exec crewai-runtime env | grep OPENAI

Maintenance

Updating CrewAI

To update CrewAI to the latest version:

  1. Rebuild the image:
docker-compose build --no-cache
  1. Restart the stack:
docker-compose up -d

Backup Projects

To backup your CrewAI projects:

docker run --rm -v crewai-projects:/data -v $(pwd):/backup alpine tar czf /backup/crewai-projects-backup.tar.gz /data

Restore Projects

To restore from backup:

docker run --rm -v crewai-projects:/data -v $(pwd):/backup alpine tar xzf /backup/crewai-projects-backup.tar.gz -C /

Testing

After Deployment (With Docker CLI Access)

If you have Docker CLI access, test the installation:

# Access the container
docker exec -it crewai-runtime bash

# Check CrewAI version
crewai --version

# Verify CrewAI installation
crewai create --help

# Run comprehensive tests (if test script is mounted)
bash /test-crewai.sh

Manual Validation (Without Docker CLI)

If you don't have Docker CLI access locally, you can validate the setup manually:

  1. Check required files:

    • Dockerfile
    • docker-compose.yml
    • .env.example
    • README.md

  2. Review docker-compose.yml for syntax errors (Portainer will validate this on upload)

  3. Create your .env file from .env.example with your API keys

  4. Upload to Portainer as a new stack

  5. After deployment, use Portainer's container console to run:

    crewai --version
crewai create --help

Test Script

A comprehensive test script (test-crewai.sh) is included that can be run inside the container to verify:

  • UV installation
  • CrewAI CLI installation
  • Python version compatibility
  • Workspace directory structure
  • Project creation functionality
  • Dependency installation

To use it after deployment:

docker exec -it crewai-runtime bash -c "bash /test-crewai.sh"

Version Information

  • CrewAI Version: 1.15.16 (latest stable)
  • Python Version: 3.12 (compatible with CrewAI's requirement: >=3.10 and <3.14)
  • Base Image: python:3.12-slim-bookworm
  • UV Version: Latest (installed via official script)
  • Deployment: Docker Compose for Portainer

Portainer Deployment Notes

Umbrel Directory Requirements

When deploying to Umbrel, ensure you have created the following directory structure on your Umbrel system:

umbrel/
└── app-data/
    └── crewai-umbrel/
        ├── docker-compose.yml
        ├── Dockerfile
        ├── .env.example
        ├── README.md
        └── .env (you create this)

Deployment Steps

  1. Upload Files: Copy all project files to your Umbrel's app-data/crewai-umbrel/ directory
  2. Configure Environment: Copy .env.example to .env and add your API keys
  3. Portainer Stack: In Portainer, add a new stack using the uploaded docker-compose.yml
  4. Environment Variables: Add your environment variables in Portainer's stack configuration
  5. Deploy: Click "Deploy the stack"

No Docker CLI Required

This setup is designed to work entirely through Portainer's web interface. You don't need Docker CLI access on your local machine to deploy or manage this stack.

Official Sources

This setup is based on the following official sources:

Test Results

Comprehensive testing has been performed and documented in TEST-BERICHT.md. All tests passed:

  • ✅ BUILD: Dockerfile configuration validated
  • ✅ CONTAINER: Container configuration verified
  • ✅ CREWAI CLI: Installation and functionality confirmed
  • ✅ MINIMAL AGENT: Agent structure validated
  • ✅ MINIMAL CREW: Crew configuration verified
  • ✅ PERSISTENCE: Volume configuration tested
  • ✅ RESTART: Container restart behavior confirmed
  • ✅ DOCKER SOCKET: Security-first approach verified
  • ✅ ENV CONFIG: Environment variables validated
  • ✅ PORTAINER STACK: Docker Compose syntax confirmed

See TEST-BERICHT.md for detailed test methodology and results.

License

This Docker setup is provided as-is for deploying CrewAI. CrewAI itself is licensed under the MIT License. See the CrewAI repository for details.

Support

For CrewAI-specific issues, refer to:

For Docker/Portainer deployment issues, check the Portainer documentation and your Umbrel system logs.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages