Contributing to DeerFlow

Thank you for your interest in contributing to DeerFlow! This guide will help you set up your development environment and understand our development workflow.

Development Environment Setup

We offer two development environments. Docker is recommended for the most consistent and hassle-free experience.

Option 1: Docker Development (Recommended)

Docker provides a consistent, isolated environment with all dependencies pre-configured. No need to install Node.js, Python, or nginx on your local machine.

Prerequisites

Docker Desktop or Docker Engine
pnpm (for caching optimization)

Setup Steps

Configure the application:

# Copy example configuration
cp config.example.yaml config.yaml

# Set your API keys
export OPENAI_API_KEY="your-key-here"
# or edit config.yaml directly

Initialize Docker environment (first time only):
```
make docker-init
```
This will:
- Build Docker images
- Install frontend dependencies (pnpm)
- Install backend dependencies (uv)
- Share pnpm cache with host for faster builds
Start development services:
```
make docker-start
```
All services will start with hot-reload enabled:
- Frontend changes are automatically reloaded
- Backend changes trigger automatic restart
- LangGraph server supports hot-reload
Access the application:
- Web Interface: http://localhost:2026
- API Gateway: http://localhost:2026/api/*
- LangGraph: http://localhost:2026/api/langgraph/*

Docker Commands

# Build the custom k3s image (with pre-cached sandbox image)
make docker-init

# Start Docker services (mode-aware, localhost:2026)
make docker-start

# Stop Docker development services
make docker-stop

# View Docker development logs
make docker-logs

# View Docker frontend logs
make docker-logs-frontend

# View Docker gateway logs
make docker-logs-gateway

Docker Architecture

Host Machine
  ↓
Docker Compose (deer-flow-dev)
  ├→ nginx (port 2026) ← Reverse proxy
  ├→ web (port 3000) ← Frontend with hot-reload
  ├→ api (port 8001) ← Gateway API with hot-reload
   ├→ langgraph (port 2024) ← LangGraph server with hot-reload
   └→ provisioner (optional, port 8002) ← Started only in provisioner/K8s sandbox mode

Benefits of Docker Development:

✅ Consistent environment across different machines
✅ No need to install Node.js, Python, or nginx locally
✅ Isolated dependencies and services
✅ Easy cleanup and reset
✅ Hot-reload for all services
✅ Production-like environment

Option 2: Local Development

If you prefer to run services directly on your machine:

Prerequisites

Check that you have all required tools installed:

make check

Required tools:

Node.js 22+
pnpm
uv (Python package manager)
nginx

Setup Steps

Configure the application (same as Docker setup above)
Install dependencies:
```
make install
```
Run development server (starts all services with nginx):
```
make dev
```
Access the application:
- Web Interface: http://localhost:2026
- All API requests are automatically proxied through nginx

Manual Service Control

If you need to start services individually:

Start backend services:

# Terminal 1: Start LangGraph Server (port 2024)
cd backend
make dev

# Terminal 2: Start Gateway API (port 8001)
cd backend
make gateway

# Terminal 3: Start Frontend (port 3000)
cd frontend
pnpm dev

Start nginx:

make nginx
# or directly: nginx -c $(pwd)/docker/nginx/nginx.local.conf -g 'daemon off;'

Access the application:
- Web Interface: http://localhost:2026

Nginx Configuration

The nginx configuration provides:

