RobustMQ-Copilot

December 8, 2025 · View on GitHub

The one-step RobustMQ operation and maintenance management platform.

Quick Start

Prerequisites

  • Node >= 20.0
  • pnpm >= 10.0

Installation

  1. Clone the project and install dependencies:
git clone <repository-url>
cd robustmq-copilot
pnpm install
  1. Start the development server:
pnpm ui:dev

The web UI will be available at http://localhost:4000

Usage Guide

Development Commands

# Start development server (default port 4000)
pnpm ui:dev

# Start development server on custom port
PORT_DEV=8080 pnpm ui:dev

# Build for production
pnpm ui:build

# Preview production build
pnpm ui:preview

Configuration

The project supports flexible configuration through environment variables and configuration files.

Port Configuration

# Set development server port
PORT_DEV=8080 pnpm ui:dev

# Set preview server port
PORT_PREVIEW=8080 pnpm ui:preview

# Set build port
PORT_BUILD=8080 pnpm ui:build

API Address Configuration

The system automatically detects the current page address for API requests, but you can override this with environment variables:

# Set custom HTTP API address
API_BASE_URL=http://localhost:8080 pnpm ui:dev

Application Configuration

# Set application title
APP_TITLE="My Custom Title" pnpm ui:dev

# Set application description
APP_DESCRIPTION="My Custom Description" pnpm ui:dev

# Set theme color
APP_THEME_COLOR="#000000" pnpm ui:dev

Development Configuration

# Set development server host
DEV_HOST=0.0.0.0 pnpm ui:dev

# Disable auto-open browser
DEV_OPEN=false pnpm ui:dev

# Disable hot reload
DEV_HOT=false pnpm ui:dev

Predefined Scripts

The project includes several predefined scripts for common configurations:

# Development with custom ports
pnpm run dev:8080    # Start dev server on port 8080
pnpm run dev:3001    # Start dev server on port 3001

# Preview with custom ports
pnpm run preview:8080  # Start preview server on port 8080
pnpm run preview:3001  # Start preview server on port 3001

Configuration Priority

  1. Environment Variables (Highest Priority)
  2. Configuration File Defaults (Medium Priority)
  3. Hardcoded Defaults (Lowest Priority)

For API addresses specifically:

  1. Environment Variable API Address (Highest Priority)
  2. Current Page Address (Medium Priority)
  3. Default Fallback Address (Lowest Priority)

Configuration Files

Configuration is managed through packages/web-ui/config/app.js. You can view the current configuration in the browser console via window.__APP_CONFIG__.

Common Use Cases

Local Development

# Standard local development
pnpm ui:dev
# Access at http://localhost:4000

Development with Custom Backend

# Connect to remote API server
API_BASE_URL=http://192.168.1.100:8080 pnpm ui:dev
# Frontend at http://localhost:4000, API calls to http://192.168.1.100:8080

Multi-Service Development

# Different services on different servers
API_BASE_URL=http://api-server:8080 \
API_GRPC_URL=http://grpc-server:8080 \
API_PLACEMENT_GRPC_URL=http://placement-server:1228 \
pnpm ui:dev

Production Build with Custom Configuration

# Build with production API endpoints
API_BASE_URL=https://api.production.com \
API_GRPC_URL=https://grpc.production.com \
pnpm ui:build

Network Access Development

# Allow network access to development server
DEV_HOST=0.0.0.0 PORT_DEV=8080 pnpm ui:dev
# Access from other devices on network at http://your-ip:8080

Development

Project Structure

robustmq-copilot/
├── packages/
│   ├── web-ui/           # Frontend React application
│   │   ├── src/          # Source code
│   │   ├── config/       # Configuration files
│   │   └── dist/         # Build output
│   └── services/         # gRPC service definitions
└── package.json          # Root package configuration

Development Setup

  1. Clone the project:
git clone <repository-url>
cd robustmq-copilot
  1. Install dependencies:
pnpm install
  1. Start development:
pnpm ui:dev

Configuration Development

The configuration system is located in packages/web-ui/config/:

  • app.js - Main configuration file
  • README.md - Detailed configuration documentation

Build and Deployment

# Development build
pnpm ui:dev

# Production build
pnpm ui:build

# Preview production build
pnpm ui:preview

Environment Variables

All configuration can be overridden with environment variables. See the Configuration section for details.

Troubleshooting

Port Already in Use

If you encounter port conflicts:

# Use a different port
PORT_DEV=8080 pnpm ui:dev

# Or kill existing processes
pkill -f "rsbuild dev"

API Connection Issues

If API requests fail:

  1. Check if the backend service is running
  2. Verify API address configuration: 
    # Use custom API address
API_BASE_URL=http://your-api-server:8080 pnpm ui:dev
  3. Check browser console for configuration: window.__APP_CONFIG__

Build Issues

If builds fail:

  1. Clear node_modules and reinstall: 
    rm -rf node_modules
pnpm install
  2. Clear build cache: 
    rm -rf packages/web-ui/dist
pnpm ui:build

Technology Stack

  • Frontend: React 19, TypeScript, TanStack Router, TanStack Query
  • UI Components: Radix UI, Tailwind CSS
  • Build Tool: Rsbuild
  • Package Manager: pnpm
  • State Management: Zustand

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/your-feature-name
  3. Make your changes and test them thoroughly
  4. Commit your changes: git commit -m 'Add some feature'
  5. Push to the branch: git push origin feature/your-feature-name
  6. Submit a pull request

Development Guidelines

  • Follow the existing code style and patterns
  • Add TypeScript types for new features
  • Update configuration documentation when adding new environment variables
  • Test your changes with different configuration scenarios
  • Ensure backward compatibility when possible

License

This project is licensed under the terms specified in the LICENSE file.