Docker Deployment

Deploy DeerFlow using Docker for a consistent, isolated environment. Docker deployment is the recommended approach for both development and production.

Architecture

DeerFlow’s Docker deployment consists of four main services:

┌─────────────────────────────────────────────────────────┐
│              Nginx Reverse Proxy (Port 2026)            │
└────────────────────┬────────────────────────────────────┘
                     │
      ┌──────────────┼──────────────┐
      │              │              │
      ▼              ▼              ▼
┌──────────┐  ┌──────────┐  ┌──────────────┐
│ Frontend │  │ Gateway  │  │  LangGraph   │
│  :3000   │  │  :8001   │  │    :2024     │
└──────────┘  └──────────┘  └──────────────┘
                     │
                     ▼
              ┌──────────────┐
              │  Provisioner │  (Optional)
              │    :8002     │
              └──────────────┘

Prerequisites

Docker 20.10+ or Docker Desktop
Docker Compose v2.0+
4GB RAM minimum (8GB recommended)
10GB disk space

Quick Start

1. Clone and Configure

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# Generate configuration files
make config

2. Configure Your Model

Edit config.yaml to add at least one LLM model:

models:
  - name: gpt-4
    display_name: GPT-4
    use: langchain_openai:ChatOpenAI
    model: gpt-4
    api_key: $OPENAI_API_KEY
    max_tokens: 4096
    temperature: 0.7

3. Set API Keys

Edit .env file in the project root:

OPENAI_API_KEY=your-openai-api-key
TAVILY_API_KEY=your-tavily-api-key
JINA_API_KEY=your-jina-api-key

4. Initialize and Start

# Pre-pull sandbox image (recommended, ~500MB)
make docker-init

# Start all services
make docker-start

5. Access the Application

Open your browser to:

Application: http://localhost:2026
API Gateway: http://localhost:2026/api/
LangGraph: http://localhost:2026/api/langgraph/
API Docs: http://localhost:2026/docs

Docker Compose Services

Frontend Service

frontend:
  build:
    context: ../
    dockerfile: frontend/Dockerfile
  ports:
    - "3000:3000"
  volumes:
    - ../frontend/src:/app/frontend/src
    - ../frontend/public:/app/frontend/public
  environment:
    - NODE_ENV=development

Key Features:

Next.js 14 with App Router
Hot reload for development
pnpm package manager
Node.js 22-alpine base image

Gateway Service

gateway:
  build:
    context: ../
    dockerfile: backend/Dockerfile
  ports:
    - "8001:8001"
  volumes:
    - ../backend/src:/app/backend/src
    - ../config.yaml:/app/config.yaml
    - ../skills:/app/skills
  command: >
    sh -c "cd backend && 
    uv run uvicorn src.gateway.app:app 
    --host 0.0.0.0 --port 8001 --reload"

Provides:

Models API (/api/models)
MCP configuration (/api/mcp)
Skills management (/api/skills)
File uploads (/api/threads/{id}/uploads)
Artifact serving (/api/threads/{id}/artifacts)

LangGraph Service

langgraph:
  build:
    context: ../
    dockerfile: backend/Dockerfile
  ports:
    - "2024:2024"
  volumes:
    - ../backend/src:/app/backend/src
    - ../backend/.deer-flow:/app/backend/.deer-flow
  command: >
    sh -c "cd backend && 
    uv run langgraph dev 
    --host 0.0.0.0 --port 2024 --allow-blocking"

Handles:

Agent runtime execution
Thread state management
SSE streaming responses
Checkpoint persistence
Tool execution

Nginx Service

nginx:
  image: nginx:alpine
  ports:
    - "2026:2026"
  volumes:
    - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
  depends_on:
    - frontend
    - gateway
    - langgraph

Routes:

