Skip to main content

πŸ“¦ Installation Guide

This guide provides detailed installation and configuration instructions for the Wegent platform, including system requirements, installation steps, and configuration options.

πŸ“‹ System Requirements​

Hardware Requirements​

ComponentMinimumRecommended
CPU2 cores4 cores or more
Memory4 GB8 GB or more
Storage20 GB50 GB or more
NetworkStable internet connection-

Software Requirements​

Required Software​

  • Docker: 20.10+
  • Docker Compose: 2.0+
  • Git: 2.0+

Optional Software (for development)​

  • Python: 3.10+
  • Node.js: 18+
  • MySQL: 8.0+
  • Redis: 7+

πŸš€ Installation Methods​

Wegent supports two main installation methods:

Suitable for quick deployment and production environments.

Method 2: Source Installation​

Suitable for development and custom deployments.

πŸ“¦ Method 1: Docker Compose Installation​

Step 1: Clone the Repository​

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

# Enter project directory
cd wegent

Step 2: Configure Environment Variables​

# Copy environment template
cp .env.example .env

# Edit .env file
vim .env  # or use another editor

Key Environment Variables​

# MySQL Configuration
MYSQL_ROOT_PASSWORD=your_root_password
MYSQL_DATABASE=task_manager
MYSQL_USER=task_user
MYSQL_PASSWORD=your_password

# Redis Configuration
REDIS_PASSWORD=your_redis_password  # Optional
REDIS_PROTOCOL=2  # Default RESP2, compatible with Redis-compatible servers without HELLO support

# Backend Configuration
PASSWORD_KEY=your-password-key-here
USER_AES_KEY=base64:your-32-byte-base64-key
GIT_TOKEN_AES_KEY=your-32-byte-sensitive-data-key
GIT_TOKEN_AES_IV=your-16-byte-iv
DATABASE_URL=mysql+pymysql://task_user:your_password@mysql:3306/task_manager
CHECK_SYSTEM_INITIALIZATION_STATUS=True

# Sites Platform configuration (optional)
# SITES_API_BASE_URL=https://sites-platform.example.com
# SITES_API_TOKEN=your-sites-platform-token

# Attachment Storage Configuration (Optional)
# Default: mysql (stores files in database)
# Options: mysql, s3, minio
ATTACHMENT_STORAGE_BACKEND=mysql

# S3/MinIO Configuration (only required when using s3 or minio backend)
# ATTACHMENT_S3_ENDPOINT=https://s3.amazonaws.com  # or http://minio:9000
# ATTACHMENT_S3_ACCESS_KEY=your_access_key
# ATTACHMENT_S3_SECRET_KEY=your_secret_key
# ATTACHMENT_S3_BUCKET=attachments
# ATTACHMENT_S3_REGION=us-east-1
# ATTACHMENT_S3_USE_SSL=true

# Frontend Configuration
# Runtime variables (recommended, can be changed without rebuilding)
# Set via docker-compose.yml environment section
# RUNTIME_INTERNAL_API_URL=http://backend:8000
# RUNTIME_SOCKET_DIRECT_URL=http://backend:8000
# RUNTIME_WEWORK_CODE_URL=https://wework.example.com/coding  # Optional: route coding entry points to Wework
# Legacy (deprecated): NEXT_PUBLIC_API_URL=http://localhost:8000

# Wework frontend build configuration (optional)
# Sets the scaling Wiki link in the cloud device resource note card under Settings -> Connections
# VITE_CLOUD_DEVICE_SCALING_WIKI_URL=https://wiki.example.com/cloud-device-scaling

# Image configuration
# Set to edge when testing CI-published edge images
WEGENT_IMAGE_TAG=latest

# Executor Manager Configuration
# Optional: explicitly override the executor image; leave unset to follow WEGENT_IMAGE_TAG
# EXECUTOR_IMAGE=ghcr.io/wecode-ai/wegent-executor:latest
EXECUTOR_WORKSPACE=/path/to/workspace

When RUNTIME_WEWORK_CODE_URL is empty, Wegent Web opens coding entry points at /chat?agent=code and filters to coding agents. When it is configured, the sidebar shows WeWork instead of Code and opens that runtime URL. This setting is delivered only through /runtime-config; there is no NEXT_PUBLIC_* fallback.

Step 3: Start Services​

# Start all services
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f

To test CI-published edge images, set the shared image tag:

