CrewAI + Docker: triển khai trên VPS chạy production

Bạn đã build crew chạy ngon trên máy local rồi, giờ muốn đưa nó lên server để chạy tự động, chạy 24/7? Docker là cách gọn gàng nhất để đóng gói toàn bộ project CrewAI (code, dependencies, config) thành một image duy nhất, rồi deploy lên bất kỳ VPS nào.

Bài này hướng dẫn từ đầu đến cuối: viết Dockerfile, dùng Docker Compose, deploy lên VPS, chạy crew định kỳ bằng cron, và theo dõi logs. Nếu bạn chưa quen CrewAI, xem lại bài giới thiệu CrewAI từ A-Z trước. Bài trước về Planning và Reasoning cũng sẽ giúp bạn hiểu thêm các tính năng nâng cao.

Tại sao cần Docker cho CrewAI production

Chạy CrewAI trên máy local thì đơn giản: cài Python, pip install, chạy script. Nhưng khi đưa lên server production, câu chuyện khác hẳn. Bạn sẽ gặp mấy vấn đề thực tế:

• Xung đột dependencies: Server có thể đang chạy Python version khác, hoặc có package conflict với CrewAI. Một project pip install crewai, project khác cần version numpy cũ hơn, thế là loạn
• Khó tái tạo môi trường: “Máy tui chạy được” nhưng lên server lại lỗi. Chuyện này xảy ra thường xuyên hơn bạn tưởng, đặc biệt khi dependencies có binary build (như numpy, pandas)
• Không cô lập: Cài thẳng lên server, nếu CrewAI hay một dependency nào đó crash hoặc chiếm hết RAM, có thể kéo theo service khác đang chạy trên cùng server
• Khó scale và rollback: Muốn chạy 2 crew khác nhau? Muốn quay về version code cũ vì version mới bị lỗi? Không Docker thì rất lộn xộn, phải pip uninstall rồi install lại
• Khó deploy lặp lại: Nếu cần chuyển sang VPS khác (server cũ hết hạn, muốn scale up), phải setup lại từ đầu. Docker thì chỉ cần pull image là xong

Docker giải quyết hết mấy chuyện này. Bạn đóng gói project thành một image, image đó chạy giống hệt nhau bất kể trên Mac, Ubuntu hay CentOS. Muốn update thì build image mới, muốn rollback thì quay lại image cũ. Chạy 5 crew khác nhau trên cùng server? Mỗi crew một container, hoàn toàn cô lập. Sạch sẽ và dễ quản lý.

Yêu cầu VPS

CrewAI không chạy model AI trực tiếp trên máy (trừ khi bạn dùng Ollama chạy local model). Phần nặng nhất là inference, đã được LLM provider lo (OpenAI, Anthropic, Groq…). VPS chủ yếu cần đủ RAM cho Python runtime, Docker overhead, và đủ CPU để xử lý logic orchestration giữa các Agent.

Cấu hình tối thiểu và khuyến nghị:

Thành phần	Tối thiểu	Khuyến nghị	Ghi chú
CPU	1 vCPU	2 vCPU	Crew nhiều Agent chạy song song cần nhiều CPU hơn
RAM	1 GB	2 GB trở lên	Python + Docker overhead ~ 300-500MB, phần còn lại cho crew
Disk	20 GB SSD	40 GB NVMe	Docker images + logs tích lũy dần, NVMe nhanh hơn đáng kể
OS	Ubuntu 22.04+	Ubuntu 24.04 LTS	LTS có hỗ trợ dài hạn, ít phải lo update
Python	3.10+	3.11 hoặc 3.12	Trong Docker image, không cần cài trên host
Docker	24.0+	27.0+	Bản mới hỗ trợ Compose V2 tốt hơn

Nếu crew của bạn có nhiều Agent chạy đồng thời (hierarchical process) hoặc dùng tools xử lý file lớn (đọc CSV, scrape web), nên chọn VPS 4 GB RAM trở lên để tránh OOM (out of memory).