/api/langgraph/* → LangGraph server (2024)
/api/* → Gateway API (8001)
/* → Frontend (3000)

Volume Mounts

Development Volumes

For hot reload and development:

volumes:
  # Frontend hot reload
  - ../frontend/src:/app/frontend/src
  - ../frontend/public:/app/frontend/public
  
  # Backend hot reload
  - ../backend/src:/app/backend/src
  
  # Configuration
  - ../config.yaml:/app/config.yaml
  - ../.env:/app/.env
  
  # Skills directory
  - ../skills:/app/skills
  
  # Thread data persistence
  - ../backend/.deer-flow:/app/backend/.deer-flow
  
  # Logs
  - ../logs:/app/logs

Cache Volumes

For faster builds:

volumes:
  # pnpm package cache
  - ~/.local/share/pnpm/store:/root/.local/share/pnpm/store
  
  # uv Python cache
  - ~/.cache/uv:/root/.cache/uv

Network Configuration

DeerFlow uses a custom bridge network:

networks:
  deer-flow-dev:
    driver: bridge
    ipam:
      config:
        - subnet: 192.168.200.0/24

Benefits:

Service discovery via DNS
Internal service communication
Isolation from other containers
Predictable IP addressing

Environment Variables

Required Variables

# Model API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DEEPSEEK_API_KEY=sk-...

# Tool API Keys
TAVILY_API_KEY=tvly-...
JINA_API_KEY=jina_...

Optional Variables

# Custom config path
DEER_FLOW_CONFIG_PATH=/custom/path/config.yaml

# pnpm store location
PNPM_STORE_PATH=/root/.local/share/pnpm/store

# Node environment
NODE_ENV=production

# Enable CI mode (disable interactive prompts)
CI=true

Building Images

Backend Image

From backend/Dockerfile:

FROM python:3.12-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    curl \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install uv package manager
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.local/bin:$PATH"

WORKDIR /app

# Copy and install dependencies
COPY backend ./backend
RUN --mount=type=cache,target=/root/.cache/uv \
    sh -c "cd backend && uv sync"

EXPOSE 8001 2024

CMD ["sh", "-c", "uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001"]

Build command:

docker build -t deer-flow-backend -f backend/Dockerfile .

Frontend Image

From frontend/Dockerfile:

FROM node:22-alpine

# Install pnpm
RUN corepack enable && corepack install -g pnpm@10.26.2

WORKDIR /app

# Copy and install dependencies
COPY frontend ./frontend
RUN sh -c "cd /app/frontend && pnpm install --frozen-lockfile"

EXPOSE 3000

Build command:

docker build -t deer-flow-frontend -f frontend/Dockerfile .

Management Commands

Start Services

# Start all services
make docker-start

# Start with rebuild
make docker-start --build

# Start specific service
docker compose -f docker/docker-compose-dev.yaml up frontend

Stop Services

# Stop all services
make docker-stop

# Stop and remove volumes
docker compose -f docker/docker-compose-dev.yaml down -v

View Logs

# All services
make docker-logs

# Specific services
make docker-logs-frontend
make docker-logs-gateway

# Follow logs
docker compose -f docker/docker-compose-dev.yaml logs -f langgraph

Restart Services

# Restart all
docker compose -f docker/docker-compose-dev.yaml restart

# Restart specific service
docker compose -f docker/docker-compose-dev.yaml restart gateway

Production Optimizations

Multi-stage Build

For smaller production images:

# Build stage
FROM node:22-alpine AS builder
WORKDIR /app
COPY frontend/package.json frontend/pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY frontend/ .
RUN pnpm run build

# Production stage
FROM node:22-alpine
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["pnpm", "start"]

Environment-specific Compose

Create docker-compose.prod.yaml:

services:
  frontend:
    build:
      context: ../
      dockerfile: frontend/Dockerfile.prod
    environment:
      - NODE_ENV=production
    restart: always
    
  gateway:
    build:
      context: ../
      dockerfile: backend/Dockerfile.prod
    command: >
      sh -c "cd backend && 
      uv run uvicorn src.gateway.app:app 
      --host 0.0.0.0 --port 8001 
      --workers 4"
    restart: always
    
  langgraph:
    restart: always
    command: >
      sh -c "cd backend && 
      uv run langgraph start 
      --host 0.0.0.0 --port 2024"

Health Checks

Add health checks to services:

gateway:
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:8001/health"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 40s

Troubleshooting

Services Not Starting

Check logs:

make docker-logs

Verify configuration:

docker compose -f docker/docker-compose-dev.yaml config

Port Conflicts

Check port usage:

lsof -i :2026  # nginx
lsof -i :3000  # frontend
lsof -i :8001  # gateway
lsof -i :2024  # langgraph

Change ports in docker-compose.yaml:

ports:
  - "8026:2026"  # Use 8026 on host instead

Volume Permission Issues

Fix permissions:

sudo chown -R $USER:$USER backend/.deer-flow
sudo chown -R $USER:$USER logs

Image Build Failures

Clear build cache:

docker builder prune -a

Rebuild without cache:

docker compose -f docker/docker-compose-dev.yaml build --no-cache

Network Issues

Recreate network:

docker compose -f docker/docker-compose-dev.yaml down
docker network rm deer-flow-dev
make docker-start

Overview

Core Concepts

Configuration

Guides

Deployment

​Architecture

​Prerequisites

​Quick Start

​1. Clone and Configure

​2. Configure Your Model

​3. Set API Keys

​4. Initialize and Start

​5. Access the Application

​Docker Compose Services

​Frontend Service

​Gateway Service

​LangGraph Service

​Nginx Service

​Volume Mounts

​Development Volumes

​Cache Volumes

​Network Configuration

​Environment Variables

​Required Variables

​Optional Variables

​Building Images

​Backend Image

​Frontend Image

​Management Commands

​Start Services

​Stop Services

​View Logs

​Restart Services

​Production Optimizations

​Multi-stage Build

​Environment-specific Compose

​Health Checks

​Troubleshooting

​Services Not Starting

​Port Conflicts

​Volume Permission Issues

​Image Build Failures

​Network Issues

​Next Steps

Kubernetes Deployment

Production Guide

​See Also