Local Microservice Testing Tool

A command-line tool with web interface for spinning up and managing local microservice environments for development and testing.

🚀 Features

• Easy Service Management: Start and stop multiple microservices with a single command
• Web-based GUI: Monitor and control services through an intuitive React-based interface
• Real-time Log Streaming: View live logs from all services with filtering and search capabilities
• Docker Compose Integration: Automatic generation and management of Docker Compose configurations
• Configuration Editor: Built-in editor for service configurations with syntax highlighting
• Service Status Monitoring: Real-time status indicators for all running services
• Cross-platform Support: Works on Windows, macOS, and Linux

📋 Requirements

• Docker (for container management)
• Docker Compose (for service orchestration)
• Go 1.24+ (for building from source)

🛠 Installation

From Source

1. Clone the repository:

git clone <repository-url>
cd duke-backend-utils

2. Build the CLI tool:

go build -o tester main.go

3. Build the web interface:

cd web
bun install
bun run build
cd ..

📖 Usage

Quick Start

1. Create a configuration file (see Configuration section):

cp sample.yml config.yml
# Edit config.yml to define your services

2. Start the complete environment:

./tester run --config config.yml

This command will:

• Start all defined microservices using Docker Compose
• Launch the web interface at http://localhost:8050
• Gracefully shutdown everything when you press Ctrl+C

Available Commands

tester run

Orchestrates the complete environment - starts services and web interface, stops everything on exit.

./tester run --config config.yml

tester up

Start microservices using Docker Compose in the background.

./tester up --config config.yml

tester down

Stop all running microservices and clean up.

./tester down

tester web

Start only the web interface (assumes services are already running).

./tester web

Command Options

• --config <file>: Specify configuration file path (supports .yml, .yaml, and .json)

⚙️ Configuration

Create a YAML or JSON configuration file to define your microservices:

YAML Example (config.yml)

services:
  mysql:
    image: mysql:8.0
    port: 3306
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: my_database

  redis:
    image: redis:7-alpine
    port: 6379
    environment:
      REDIS_PASSWORD: mypassword

  api-gateway:
    image: my-company/api-gateway:latest
    port: 8080
    environment:
      DB_HOST: mysql
      REDIS_HOST: redis
      ENV: development

JSON Example (config.json)

{
  "services": {
    "mysql": {
      "image": "mysql:8.0",
      "port": "3306",
      "environment": {
        "MYSQL_ROOT_PASSWORD": "root",
        "MYSQL_DATABASE": "my_database"
      }
    },
    "redis": {
      "image": "redis:7-alpine",
      "port": "6379"
    }
  }
}

Configuration Fields

• image (required): Docker image name and tag
• port (optional): Port to expose (maps container port to same host port)
• environment (optional): Environment variables for the service

🌐 Web Interface

The web interface provides:

Service Management

• Service List: Overview of all configured services with status indicators
• Individual Control: Start/stop individual services
• Bulk Operations: Start/stop all services at once

Log Monitoring

• Real-time Logs: Live log streaming for each service in separate tabs
• Log Controls: Pause/resume streaming, clear logs
• Filtering: Filter logs by severity level (Info, Warning, Error)
• Search: Find specific keywords within logs

Configuration Editor

• Live Editing: Edit service configurations directly in the web interface
• Syntax Highlighting: YAML syntax highlighting for better readability
• Auto-save: Automatically save configuration changes

Access the web interface at: http://localhost:8050

🏗 Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Tool      │    │  Web Interface  │    │ Docker Compose  │
│   (Go/Cobra)    │◄──►│   (React)       │◄──►│   Services      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Configuration  │    │   WebSocket     │    │    Service      │
│     Parser      │    │   Log Stream    │    │     Logs        │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Components

• CLI Tool: Go-based command processor using Cobra framework
• Web Server: HTTP server serving React frontend and REST API
• Log Streaming: WebSocket-based real-time log delivery
• Docker Integration: Automatic Docker Compose file generation and management

🔧 Development

Project Structure

├── cmd/                 # CLI commands (up, down, web, run)
├── internal/
│   ├── config/         # Configuration parsing
│   ├── controllers/    # Web API handlers
│   └── server/         # HTTP server setup
├── utils/              # Shared utilities
├── web/                # React frontend
│   ├── src/
│   │   ├── app/        # Route components
│   │   └── components/ # Reusable components
│   └── dist/           # Built frontend (after npm run build)
└── main.go            # Application entry point

Building

Backend:

go build -o tester main.go

Frontend:

cd web
bun install
bun run build

Running in Development

Start backend in development mode:

go run main.go run --config config.yml

Start frontend development server:

cd web
npm run dev

🐛 Troubleshooting

Common Issues

1. "Docker is not installed"

   • Install Docker Desktop or Docker Engine
   • Ensure Docker is in your system PATH

2. "Docker Compose is not installed"

   • Install Docker Compose or use Docker Desktop (includes Compose)

3. "No active Docker Compose environment found"

   • Run tester up --config <file> first, or use tester run for full orchestration

4. Web interface shows no services

   • Ensure your configuration file is valid YAML/JSON
   • Check that services are properly defined in the config

5. Services won't start

   • Verify Docker images exist and are accessible
   • Check for port conflicts with other running services
   • Review Docker Compose logs for specific error messages

Debug Information

• State file location: Stored in system temp directory as duke-compose-state.json
• Generated compose files: Created in temporary directories with prefix tester-compose
• Log level: Set environment variable LOG_LEVEL=debug for verbose output

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎯 Future Roadmap

• Kubernetes integration (Minikube/Kind support)
• Service dependency management and startup ordering
• Resource usage monitoring (CPU, memory)
• Integration with testing frameworks
• Advanced log analysis and filtering
• Service health checks and auto-restart
• Configuration templates and presets
• Multi-environment support