💡 AZDIGI Pro VPS dùng ổ NVMe tốc độ cao, hỗ trợ kỹ thuật 24/7, phù hợp để chạy Docker workloads kiểu này. Build Docker image trên NVMe nhanh hơn rõ rệt so với SSD thường.

Tạo Dockerfile cho project CrewAI

Giả sử cấu trúc project của bạn trông như thế này:

my-crew-project/
├── main.py          # Entry point chạy crew
├── agents.py        # Định nghĩa agents
├── tasks.py         # Định nghĩa tasks
├── tools.py         # Custom tools (nếu có)
├── requirements.txt # Dependencies với version cụ thể
├── .env             # API keys (KHÔNG đưa vào image!)
├── .dockerignore    # File/folder bỏ qua khi build
└── Dockerfile       # Công thức build image

Bước 1: Tạo requirements.txt

Luôn pin version cụ thể. Nếu không pin, pip sẽ lấy version mới nhất mỗi lần build, có thể gây lỗi bất ngờ khi package update:

# requirements.txt
crewai==1.9.3
crewai-tools==0.40.1
python-dotenv==1.0.1

ℹ️ Kiểm tra version mới nhất trên PyPI trước khi deploy. Số version trong ví dụ mang tính minh họa. Dùng pip freeze > requirements.txt trên máy local (sau khi chạy thành công) để lấy danh sách chính xác.

Bước 2: Viết Dockerfile

# Dùng Python slim thay vì full image, giảm size từ ~1GB xuống ~200MB
FROM python:3.11-slim
# Đặt thư mục làm việc trong container
WORKDIR /app
# Copy requirements trước (riêng) để tận dụng Docker layer cache
# Nếu requirements.txt không đổi, Docker skip bước pip install khi rebuild
COPY requirements.txt .
# Cài dependencies, --no-cache-dir giảm size image
RUN pip install --no-cache-dir -r requirements.txt
# Copy toàn bộ source code vào container
COPY . .
# Tạo thư mục output cho crew xuất kết quả
RUN mkdir -p /app/output
# Lệnh mặc định khi container chạy
CMD ["python", "main.py"]

Cấu trúc Dockerfile tách riêng bước copy requirements.txt và pip install ra khỏi bước copy source code. Lý do: Docker cache theo layer. Nếu requirements.txt không đổi (bạn chỉ sửa code Python), Docker sẽ dùng cache cho bước pip install, chỉ chạy lại bước copy code. Build lần sau nhanh hơn nhiều, từ vài phút xuống còn vài giây.

Bước 3: Tạo .dockerignore

Tránh copy file không cần thiết vào image, giữ image nhỏ gọn và bảo mật:

# .dockerignore
.env
.git
__pycache__
*.pyc
.venv
.mypy_cache
.pytest_cache
README.md
tests/

⚠️ File .env chứa API keys, tuyệt đối không đưa vào Docker image. Ai có image sẽ đọc được keys. Truyền qua environment variables khi chạy container hoặc dùng Docker secrets.

Bước 4: Build thử trên máy local

Trước khi deploy lên VPS, build và test trên máy local trước:

# Build image
docker build -t my-crew-project .
# Chạy thử (truyền .env file)
docker run --env-file .env my-crew-project
# Kiểm tra size image
docker images my-crew-project

Nếu crew chạy thành công trên local Docker thì 99% sẽ chạy đúng trên VPS. Đó là lợi ích chính của Docker: consistency giữa các môi trường.

Docker Compose cho CrewAI

Chạy docker run trực tiếp cũng được, nhưng Docker Compose giúp quản lý dễ hơn: ghi config vào file YAML, một lệnh để start/stop tất cả, dễ thêm service phụ (Redis, database…).

# docker-compose.yml
version: "3.8"
services:
  crewai-app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: crewai-app
    env_file:
      - .env                    # Truyền API keys từ file .env trên host
    volumes:
      - ./output:/app/output    # Mount thư mục output ra ngoài container
    restart: unless-stopped     # Tự restart nếu crash hoặc VPS reboot
    logging:
      driver: json-file
      options:
        max-size: "10m"         # Giới hạn mỗi file log 10MB
        max-file: "3"           # Giữ tối đa 3 file (tổng 30MB)