WEGENT_IMAGE_TAG=edge docker compose up -d

Build the hybrid Backend from source​

docker compose -f docker-compose.yml -f docker-compose.build.yml --profile rag up -d

The backend image runs the Rust gateway and Python in one container. Rust listens publicly on port 8000, selects migrated APIs using backend-rs/config/routes.toml, and forwards other requests to the internal 127.0.0.1:8004 listener. The service name, client URLs and existing log mount stay unchanged. Rust is built inside the image; the host needs no Rust toolchain.

The runtime reuses the hybrid launcher with a prebuilt gateway and no Python development reloader. Container shutdown forwards termination to both processes; when either exits, the launcher cleans up the other, and the existing Compose restart policy restores the service. Health checks reach Python's /api/health through Rust. GRACEFUL_SHUTDOWN_TIMEOUT still controls Python's drain timeout; allow enough time for active requests when using docker compose stop -t.

Inject configuration through Compose's environment: real .env files and local Cargo target directories are excluded from the image build context.

PRs changing backend image inputs also build the delivery docker/backend/Dockerfile once in the independent Verify Backend Delivery Image CI job. The same image is checked against real MySQL and Redis services for initialization, Rust routes, Python forwarding, restart, and process shutdown. Frontend-only changes do not select this check; scheduled runs, full manual runs, and ci:all do. Build layers read the published GHCR cache without writing it. Browser shards do not repeat the build, and the image is not published. Delivery verification and runtime artifact production have separate time budgets; CI requires both jobs to succeed when selected.

CI uploads logs and the source revision/image ID as backend-delivery-evidence. This check covers Linux amd64; complete images for other architectures still require separate validation. Passing local script unit tests is not evidence that the delivery image works: use the actual CI build and container results for the corresponding commit.

When using install.sh, you can also pass the edge shortcut directly:

curl -fsSL https://raw.githubusercontent.com/wecode-ai/Wegent/main/install.sh | bash -s -- --edge

Step 4: Verify Installation​

Wait for services to start completely (about 30 seconds). Database tables and initial data will be created automatically.

Visit the following URLs to verify installation:

  • Frontend: http://localhost:3000
  • Backend API: http://localhost:8000
  • API Documentation: http://localhost:8000/api/docs
  • Executor Manager: http://localhost:8001

Step 5: Configure GitHub Integration (Optional)​

  1. Visit http://localhost:3000
  2. Follow on-screen instructions to configure GitHub Personal Access Token
  3. Required token permissions:
    • repo - Full repository access
    • workflow - Workflow permissions

πŸ’» Method 2: Source Installation​

Step 1: Install Required Software​

On Ubuntu/Debian​

# Update package list
sudo apt-get update

# Install Python
sudo apt-get install python3.10 python3-pip python3-venv

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install MySQL
sudo apt-get install mysql-server

# Install Redis
sudo apt-get install redis-server

# Install Git
sudo apt-get install git

On macOS​

# Install using Homebrew
brew install python@3.10 node@18 mysql redis git

Step 2: Setup Database​

# Start MySQL
sudo systemctl start mysql  # Linux
# or
brew services start mysql  # macOS

# Login to MySQL
mysql -u root -p

# Create database and user
CREATE DATABASE task_manager;
CREATE USER 'task_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON task_manager.* TO 'task_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 3: Setup Redis​

# Start Redis
sudo systemctl start redis  # Linux
# or
brew services start redis  # macOS

# Verify Redis
redis-cli ping  # Should return PONG

Step 4: Install Backend​

# Enter backend directory
cd backend

# Create virtual environment
python3 -m venv venv

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

# Install dependencies
uv sync

# Configure environment variables
cp .env.example .env
vim .env  # Edit configuration

# Create database (tables and initial data will be created automatically on first startup)
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS task_manager CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Run backend service
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Administrator password: First startup automatically creates the admin administrator account, but it does not assign a default password. By default, CHECK_SYSTEM_INITIALIZATION_STATUS=True makes the backend load the initialization state into memory at startup, and the first visit to the login page forces the administrator password setup flow. Complete that flow before logging in and using the system. Set CHECK_SYSTEM_INITIALIZATION_STATUS=False only for deployments that must skip this check.

Step 5: Install Frontend​

In a new terminal:

# Return to the repository root
cd Wegent

# Install pnpm workspace dependencies
pnpm install

# Configure environment variables
cd frontend
cp .env.local.example .env.local
vim .env.local  # Edit configuration