Unified entry point on port 2026
Routes /api/langgraph/* to LangGraph Server (2024)
Routes other /api/* endpoints to Gateway API (8001)
Routes non-API requests to Frontend (3000)
Centralized CORS handling
SSE/streaming support for real-time agent responses
Optimized timeouts for long-running operations

Project Structure

deer-flow/
├── config.example.yaml      # Configuration template
├── extensions_config.example.json  # MCP and Skills configuration template
├── Makefile                 # Build and development commands
├── scripts/
│   └── docker.sh           # Docker management script
├── docker/
│   ├── docker-compose-dev.yaml  # Docker Compose configuration
│   └── nginx/
│       ├── nginx.conf      # Nginx config for Docker
│       └── nginx.local.conf # Nginx config for local dev
├── backend/                 # Backend application
│   ├── src/
│   │   ├── gateway/        # Gateway API (port 8001)
│   │   ├── agents/         # LangGraph agents (port 2024)
│   │   ├── mcp/            # Model Context Protocol integration
│   │   ├── skills/         # Skills system
│   │   └── sandbox/        # Sandbox execution
│   ├── docs/               # Backend documentation
│   └── Makefile            # Backend commands
├── frontend/               # Frontend application
│   └── Makefile            # Frontend commands
└── skills/                 # Agent skills
    ├── public/             # Public skills
    └── custom/             # Custom skills

Architecture

Browser
  ↓
Nginx (port 2026) ← Unified entry point
  ├→ Frontend (port 3000) ← / (non-API requests)
  ├→ Gateway API (port 8001) ← /api/models, /api/mcp, /api/skills, /api/threads/*/artifacts
  └→ LangGraph Server (port 2024) ← /api/langgraph/* (agent interactions)

Development Workflow

1. Create a Feature Branch

git checkout -b feature/your-feature-name

2. Make Your Changes

With hot-reload enabled in both Docker and local development, your changes will be reflected immediately:

Frontend changes reload automatically
Backend changes trigger service restarts
No need to manually restart services during development

3. Test Your Changes

Thoroughly test your changes before committing. See the Testing Guide for details on running tests.

# Backend tests
cd backend
make test

# Frontend tests
cd frontend
pnpm test

4. Commit Your Changes

Follow conventional commit message format:

git add .
git commit -m "feat: description of your changes"

Commit message prefixes:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
refactor: - Code refactoring
test: - Adding or updating tests
chore: - Maintenance tasks

5. Push and Create a Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub with:

Clear description of the changes
Reference to any related issues
Screenshots or demos for UI changes
Test results and coverage information

Pull Request Guidelines

Before Submitting

Code follows our style guide
All tests pass (make test)
New tests added for new features
Documentation updated if needed
Commit messages follow conventional format
No merge conflicts with main branch

PR Description Template

## Description
Brief description of what this PR does.

## Changes
- List of specific changes made
- Include technical details

## Testing
- How was this tested?
- What test cases were added?

## Related Issues
Fixes #123
Related to #456

## Screenshots (if applicable)
[Add screenshots for UI changes]

Review Process

Automated Checks: CI/CD runs tests and linting
Code Review: Maintainers review code quality and design
Testing: Reviewers test functionality
Approval: At least one maintainer approval required
Merge: Maintainer merges the PR

PR Regression Checks

Every pull request runs the backend regression workflow, including:

tests/test_provisioner_kubeconfig.py
tests/test_docker_sandbox_mode_detection.py
All unit tests in the test suite

These checks must pass before your PR can be merged.

Development Best Practices

Test-Driven Development (TDD)

Every new feature or bug fix MUST be accompanied by unit tests. No exceptions.

Write tests before implementing features
Ensure all tests pass before submitting PR
Aim for high test coverage
See Testing Guide for details

Code Quality

Follow the Code Style Guide
Use type hints in Python code
Write clear, self-documenting code
Add comments for complex logic
Keep functions small and focused

Documentation

CRITICAL: Always update documentation after code changes

Update README.md for user-facing changes
Update CLAUDE.md for development changes
Keep documentation synchronized with code
Add inline documentation for complex code

Debugging

See the Debugging Guide for techniques and tools to help troubleshoot issues during development.

Getting Help

Check existing Issues
Read the Documentation
Ask questions in Discussions
Review Architecture Documentation

Common Development Tasks

Adding a New API Endpoint

Add route to appropriate router in backend/src/gateway/routers/
Add corresponding tests in backend/tests/
Update API documentation
Test endpoint manually and with automated tests

Adding a New Middleware

Create middleware in backend/src/agents/middlewares/
Add middleware to chain in backend/src/agents/lead_agent/agent.py
Consider middleware order (see CLAUDE.md for details)
Add unit tests for middleware logic
Update CLAUDE.md with middleware description

Adding a New Tool

Implement tool in appropriate directory:
- Built-in: backend/src/tools/builtins/
- Community: backend/src/community/
Register tool in config.yaml under tools section
Add tool to appropriate tool group
Add tests for tool functionality
Document tool usage

Modifying Configuration Schema

Update Pydantic models in backend/src/config/
Update config.example.yaml with new fields
Add migration notes if breaking changes
Update configuration documentation
Add tests for config validation

License

By contributing to DeerFlow, you agree that your contributions will be licensed under the MIT License.

Architecture

Development

Troubleshooting

​Development Environment Setup

​Option 1: Docker Development (Recommended)

​Prerequisites

​Setup Steps

​Docker Commands

​Docker Architecture

​Option 2: Local Development

​Prerequisites

​Setup Steps

​Manual Service Control

​Nginx Configuration

​Project Structure

​Architecture

​Development Workflow

​1. Create a Feature Branch

​2. Make Your Changes

​3. Test Your Changes

​4. Commit Your Changes

​5. Push and Create a Pull Request

​Pull Request Guidelines

​Before Submitting

​PR Description Template

​Review Process

​PR Regression Checks

​Development Best Practices

​Test-Driven Development (TDD)

​Code Quality

​Documentation

​Debugging

​Getting Help

​Common Development Tasks

​Adding a New API Endpoint

​Adding a New Middleware

​Adding a New Tool

​Modifying Configuration Schema

​License

Build docs developers (and LLMs) love

Development Environment Setup

Option 1: Docker Development (Recommended)

Prerequisites

Setup Steps

Docker Commands

Docker Architecture

Option 2: Local Development

Prerequisites

Setup Steps

Manual Service Control

Nginx Configuration

Project Structure

Architecture

Development Workflow

1. Create a Feature Branch

2. Make Your Changes

3. Test Your Changes

4. Commit Your Changes

5. Push and Create a Pull Request

Pull Request Guidelines

Before Submitting

PR Description Template

Review Process

PR Regression Checks

Development Best Practices

Test-Driven Development (TDD)

Code Quality

Documentation

Debugging

Getting Help

Common Development Tasks

Adding a New API Endpoint

Adding a New Middleware

Adding a New Tool

Modifying Configuration Schema

License