💻 Development Setup

This document provides detailed instructions on setting up a local development environment for Wegent.

📋 Prerequisites

Before starting, ensure your development environment has the following software installed:

Required Software

Python 3.10+: For backend service, Executor, and Executor Manager
Node.js 18+: For frontend development
MySQL 8.0+: Database service
Redis 7+: Cache service
Docker & Docker Compose: For containerized deployment and development
Git: Version control

Recommended Tools

Visual Studio Code: Code editor
Postman or curl: API testing
MySQL Workbench: Database management

🚀 Quick Experience

If you just want to quickly experience Wegent, use Docker Compose:

# Clone the repository
git clone https://github.com/wecode-ai/wegent.git
cd wegent

# Start all services
docker-compose up -d

# Access the web interface
# http://localhost:3000

This will start all required services:

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Documentation: http://localhost:8000/api/docs
MySQL: localhost:3306
Redis: localhost:6379
Executor Manager: http://localhost:8001

🔧 Local Development Setup

If you need to modify code and develop, follow these steps to set up your local development environment.

1️⃣ Database Configuration

Run MySQL with Docker

docker run -d \
  --name wegent-mysql \
  -e MYSQL_ROOT_PASSWORD=123456 \
  -e MYSQL_DATABASE=task_manager \
  -e MYSQL_USER=task_user \
  -e MYSQL_PASSWORD=task_password \
  -p 3306:3306 \
  mysql:9.4

Or Use Local MySQL

# Login to MySQL
mysql -u root -p

# Create database
CREATE DATABASE task_manager;

# Create user
CREATE USER 'task_user'@'localhost' IDENTIFIED BY 'task_password';

# Grant privileges
GRANT ALL PRIVILEGES ON task_manager.* TO 'task_user'@'localhost';
FLUSH PRIVILEGES;

Note: Database tables and initial data will be created automatically on first backend startup, no need to execute SQL scripts manually.

2️⃣ Redis Configuration

Run Redis with Docker

docker run -d \
  --name wegent-redis \
  -p 6379:6379 \
  redis:7

Or Use Local Redis

# macOS
brew install redis
brew services start redis

# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis

# Verify Redis is running
redis-cli ping
# Should return PONG

3️⃣ Backend Service Development

The backend service is a RESTful API service based on FastAPI.

Install Dependencies

cd backend

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# macOS/Linux:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

# Install dependencies
uv sync

Configure Environment Variables

# Copy environment template
cp .env.example .env

# Edit .env file
# Main configuration items:
# DATABASE_URL=mysql+pymysql://task_user:task_password@localhost:3306/task_manager
# REDIS_URL=redis://127.0.0.1:6379/0
# PASSWORD_KEY=your-password-key-here
# EXECUTOR_DELETE_TASK_URL=http://localhost:8001/executor-manager/executor/delete

Run Development Server

# Run with uvicorn, hot reload enabled
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Access API documentation:

Swagger UI: http://localhost:8000/api/docs
ReDoc: http://localhost:8000/api/redoc

Backend Directory Structure

backend/
├── app/
│   ├── api/              # API routes
│   ├── core/            # Core configuration
│   ├── db/              # Database connection
│   ├── models/          # SQLAlchemy models
│   ├── repository/      # Data access layer
│   ├── schemas/         # Pydantic schemas
│   └── services/        # Business logic layer
├── init_data/           # YAML initialization data
└── pyproject.toml       # Python dependencies

4️⃣ Frontend Service Development

The frontend is a React application based on Next.js 15.

Install Dependencies

cd frontend

# Install npm dependencies
npm install

Configure Environment Variables

# Copy environment template
cp .env.local.example .env.local

# Edit .env.local file
# Main configuration items (runtime variables, can be changed without rebuilding):
# RUNTIME_INTERNAL_API_URL=http://localhost:8000  # Server-side proxy URL
# RUNTIME_SOCKET_DIRECT_URL=http://localhost:8000 # WebSocket connection URL
# Legacy (deprecated): NEXT_PUBLIC_API_URL=http://localhost:8000
# NEXT_PUBLIC_USE_MOCK_API=false
# NEXT_PUBLIC_LOGIN_MODE=all
# I18N_LNG=en

Note: The frontend now uses RUNTIME_INTERNAL_API_URL and RUNTIME_SOCKET_DIRECT_URL instead of NEXT_PUBLIC_API_URL. Runtime variables can be changed without rebuilding the application.

Run Development Server

# Start development server
npm run dev

Access application: http://localhost:3000

Other Commands

