Deploy bằng Docker Compose: Development → Staging → Production

Agent chạy local mượt mà nhưng lên production lại "quên" hết ngữ cảnh, mất dữ liệu ký ức, hay tool execution bị lỗi path? Vấn đề không nằm ở code — mà ở việc bạn đang đối xử với agent như một web app stateless thông thường. Docker Compose không chỉ là công cụ "chạy thử" trên máy tính cá nhân; khi hiểu đúng, nó là specification cho toàn bộ hệ sinh thái stateful của agent, từ LLM brain đến memory store và tool sandbox.

Vấn đề

Sự khác biệt cốt lõi giữa web app và AI agent là trạng thái (state). Web app truyền thống vô trạng thái: request vào, query database, trả response, quên ngay lập tức. Ngược lại, AI agent là "quá trình sống" — nó có conversation history kéo dài hàng giờ, episodic memory trong SQLite/Postgres, vector embeddings trong Chroma/Weaviate, và scheduled cron jobs cần persistence.

Cách tiếp cận "hy vọng may mắn" (hope-based deployment) gây ra lỗi đặc trưng của agent:

1. Context amnesia: Mount sai volume khiến MEMORY.md và SOUL.md bị reset mỗi lần restart container, agent "quên" mình là ai sau mỗi deploy.
2. Tool path drift: Dev chạy agent trực tiếp trên host có sẵn Python/Bash; production container thiếu dependency, hoặc worse — tool access vào host filesystem vì thiếu sandbox.
3. Environment drift: docker run thủ công trên staging và production khác nhau một dòng flag, dẫn đến behavior khác biệt không lý giải được (ví dụ: rate limiting hoặc RLS policy bật/tắt).
4. Stateful recovery: Khi container crash, conversation history và in-flight tool execution không được checkpoint, gây "cognitive discontinuity" — agent thức dậy không biết mình đang làm gì giữa chừng.

Kubernetes (K8s) giải quyết được vấn đề scale, nhưng overhead cho team nhỏ là không cần thiết — bạn không cần distributed consensus để chạy 5 agent trên một con Mac Mini hoặc VPS.

Ý tưởng cốt lõi

Docker Compose là container relationship specification — một bản thiết kế invariant cho mối quan hệ giữa các dịch vụ, không phụ thuộc vào môi trường. Triển khai agent production không phải là việc viết lại config, mà là merge config theo pattern kế thừa (inheritance).

Inheritance Pattern: Base + Environment Deltas

Thay vì sao chép file, bạn tổ chức theo object-oriented config:

# docker-compose.yml (Base class)
version: "3.8"
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    volumes:
      - ./SOUL.md:/app/SOUL.md:ro
      - ./AGENTS.md:/app/AGENTS.md:ro
      - agent_memory:/app/memory
    environment:
      - LLM_MODEL=claude-3-opus
      - LOG_LEVEL=debug
    depends_on:
      - redis
      - vectorstore

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

  vectorstore:
    image: semitechnologies/weaviate:1.24
    volumes:
      - weaviate_data:/var/lib/weaviate

volumes:
  agent_memory:
  redis_data:
  weaviate_data:

# docker-compose.prod.yml (Subclass — chỉ override biến động)
services:
  openclaw:
    environment:
      - LOG_LEVEL=warn
      - RATE_LIMIT_REQ_PER_MIN=100
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
    restart: unless-stopped
    # Override volume: bind mount thành named volume trên host cụ thể
    volumes:
      - /var/lib/openclaw/memory:/app/memory
      - /etc/openclaw/SOUL.md:/app/SOUL.md:ro

  redis:
    restart: unless-stopped
    # Bật AOF persistence cho production
    command: redis-server --appendonly yes

Merge bằng lệnh:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Logic merge left-to-right: giá trị trong docker-compose.prod.yml ghi đè (override) base. Điều này đảm bảo topology (network aliases, dependency order) giữ nguyên giữa dev và prod, chỉ thay đổi environmental properties (resource limits, restart policy, secret paths).

Stateful Service Topology cho Agent

Agent không phải là một container đơn lẻ mà là topology gồm 4 thành phần bắt buộc:

• Agent Runtime (OpenClaw/GoClaw): Xử lý reasoning và tool orchestration
• Memory Store (SQLite/Postgres với RLS): Lưu conversation history và user-scoped data (xem multi-tenant-architecture)
• Message Queue (Redis): Xử lý async tasks và cron jobs (HEARTBEAT.md triggers)
• Vector Database (Weaviate/Chroma): RAG retrieval cho long-term memory

# docker-compose.agent-stack.yml
services:
  agent:
    build: ./agent
    environment:
      - DB_URL=postgres://agent:${DB_PASS}@postgres:5432/agent_db
      - REDIS_URL=redis://redis:6379
      - VECTOR_URL=http://vectorstore:8080
    volumes:
      - ./skills:/app/skills:ro  # SKILL.md mounts
    networks:
      - agent_network

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: ${DB_PASS}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      # Mount init script cho Row-Level Security
      - ./init-rls.sql:/docker-entrypoint-initdb.d/init-rls.sql:ro

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

  # Tool sandbox — cách ly execution của agent khỏi host
  sandbox:
    image: ghcr.io/openclaw/sandbox:latest
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
    read_only: true
    tmpfs:
      - /tmp:noexec,nosuid,size=100m

Remote Execution & Git-Push Deployment