# Redis cho short-term memory (tùy chọn, xóa nếu không cần)
  redis:
    image: redis:7-alpine
    container_name: crewai-redis
    ports:
      - "127.0.0.1:6379:6379"  # Chỉ cho phép access từ localhost
    volumes:
      - redis-data:/data
    restart: unless-stopped
volumes:
  redis-data:

Giải thích các phần quan trọng:

• env_file: Docker đọc file .env trên host và truyền biến môi trường vào container. CrewAI tự nhận OPENAI_API_KEY, ANTHROPIC_API_KEY, SERPER_API_KEY… từ environment variables
• volumes (output): Mount thư mục output ra ngoài container. Crew xuất file kết quả (report, CSV, JSON…) vào đây, file nằm trên host nên không mất khi container restart hay bị xóa
• restart: unless-stopped: Container tự khởi động lại khi crash hoặc VPS reboot. Chỉ dừng khi bạn chủ động chạy docker compose stop
• logging config: Giới hạn log ở 30MB tổng cộng (3 file x 10MB). Không có giới hạn này, log có thể phình ra hàng GB theo thời gian, ăn hết disk
• Redis (tùy chọn): Dùng nếu crew cần short-term memory giữa các lần chạy. Bind port ở 127.0.0.1 để không expose ra internet

File .env trên VPS chứa API keys:

# .env (file này nằm trên VPS, cùng thư mục với docker-compose.yml)
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
SERPER_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
# Thêm key khác nếu crew dùng

Phân quyền file .env cho chặt: chmod 600 .env để chỉ owner đọc được.

Deploy lên VPS

Dưới đây là các bước từ lúc SSH vào VPS cho đến khi crew chạy thành công trong Docker container.

Bước 1: Cài Docker trên VPS

SSH vào VPS rồi chạy các lệnh sau. Ví dụ này dùng Ubuntu 24.04:

# Cập nhật package list
sudo apt update
# Cài Docker và Docker Compose plugin
sudo apt install -y docker.io docker-compose-plugin
# Khởi động Docker và enable tự chạy khi boot
sudo systemctl start docker
sudo systemctl enable docker
# Kiểm tra Docker đã cài thành công
docker --version
# Docker version 27.x.x, build xxxxxxx
docker compose version
# Docker Compose version v2.x.x

💡 Nếu không muốn gõ sudo mỗi lần chạy Docker, thêm user vào group docker: sudo usermod -aG docker $USER rồi logout/login lại.

Bước 2: Đưa code lên VPS

Có 2 cách phổ biến:

Cách 1: Git clone (khuyên dùng, dễ update sau này)

# Clone repo project lên VPS
cd /opt
git clone https://github.com/your-user/my-crew-project.git
cd my-crew-project
# Tạo file .env chứa API keys
nano .env
# Paste API keys vào, lưu file
# Phân quyền .env
chmod 600 .env

Cách 2: SCP hoặc rsync (copy trực tiếp từ máy local)

# Chạy trên máy local, copy project lên VPS
scp -r ./my-crew-project root@your-vps-ip:/opt/
# Hoặc dùng rsync (chỉ sync file thay đổi, nhanh hơn khi update)
rsync -avz --exclude '.env' --exclude '.git' \
  ./my-crew-project/ root@your-vps-ip:/opt/my-crew-project/

Bước 3: Build và chạy

cd /opt/my-crew-project
# Build image và chạy container ở background
docker compose up -d --build
# Kiểm tra container đang chạy
docker compose ps
# NAME          STATUS          PORTS
# crewai-app    Up 30 seconds
# crewai-redis  Up 30 seconds   127.0.0.1:6379->6379/tcp
# Xem logs realtime
docker compose logs -f crewai-app

Flag -d chạy container ở background (detached). --build force build lại image, cần thiết khi bạn vừa sửa code hoặc thay đổi Dockerfile. Lần chạy sau nếu code không đổi, bỏ --build để start nhanh hơn.