# Lint code
npm run lint

# Format code
npm run format

# Production build
npm run build

# Run production version
npm run start

5️⃣ Executor Manager Development

Executor Manager is responsible for managing and scheduling Executor containers.

Install Dependencies

cd executor_manager

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
uv sync

Run Development Server

# Set environment variables
export TASK_API_DOMAIN=http://localhost:8000
export CALLBACK_HOST=http://localhost:8001
export MAX_CONCURRENT_TASKS=5
export EXECUTOR_IMAGE=ghcr.io/wecode-ai/wegent-executor:latest
export EXECUTOR_WORKSPACE=${HOME}/wecode-bot

# Run service
python main.py

📂 Project Structure

Complete project structure:

wegent/
├── backend/                 # FastAPI backend service
├── frontend/                # Next.js frontend application
├── executor/                # Task executor
├── executor_manager/        # Executor manager
├── shared/                  # Shared code and models
├── docker/                  # Docker configurations
├── docs/                    # Documentation
└── docker-compose.yml       # Docker Compose configuration

🔬 Testing

Wegent provides comprehensive testing framework coverage across all core modules.

Backend Testing

cd backend

# Run all tests
pytest

# Run specific test module
pytest tests/core/

# Run with coverage report
pytest --cov=app --cov-report=html

# Run only unit tests
pytest -m unit

# Run only integration tests
pytest -m integration

Frontend Testing

cd frontend

# Run tests
npm test

# Run and watch for changes
npm run test:watch

# Generate coverage report
npm run test:coverage

Executor and Shared Module Testing

# Executor tests
cd executor
pytest tests/ --cov=agents

# Executor Manager tests
cd executor_manager
pytest tests/ --cov=executors

# Shared utilities tests
cd shared
pytest tests/ --cov=utils

Complete Testing Guide

For detailed testing framework documentation, best practices, and CI/CD configuration, see:

📖 Complete Testing Guide - Test framework documentation, Fixtures, Mocking strategies, and more

🐛 Debugging Tips

Backend Debugging

# Enable verbose logging
export LOG_LEVEL=DEBUG
uvicorn app.main:app --reload --log-level debug

Frontend Debugging

In browser developer tools, check:

Console: JavaScript errors and logs
Network: API requests and responses
React DevTools: Component state and performance

Executor Debugging

# View container logs
docker logs -f <executor-container-id>

# Enter container for debugging
docker exec -it <executor-container-id> /bin/bash

📞 Get Help

If you encounter issues:

Check the Troubleshooting section
Search GitHub Issues
Read related documentation:
- YAML Specification
- Core Concepts
Create a new Issue with detailed information

Testing - Testing guide

Happy coding! 🚀

📋 Prerequisites​

Required Software​

Recommended Tools​

🚀 Quick Experience​

🔧 Local Development Setup​

1️⃣ Database Configuration​

Run MySQL with Docker​

Or Use Local MySQL​

2️⃣ Redis Configuration​

Run Redis with Docker​

Or Use Local Redis​

3️⃣ Backend Service Development​

Install Dependencies​

Configure Environment Variables​

Run Development Server​

Backend Directory Structure​

4️⃣ Frontend Service Development​

Install Dependencies​

Configure Environment Variables​

Run Development Server​

Other Commands​

5️⃣ Executor Manager Development​

Install Dependencies​

Run Development Server​

📂 Project Structure​

🔬 Testing​

Backend Testing​

Frontend Testing​

Executor and Shared Module Testing​

Complete Testing Guide​

🐛 Debugging Tips​

Backend Debugging​

Frontend Debugging​

Executor Debugging​

📞 Get Help​

🔗 Related Resources​

📋 Prerequisites

Required Software

Recommended Tools

🚀 Quick Experience

🔧 Local Development Setup

1️⃣ Database Configuration

Run MySQL with Docker

Or Use Local MySQL

2️⃣ Redis Configuration

Run Redis with Docker

Or Use Local Redis

3️⃣ Backend Service Development

Install Dependencies

Configure Environment Variables

Run Development Server

Backend Directory Structure

4️⃣ Frontend Service Development

Install Dependencies

Configure Environment Variables

Run Development Server

Other Commands

5️⃣ Executor Manager Development

Install Dependencies

Run Development Server

📂 Project Structure

🔬 Testing

Backend Testing

Frontend Testing

Executor and Shared Module Testing

Complete Testing Guide

🐛 Debugging Tips

Backend Debugging

Frontend Debugging

Executor Debugging

📞 Get Help

🔗 Related Resources