Skip to content

README-WEBUI.md

Latest commit

 

History

History
348 lines (250 loc) · 9.38 KB

README-WEBUI.md

File metadata and controls

348 lines (250 loc) · 9.38 KB

Minecraft Server Web UI

A modern, feature-rich web interface for managing your Minecraft server with RCON support.

Features

🎮 Server Management

  • Real-time Status Monitoring - View server status, player count, and uptime
  • RCON Console - Execute commands directly from the web interface
  • Player Management - OP, De-OP, Ban, Unban, and Kick players
  • Ban List - View and manage banned players
  • Configuration Editor - Edit server.properties directly from the web UI

🎨 User Interface

  • Dark Mode - Toggle between light and dark themes (preference saved)
  • Responsive Design - Works on desktop, tablet, and mobile
  • Real-time Updates - WebSocket-based live updates
  • Quick Actions - One-click commands for common tasks

🔧 Technical Features

  • RCON Integration - Secure remote console access
  • Status Caching - Reduced server load with intelligent caching
  • Error Handling - Comprehensive error messages and logging
  • Docker-based - Easy deployment with Docker Compose

Quick Start

🚀 One-Command Setup (Windows)

PowerShell (Recommended):

# Download and run setup automatically
iwr -useb https://raw.githubusercontent.com/involvex/docker-minecraft-server/master/setup.ps1 | iex

Command Prompt:

# Download and run setup automatically
curl -o setup.bat https://raw.githubusercontent.com/involvex/docker-minecraft-server/master/setup.bat && setup.bat && manage.bat start

Manual Setup

  1. Clone or download this repository

    git clone https://github.com/involvex/docker-minecraft-server.git
cd docker-minecraft-server

  2. Configure environment variables

    cp .env.example .env

    Edit .env and set:

    • RCON_PASSWORD - Your RCON password (default: admin)
    • WEBUI_SECRET_KEY - Secret key for web UI sessions

  3. Start the services

    docker-compose up -d

  4. Access the Web UI

Configuration

Environment Variables

Required Variables

Variable Description Default
RCON_PASSWORD RCON password for server access admin
WEBUI_SECRET_KEY Secret key for web UI admin

Note: CurseForge plugin search now uses the public servermods API and does not require authentication. Spiget and GitHub searches also work without API keys.

Server Configuration Variables

Variable Description Default
RCON_PORT RCON port 25575
SERVER_NAME Display name for your server Involvex Minecraft Server
MAX_MEMORY Maximum memory allocation 4G
MAX_PLAYERS Maximum player count 20

RCON Setup

The web UI communicates with the Minecraft server via RCON. Ensure these settings match:

In .env:

RCON_PASSWORD=your_secure_password

In config/server.properties:

enable-rcon=true
rcon.port=25575
rcon.password=your_secure_password

Usage

Dashboard

  • View real-time server status
  • See online players
  • Monitor system resources
  • Quick action buttons for common commands

Console

  • Execute any Minecraft command
  • View command history
  • Real-time command output

Player Management

  • OP - Grant operator permissions
  • De-OP - Remove operator permissions
  • Ban - Ban player with optional reason
  • Kick - Kick player from server
  • Unban - Remove player from ban list

Configuration

  • Edit server.properties directly
  • Changes are saved immediately
  • Restart server to apply changes

Ban List

  • View all banned players
  • Unban players with one click
  • See ban reasons (if provided)

Troubleshooting

Web UI shows "Checking..." status

  • Ensure RCON is enabled in server.properties
  • Verify RCON password matches in both .env and server.properties
  • Check that RCON port (25575) is not blocked
  • Rebuild the web UI container: docker-compose build --no-cache minecraft-webui

Configuration shows blank

  • The server.properties file may not exist yet
  • Wait for the Minecraft server to fully start
  • Check /api/debug/files endpoint for file location details
  • Verify volume mounts in docker-compose.yml

RCON connection spam in logs

  • This has been fixed with status caching
  • Ensure you're running the latest version
  • Rebuild containers if needed

Players not showing

  • This is normal if no players are online
  • Player list updates every 30 seconds
  • Check RCON connection is working

Plugin search not working

  • Check your internet connection
  • Try a different search query
  • The API may be temporarily unavailable
  • All plugin search providers (Spiget, CurseForge, GitHub) work without requiring API keys

Management Scripts

manage.bat

Windows batch script for server management:

manage.bat start    # Start the server
manage.bat stop     # Stop the server
manage.bat restart  # Restart the server
manage.bat status   # Show server status
manage.bat logs     # View server logs
manage.bat update   # Update Docker images

manage.ps1

PowerShell alternative for Windows:

.\manage.ps1 -Command start
.\manage.ps1 -Command status
.\manage.ps1 -Command logs

setup.sh

Linux/macOS setup and management script:

./setup.sh start    # Start the server
./setup.sh status   # Check status
./setup.sh stop     # Stop the server

Architecture

┌─────────────────┐         ┌──────────────────┐
│   Web Browser   │◄───────►│  Web UI (Flask)  │
└─────────────────┘         └──────────────────┘
                                     │
                                     │ RCON
                                     ▼
                            ┌──────────────────┐
                            │ Minecraft Server │
                            └──────────────────┘

Components

  • Web UI - Flask application with Socket.IO for real-time updates
  • RCON Client - Python rcon library for server communication
  • Database - SQLite for storing logs and player data
  • Docker - Containerized deployment

Ports

  • 8080 - Web UI HTTP
  • 25565 - Minecraft server
  • 25575 - RCON (internal only)

Development

Project Structure

.
├── webui/
│   ├── app.py              # Main Flask application
│   ├── Dockerfile          # Web UI container
│   ├── requirements.txt    # Python dependencies
│   └── templates/
│       ├── base.html       # Base template with dark mode
│       └── dashboard.html  # Dashboard page
├── config/
│   └── server.properties   # Minecraft server config
├── docker-compose.yml      # Service definitions
├── .env                    # Environment variables
└── README-WEBUI.md        # This file

Building from Source

  1. Make changes to webui/app.py or templates
  2. Rebuild the container: 
    docker-compose build --no-cache minecraft-webui
  3. Restart services: 
    docker-compose up -d

Security

Best Practices

  1. Change default passwords - Update RCON_PASSWORD and WEBUI_SECRET_KEY
  2. Use strong passwords - At least 16 characters, mixed case, numbers, symbols
  3. Restrict access - Use firewall rules to limit web UI access
  4. HTTPS - Use a reverse proxy (nginx, Caddy) for HTTPS
  5. Regular updates - Keep Docker images updated

Recommended nginx Configuration

server {
    listen 443 ssl;
    server_name minecraft.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

License

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

Support

Changelog

Version 1.0.0 (2025-11-22)

  • Initial release
  • RCON integration
  • Player management (OP, Ban, Kick)
  • Dark mode support
  • Real-time status updates
  • Configuration editor
  • Ban list management

Credits