Cập nhật code sau này

Khi muốn deploy version mới:

cd /opt/my-crew-project
# Pull code mới (nếu dùng git)
git pull origin main
# Rebuild image và restart container
docker compose up -d --build
# Kiểm tra logs xem có lỗi không
docker compose logs --tail=50 crewai-app

Downtime chỉ vài giây trong lúc container restart. Nếu cần zero-downtime, có thể dùng kỹ thuật blue-green deploy, nhưng với crew AI thì thường không cần phức tạp vậy.

Chạy crew định kỳ với cron

Crew chạy trên server mà không ai theo dõi thì giống xe tự lái không camera. Cần biết crew có chạy thành công không, có lỗi gì không, tốn bao nhiêu thời gian và tài nguyên.

Xem logs Docker

# Xem logs realtime (Ctrl+C để thoát)
docker compose logs -f crewai-app
# Xem 100 dòng log gần nhất
docker compose logs --tail=100 crewai-app
# Xem logs kèm timestamp
docker compose logs -t crewai-app
# Xem logs từ 1 giờ trước đến giờ
docker compose logs --since=1h crewai-app

Theo dõi tài nguyên

# Xem CPU, RAM đang dùng (realtime)
docker stats crewai-app

# Output kiểu:
# CONTAINER     CPU %   MEM USAGE / LIMIT   MEM %   NET I/O
# crewai-app    2.5%    156MiB / 2GiB       7.6%    1.2MB / 800kB
# Xem disk dùng bởi Docker (images, containers, volumes)
docker system df

Nếu thấy MEM % tăng dần qua mỗi lần chạy mà không giảm, có thể crew bị memory leak. Restart container định kỳ hoặc dùng docker compose run --rm (tạo container mới mỗi lần) để tránh.

Health check trong Docker Compose

Nếu crew expose qua FastAPI hoặc Flask (chạy như API service), thêm health check:

# Thêm vào service crewai-app trong docker-compose.yml
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s          # Kiểm tra mỗi 30 giây
      timeout: 10s           # Timeout sau 10 giây
      retries: 3             # Fail 3 lần liên tiếp = unhealthy
      start_period: 40s      # Chờ 40 giây sau khi start mới bắt đầu check

Chạy docker compose ps sẽ thấy cột STATUS hiện “healthy” hoặc “unhealthy”.

Gửi thông báo khi crew lỗi

Cách đơn giản nhất là thêm try/except trong main.py, gửi webhook khi catch exception:

import requests
import traceback

def send_alert(message):
    """Gửi thông báo lỗi qua Telegram bot"""
    bot_token = os.getenv("TELEGRAM_BOT_TOKEN")
    chat_id = os.getenv("TELEGRAM_CHAT_ID")
    if bot_token and chat_id:
        url = f"https://api.telegram.org/bot{bot_token}/sendMessage"
        requests.post(url, json={"chat_id": chat_id, "text": message})
try:
    result = crew.kickoff()
    print("Crew completed successfully")
    print(result)
except Exception as e:
    error_msg = f"CrewAI Error:\n{traceback.format_exc()}"
    print(error_msg)
    send_alert(error_msg)

ℹ️ Ngoài Telegram, bạn có thể gửi webhook về Discord, Slack, hoặc bất kỳ service nào nhận HTTP POST. Cách nào tiện nhất cho bạn thì dùng cách đó.

Câu hỏi thường gặp

---

Vậy là bạn đã có đủ kiến thức để đưa project CrewAI từ máy local lên VPS production. Từ viết Dockerfile, Docker Compose config, deploy qua SSH, đến chạy crew tự động bằng cron và theo dõi logs, tất cả đã có trong bài này.

Nếu bạn đang tìm VPS phù hợp để chạy Docker workloads, AZDIGI Pro VPS là lựa chọn đáng cân nhắc: ổ NVMe tốc độ cao, uptime ổn định, hỗ trợ kỹ thuật 24/7 bằng tiếng Việt. Đặc biệt phù hợp cho các project AI Agent cần chạy liên tục hoặc theo lịch trình tự động.