# Run development server
pnpm run dev

The repository root pnpm-workspace.yaml declares the dependency build-script allowlist required by pnpm and disables node_modules rebuild confirmation in non-interactive environments. Developers and Git hooks should run pnpm install from the repository root and should not maintain separate approve-builds settings in subdirectories.

Step 6: Install Executor Manager​

Local Development

βš™οΈ Advanced Configuration​

Custom Ports​

Modify docker-compose.yml or environment variables to customize ports:

# docker-compose.yml
services:
  frontend:
    ports:
      - "3001:3000" # Change to 3001
  backend:
    ports:
      - "8001:8000" # Change to 8001

Configure HTTPS​

For production environments, use Nginx reverse proxy to configure HTTPS:

# Install Nginx
sudo apt-get install nginx

# Configure reverse proxy
sudo vim /etc/nginx/sites-available/wegent

Example Nginx configuration:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Data Persistence​

Ensure Docker volumes are configured correctly for data persistence:

# docker-compose.yml
volumes:
  mysql_data:
  redis_data:
  workspace_data:

services:
  mysql:
    volumes:
      - mysql_data:/var/lib/mysql

  redis:
    volumes:
      - redis_data:/data

πŸ” Verify Installation​

Check Service Status​

# Docker Compose method
docker-compose ps

# Should see all services in Up status

Test API​

# Test backend API
curl http://localhost:8000/api/health

# Should return: {"status": "ok"}

Test Frontend​

Visit http://localhost:3000 in your browser, you should see the Wegent login page.

πŸ› Common Issues​

Issue 1: Port Already in Use​

Error: Error: Port 3000 is already in use

Solution:

# Find process using the port
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or modify port configuration

Issue 2: MySQL Connection Failed​

Error: Can't connect to MySQL server

Solution:

# Ensure MySQL is running
docker-compose ps mysql
# or
sudo systemctl status mysql

# Check connection configuration
mysql -u task_user -p -h localhost task_manager

Issue 3: Redis Connection Failed​

Error: Error connecting to Redis

Solution:

# Ensure Redis is running
redis-cli ping

# Check Redis configuration
docker-compose logs redis

Issue 4: Docker Image Pull Failed​

Error: Error pulling image

Solution:

# Use mirror registry
# Edit /etc/docker/daemon.json
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

# Restart Docker
sudo systemctl restart docker

πŸ”„ Upgrade and Update​

Upgrade to Latest Version​

# Pull latest code
git pull origin main

# Rebuild images
docker-compose build

# Restart services
docker-compose down
docker-compose up -d

# Update database
docker-compose exec backend python -m alembic upgrade head

Deprecated Environment Variables (Upgrade Note)​

RAG_RUNTIME_MODE is deprecated; delete it from .env after upgrading. RAG now has exactly one execution path: index, query and delete all run in the knowledge_runtime service. Backend knowledge features require an accessible Knowledge Runtime service.

  • Docker Compose deployments: docker compose up -d starts the Backend and knowledge_runtime together; no extra profile is needed for knowledge_runtime.
  • start.sh deployments: omitting service names starts all services, including Knowledge Runtime. Explicit service selections apply independently to start, stop, and restart. ./start.sh --restart fe be restarts only the frontend and Backend, keeping an existing Runtime running; use ./start.sh --restart fe be kr to restart Runtime too. If Runtime is not running, start it with ./start.sh kr or configure an existing service through KNOWLEDGE_RUNTIME_URL. Knowledge operations fail when no Runtime is available.
  • If an existing environment still sets RAG_RUNTIME_MODE, the variable is ignored and does not make the Backend fail to start.

πŸ—‘οΈ Uninstall​

Docker Compose Method​

# Stop and remove containers
docker-compose down

# Remove volumes (will delete all data)
docker-compose down -v

# Remove images
docker-compose down --rmi all

Source Installation Method​

# Stop all services
# Then delete project directory
rm -rf wegent

# Delete database
mysql -u root -p
DROP DATABASE task_manager;
DROP USER 'task_user'@'localhost';

πŸ“ž Get Help​

If you encounter installation issues:

  1. Check Troubleshooting Guide
  2. Search GitHub Issues
  3. View FAQ
  4. Create a new Issue to report problems

πŸ”— Next Steps​

After installation, you can:

Installation complete! Start exploring Wegent! πŸŽ‰