Bạn không cần SSH vào server để chạy docker compose. Dùng DOCKER_HOST environment variable:

# Local machine
export DOCKER_HOST=ssh://deploy@prod-server
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Compose CLI chạy local nhưng Docker Engine thực thi trên remote host — không cần copy file lên server thủ công, không lo lỗi "works on my machine".

Kết hợp với Git webhook:

1. Push lên main → Trigger GitHub Actions
2. Build image mới → Push registry
3. SSH vào server → Pull → docker compose up -d

Rolling update zero-downtime: Compose tự động recreate containers theo thứ tự depends_on, đảm bảo agent không bị "gián đoạn tư duy" giữa chừng khi update.

Horizontal Splitting (Dev → Staging → Production)

Khi cần scale vượt quá một node, split topology thành tiers:

# docker-compose.web.yml (Frontend + API Gateway)
services:
  api_gateway:
    image: kong:3.5
    ports:
      - "80:8000"
      - "443:8443"
    environment:
      - KONG_DATABASE=off
      - KONG_DECLARATIVE_CONFIG=/kong/declarative/kong.yml

# docker-compose.worker.yml (Background agents)
services:
  cron_agent:
    image: openclaw-cron:latest
    environment:
      - AGENT_MODE=cron
    # Không expose port, chỉ consume từ Redis queue

  event_agent:
    image: openclaw-event:latest
    environment:
      - AGENT_MODE=webhook

Chạy trên các node khác nhau nhưng cùng external network:

# Node 1
docker compose -f docker-compose.yml -f docker-compose.web.yml up -d

# Node 2 (worker node)
docker compose -f docker-compose.yml -f docker-compose.worker.yml up -d

Tại sao nó hoạt động

Thiết kế này giải quyết impedance mismatch giữa stateful agent và infrastructure thông qua ba nguyên lý:

Container là Process Boundary, không phải Package Agent sử dụng tools (bash, Python, file system) là surface tấn công rộng. Chạy agent trực tiếp trên host như go run main.go tạo "ambient authority" — agent có quyền của user chạy nó. Compose container với security_opt, cap_drop, read_only mounts tạo least-privilege sandbox, cô lập tool execution khỏi host OS. Đây là layer 0 của 5-layer-security.

Volume Mounts là Memory Persistence Khác web app, agent cần "bộ não" liên tục. Named volumes (agent_memory, postgres_data) được mount vào container như hippocampus của agent — khi container restart, identity và history vẫn intact. Điều này critical cho HEARTBEAT.md và MEMORY.md patterns.

Thin Wrapper vs. Orchestrator Compose là thin wrapper quanh Docker Engine API — nó supervise processes, không làm distributed scheduling như K8s. Điều này phù hợp agent vì:

• Context window của LLM cần RAM liên tục (vertical scaling hiệu quả hơn horizontal cho single agent instance)
• Agent chạy trên GPU instance đơn lẻ có thể xử lý hàng nghìn conversation parallel (nhờ goroutine pools trong GoClaw) trước khi cần sharding sang node khác
• 95% "hardening" là OS-level (firewall, SSL, backup) — không cần K8s complexity

Trade-off rõ ràng: Bạn đánh đổi khả năng auto-scaling horizontal (HPA) của K8s để lấy simplicity và reproducibility. Với agent fleet dưới 1000 instances trên một node beefy (như scaling-to-1000-agents đề cập), vertical scale + Compose thường hiệu quả hơn về chi phí và độ phức tạp.

Ý nghĩa thực tế

Benchmarks & Production Stories

• Nick Janetakis duy trì Flask app sinh lời $90,000/tháng trên hosting$100/tháng sử dụng Docker Compose pattern tương tự — chứng minh rằng "scale" không đồng nghĩa với Kubernetes.
• Rails backend xử lý doanh thu multi-million USD chạy trên 40 EC2 instances với Compose file chaining, đạt sub-5s deployment times.
• Agent platform có thể sustain 1000+ concurrent agents trên single Docker Compose stack với proper resource limits và goroutine pool tuning (xem performance-tuning).

Ai đang dùng?

• Solo SaaS founders: Không có team DevOps, cần deploy production ngay từ ngày đầu.
• Fintech acquired: Cần compliance và audit trail (immutable container images) nhưng không có thời gian migrate sang K8s.
• Internal IT Agents: Chạy on-premise trong mạng corporate (air-gapped) — Docker Compose dễ dàng hơn K8s trong môi trường restricted.

Hạn chế — Khi nào KHÔNG dùng Compose?

• Auto-scaling: Không có built-in HPA (Horizontal Pod Autoscaler). Khi load vượt quá một node, bạn phải manual split sang node khác (worker tier) hoặc migrate sang deploy-kubernetes.
• Self-healing: Nếu node chết, toàn bộ agent fleet down. Không có distributed consensus như K8s.
• Secret rotation: Thay đổi DB_PASS yêu cầu restart container (không có hot secret injection như Vault sidecar).
• Docker Socket risk: Dùng DOCKER_HOST qua TCP không có TLS expose attack surface (SSRF vector).
• Disaster Recovery: Backup và restore stateful volumes (SQLite/Postgres) phức tạp hơn stateless app — cần strategy riêng trong disaster-recovery.

Đào sâu hơn

Tài liệu chính thức

• Docker Docs: Production deployment using Docker Compose — remote deployment via DOCKER_HOST environment variables.

Cùng cụm Production Deploy

Đọc tiếp