Minecraft Server Management Framework

Project Introduction

MC-Server-Framework is a modular Python CLI framework for managing local Minecraft Java Edition servers. It handles the full server lifecycle — from startup and shutdown to backups, dynamic DNS updates, NAT traversal, and remote console access — packaged as a standalone Windows executable.

Core Philosophy

• Zero-Dependency Deployment: Single EXE via PyInstaller, no Python installation required for end users

• Multi-Instance Management: Manage multiple Minecraft server instances from one CLI, each with independent configuration

• Network Accessibility: Built-in DDNS and tunnel integration to solve home server connectivity challenges (CGNAT, dynamic IP)

My Responsibilities

As the sole developer of the project, I am responsible for:

System Architecture Design

• Designed modular CLI architecture with Typer framework

• Planned per-server configuration system with YAML-based settings

• Architected backup system with policy-based retention

Core Feature Implementation

• Server Lifecycle: Start, stop, restart, status monitoring for multiple instances

• Java Management: Per-server Java version switching with automatic registry

• Backup System: Policy-based backups with configurable retention (count or age), include/exclude filtering

• DNS Integration: Cloudflare (A + SRV records) and DuckDNS dynamic DNS updates

• NAT Traversal: PlayIt.gg tunnel integration for CGNAT bypass

• Remote Console: RCON client for remote server administration

• System Diagnostics: Interactive menu with health checks and first-run initialization

Core Features

1. Multi-Instance Server Management

• Each server instance lives in its own directory with a server.yml configuration

• Framework automatically scans and discovers server instances

• Support for Forge 1.17+ special launch mode

2. Java Version Management

• java_registry.yml tracks available Java installations

• Per-server Java version assignment

• Automatic path resolution and validation

3. Policy-Based Backup System

• Configurable retention: keep last N backups or backups within N days

• Include/exclude file pattern filtering

• Compressed archive output

4. Dynamic DNS Integration

• Cloudflare: A record + SRV record updates (allows players to connect without port number)

• DuckDNS: Simple A record updates

• Automatic IP detection and update on server start

5. PlayIt.gg Tunnel (CGNAT Bypass)

• Integrated tunnel management for players behind carrier-grade NAT

• Automatic tunnel creation and teardown with server lifecycle

6. RCON Remote Console

• Built-in RCON client for remote server administration

• Interactive and command-line modes

Technologies Used

Core

• Python 3.8+: Primary development language

• Typer: CLI framework with auto-generated help

• Rich: Terminal UI with formatted output, progress bars, tables

Infrastructure

• PyYAML: Configuration management

• Requests: HTTP client for Cloudflare and DuckDNS APIs

• psutil: Process monitoring and management

Build & Distribution

• PyInstaller: Standalone EXE packaging (~30-50 MB)

• PowerShell: Build scripts (build.ps1)

Project Status

Current Version: v0.2.0 (Phase 2)

• ✅ Phase 1: Core server management, Java management, backup system, CLI

• ✅ Phase 2: RCON, PlayIt.gg tunnel, interactive menu, system diagnostics, first-run initialization

• 🔄 Phase 3 (planned): Auto server type detection, scheduled backups, crash auto-restart, log streaming

Development Challenges & Achievements

1. CGNAT Bypass Solution

Challenge: Many home internet connections use CGNAT, making direct port forwarding impossible.

Solution: Integrated PlayIt.gg tunnel service, automatically managing tunnel lifecycle alongside server start/stop.

2. Zero-Dependency Distribution

Challenge: End users shouldn't need to install Python or manage dependencies.

Solution: PyInstaller packaging produces a single EXE with all dependencies bundled, distributed as a ZIP archive.

3. SRV Record Automation

Challenge: Players dislike typing port numbers for non-standard Minecraft ports.

Solution: Automated Cloudflare SRV record creation alongside A records, allowing players to connect with just the domain name.

Future Roadmap

Phase 3 (v0.3.0)

• Auto-detect server type (Paper, Fabric, NeoForge, etc.)

• Scheduled backups (cron-like)

• Crash auto-restart with configurable retry policy

• Log aggregation and real-time streaming

Project Highlights

Technical Innovation

• ✅ Integrated DDNS + SRV record automation for seamless multiplayer connectivity

• ✅ PlayIt.gg tunnel integration solving CGNAT accessibility

• ✅ Policy-based backup system with flexible retention rules

User Experience

• ✅ Single EXE distribution — zero installation required

• ✅ Interactive CLI with Rich-powered terminal UI

• ✅ First-run initialization wizard for quick setup

Tech Stack: Python 3.8+, Typer, Rich, PyInstaller, Cloudflare API, PlayIt.gg Distribution: Standalone Windows EXE (~30-50 MB) Current Phase: Phase 2 complete, Phase 3 planned