mc/README.md

🎮 Minecraft Server Dashboard

A beautiful, modern web dashboard to monitor and control your Minecraft server with real-time statistics and server management.

✨ Features

• 🎯 Real-time Server Monitoring

  • Player count and online players list
  • Server version and status
  • Latency monitoring
  • TPS (Ticks Per Second) tracking

• 🎮 Server Control

  • Start server with one click
  • Stop server gracefully (with confirmation)
  • Automatic status refresh every 5 seconds

• 🎨 Beautiful UI

  • Modern gradient design
  • Minecraft-themed color palette
  • Responsive layout for all devices
  • Smooth animations and transitions
  • Real-time status indicators

🏗️ Architecture

Backend

• Node.js + Express - RESTful API server
• RCON Integration - Direct communication with Minecraft server
• Docker API - Container management for start/stop functionality
• minecraft-server-util - Server status queries

Frontend

• React 18 - Modern UI framework
• Vite - Lightning-fast build tool
• Tailwind CSS - Utility-first styling
• Lucide React - Beautiful icons
• Axios - HTTP client

🚀 Quick Start

Prerequisites

• Docker and Docker Compose installed
• Existing Minecraft server running on mcnet network

Installation

1. Clone or navigate to the project directory

   cd mc
   

2. Start your Minecraft server (if not already running)

   docker-compose -f docker-compose.minecraft.yml up -d
   

3. Build and start the dashboard

   docker-compose -f docker-compose.dashboard.yml up -d --build
   

4. Access the dashboard

   • Open your browser to: http://localhost:8080

Development Mode

For local development without Docker:

Backend:

cd backend
npm install
npm run dev

Frontend:

cd frontend
npm install
npm run dev

📁 Project Structure

mc/
├── backend/
│   ├── src/
│   │   └── index.js          # Express API server
│   ├── Dockerfile
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── App.jsx           # Main React component
│   │   ├── main.jsx
│   │   ├── index.css
│   │   └── App.css
│   ├── public/
│   ├── index.html
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── vite.config.js
│   └── package.json
├── docker-compose.dashboard.yml
└── README.md

🔧 Configuration

Environment Variables

Create a .env file based on .env.example:

# Minecraft Server
MINECRAFT_HOST=mc-java
MINECRAFT_PORT=25565
RCON_PORT=25575
RCON_PASSWORD=bethureddy1
CONTAINER_NAME=mc-java

# Dashboard
DASHBOARD_PORT=8080

Network Configuration

The dashboard connects to your Minecraft server via the mcnet Docker network. Make sure your Minecraft server is on this network:

networks:
  mcnet:
    external: true

📊 API Endpoints

GET /api/status

Returns Minecraft server status including:

• Online status
• Player count and list
• Server version
• Latency
• TPS (if available)
• MOTD

GET /api/container/status

Returns Docker container status:

• Running state
• Container health
• Start time

POST /api/server/start

Starts the Minecraft server container

POST /api/server/stop

Gracefully stops the Minecraft server (saves world first)

🎨 UI Components

Status Cards

• Players - Current player count vs max players
• Version - Minecraft server version
• Latency - Server response time
• TPS - Server performance metric

Control Panel

• Start Button - Starts the server (disabled when running)
• Stop Button - Stops the server with confirmation (disabled when stopped)
• Refresh Button - Manually refresh status

Player List

• Displays all currently online players
• Beautiful avatar placeholders
• Grid layout for easy viewing

🐛 Troubleshooting

Dashboard can't connect to Minecraft server

• Ensure Minecraft server is running: docker ps | grep mc-java
• Verify both containers are on mcnet network
• Check RCON is enabled in server configuration

Start/Stop buttons not working

• Ensure backend has access to Docker socket
• Verify volume mount: /var/run/docker.sock:/var/run/docker.sock
• Check container name matches: CONTAINER_NAME=mc-java

RCON connection failed

• Verify RCON password matches Minecraft server
• Check RCON port (default: 25575)
• Ensure RCON is enabled in server.properties

🔒 Security Notes

• The dashboard requires access to Docker socket for start/stop functionality
• RCON password is configured via environment variables
• Consider using Docker secrets for production deployments
• Restrict dashboard access using firewall rules or reverse proxy authentication

📝 License

MIT

🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

💖 Acknowledgments

• Built with React and Node.js
• Minecraft server status via minecraft-server-util
• RCON implementation using modern-rcon
• Icons by Lucide React