etaMonitor: A Minecraft Server Monitoring System

Check out our Demo Site

• 中文文档
• English

Overview

etaMonitor is a powerful self-hosted Minecraft server monitoring system that provides real-time monitoring, data analysis, and a beautiful web interface.

Core Features

• 🌐 Real-time Monitoring: WebSocket-based real-time server status monitoring
• 💾 Data Persistence: SQLite database for storing historical monitoring data
• 📊 Data Analysis: Player online statistics and trend analysis with chart visualization
• 🔔 Activity Notifications: Real-time player join/leave notifications (15-minute activity records)
• 🖥️ Multi-Server: Support for monitoring multiple Minecraft servers simultaneously
• 🎮 Version Compatibility: Automatic detection of Java/Bedrock server versions
• 🌐 SRV Records: Support for SRV DNS record resolution
• 🔐 Security Authentication: JWT authentication and HTTPS security alerts
• 💼 Database Management: Support for database backup, restore, and intelligent optimization
• 🎨 Modern Interface: Material Design 3 style interface based on MDUI
• 📱 Responsive Design: Perfect adaptation for desktop and mobile devices with adaptive chart controls

Quick Start

1. Download and Install

Download the latest version for your platform from GitHub Releases:

2. First Launch

./etamonitor

The first launch will automatically:

• Create default configuration file config.json, see Configuration File
• Require setting up administrator account and password
• Initialize SQLite database

3. Access the System

Default access address: http://127.0.0.1:11451

Log in with the administrator account you just set up to start adding and monitoring Minecraft servers.

Configuration File

Specify Configuration File Path

./etamonitor -c /path/to/your/config.json

Configuration Details

Complete configuration file example:

{
  "server": {
    "host": "127.0.0.1",
    "port": "11451", 
    "environment": "release"
  },
  "database": {
    "path": "./data/etamonitor.db"
  },
  "jwt": {
    "secret": "your-secret-key-change-in-production",
    "expires_in": "24h"
  },
  "monitor": {
    "interval": "10s",
    "ping_timeout": "10s", 
    "max_concurrent": 10,
    "activity_retention_time": "15m"
  },
  "logging": {
    "level": "info",
    "format": "json"
  },
  "cors": {
    "allow_origins": ["*"],
    "allow_credentials": true
  }
}

Configuration Description

Server Configuration:

• server.host: Listening address
• server.port: Listening port (default 11451)
• server.environment: Runtime environment (release/debug)

Database Configuration:

• database.path: SQLite database file path

JWT Configuration:

• jwt.secret: JWT secret key (must change in production, randomly generated by default)
• jwt.expires_in: JWT token validity period (e.g., 24h, 7d)

Monitor Configuration:

• monitor.interval: Monitoring check interval (recommended 5-30 seconds)
• monitor.ping_timeout: Server ping timeout
• monitor.max_concurrent: Maximum concurrent monitoring count
• monitor.activity_retention_time: Player activity record retention time (e.g., 15m, 30m)

Logging Configuration:

• logging.level: Log level (debug, info, warn, error, fatal)
• logging.format: Log format (text, json)

CORS Configuration:

• cors.allow_origins: Allowed origins for cross-origin requests
• cors.allow_credentials: Allow sending cookies

Environment Variable Support

Configuration can be overridden through environment variables:

# Basic configuration
export HOST=0.0.0.0
export PORT=8080
export GIN_MODE=release

# Database configuration
export DB_PATH=/var/lib/etamonitor/data.db

# JWT configuration
export JWT_SECRET=your-production-secret-key
export JWT_EXPIRES_IN=7d

# Monitor configuration
export MONITOR_INTERVAL=15s
export PING_TIMEOUT=5s
export MAX_CONCURRENT=20
export ACTIVITY_RETENTION_TIME=30m

# Logging configuration
export LOG_LEVEL=warn
export LOG_FORMAT=text

Deployment Guide

Persistent Running (Systemd)

Create system service file:

sudo nano /etc/systemd/system/etamonitor.service

[Unit]
Description=etaMonitor - Minecraft Server Monitor
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/etamonitor
ExecStart=/path/to/etamonitor/etamonitor # Change to executable program path
Restart=always
RestartSec=5
# Environment=GIN_MODE=release
# Environment=HOST=127.0.0.1
# Environment=PORT=11451

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable etamonitor
sudo systemctl start etamonitor
sudo systemctl status etamonitor

Reverse Proxy (Nginx)

Using Nginx for reverse proxy to enable HTTPS:

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL configuration
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;

    location / {
        proxy_pass http://127.0.0.1:11451;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

Building the Project

See the BUILD_PROJECT.md file in the project root directory for complete compilation and release guide.

Quick Build

# Clone the project
git clone https://github.com/HwlloChen/etaMonitor.git
cd etaMonitor

# One-click build
make

# Run
make run

Usage Instructions

Adding a Server

1. Log in to the admin panel
2. Click "Add Server"
3. Enter server information:
   • Server name
   • Address
   • Port
   • Version type (Java/Bedrock)

Monitoring Features

• Real-time Status: Server online status, player count, latency
• Historical Data: Online player count trend charts with accurate time axis display
• Player Activity: Recent player join/leave records within 15 minutes
• Server Details: Version information, MOTD, Favicon, etc.
• Data Management: Admin panel supports database backup, restore, and optimization functions

Troubleshooting

Log Viewing

# View system logs (if using systemd)
sudo journalctl -u etamonitor -f

# View application output
./etamonitor 2>&1 | tee etamonitor.log

Contributing

Contributions of code, bug reports, or suggestions are welcome!

You can support the project by giving it a Star⭐

License

This project is licensed under the Mozilla Public License Version 2.0. See the LICENSE file for details.

Acknowledgments

• CraftHead: Minecraft avatar API provider
• MDUI: Material Design component library
• Gin: Go web framework
• Vue.js: Frontend framework