feat: adds docker-based dev environment (#18)

* feat: adds docker-based dev environment * docs: updates Docker command help * fix local dev
2026-04-23 22:24:46 +08:00 · 2026-01-24 22:01:00 +08:00
parent c468381064
commit 38081306fe
10 changed files with 889 additions and 100 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,267 @@
+# 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
+
+1. **Configure the application**:
+   ```bash
+   # 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
+
+   # Optional: Enable MCP servers and skills
+   cp extensions_config.example.json extensions_config.json
+   # Edit extensions_config.json to enable desired MCP servers and skills
+   ```
+
+2. **Initialize Docker environment** (first time only):
+   ```bash
+   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**:
+   ```bash
+   make docker-dev
+   ```
+   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
+
+```bash
+# View all logs
+make docker-dev-logs
+
+# View specific service logs
+./scripts/docker.sh logs --web      # Frontend only
+./scripts/docker.sh logs --api      # Backend only
+
+# Restart services
+./scripts/docker.sh restart
+
+# Stop services
+make docker-dev-stop
+
+# Get help
+./scripts/docker.sh help
+```
+
+#### 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
+```
+
+**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:
+
+```bash
+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**:
+   ```bash
+   make install
+   ```
+
+3. **Run development server** (starts all services with nginx):
+   ```bash
+   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**:
+   ```bash
+   # 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**:
+   ```bash
+   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**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** with hot-reload enabled
+
+3. **Test your changes** thoroughly
+
+4. **Commit your changes**:
+   ```bash
+   git add .
+   git commit -m "feat: description of your changes"
+   ```
+
+5. **Push and create a Pull Request**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+## Testing
+
+```bash
+# Backend tests
+cd backend
+uv run pytest
+
+# Frontend tests
+cd frontend
+pnpm test
+```
+
+## Code Style
+
+- **Backend (Python)**: We use `ruff` for linting and formatting
+- **Frontend (TypeScript)**: We use ESLint and Prettier
+
+## Documentation
+
+- [Configuration Guide](backend/docs/CONFIGURATION.md) - Setup and configuration
+- [Architecture Overview](backend/CLAUDE.md) - Technical architecture
+- [MCP Setup Guide](MCP_SETUP.md) - Model Context Protocol configuration
+
+## Need Help?
+
+- Check existing [Issues](https://github.com/bytedance/deer-flow/issues)
+- Read the [Documentation](backend/docs/)
+- Ask questions in [Discussions](https://github.com/bytedance/deer-flow/discussions)
+
+## License
+
+By contributing to DeerFlow, you agree that your contributions will be licensed under the [MIT License](./LICENSE).