Contributing to DeerFlow

Learn how to contribute to DeerFlow with development setup, workflow guidelines, and pull request process

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

1. 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
   

2. 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

3. 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

4. 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

1. Configure the application (same as Docker setup above)

2. Install dependencies:

   make install
   

3. Run development server (starts all services with nginx):

   make dev
   

4. 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:

1. 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
   

2. Start nginx:

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

3. 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

1. Automated Checks: CI/CD runs tests and linting
2. Code Review: Maintainers review code quality and design
3. Testing: Reviewers test functionality
4. Approval: At least one maintainer approval required
5. 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

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

Adding a New Middleware

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

Adding a New Tool

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

Modifying Configuration Schema

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

License

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