MineAdmin

A self-hosted web panel that installs, runs and monitors Minecraft servers — from picking a core to a live console — right in your browser.

English · Русский

Features · Screenshots · Quick start · Usage · API

---

MineAdmin is a web tool for automatically installing, configuring and managing Minecraft servers through the browser. Pick a server core and a game version, press one button, and MineAdmin downloads the server, finds a suitable Java, assigns a free port and gives you a live console, a file manager, backups and system monitoring. It runs from a single python main.py (or docker compose up) and is aimed at anyone hosting servers for friends, a LAN or a small community on their own machine.

Note

The web interface is currently in Russian. Current version: 1.0.6 (see VERSION).

✨ Features

⚡ One-click install	Choose a core (Vanilla, Paper, Purpur, Fabric, Forge, Spigot) and a version, then press a button. Download and install progress is shown as real percentages.
🗂 Multiple servers	Run several servers side by side; ports are assigned automatically starting from 25565.
💻 Web terminal	Live server console over WebSocket with command autocompletion (Tab) and history (↑ ↓). Graceful stop sends stop first and only then terminates the process.
📁 File manager	Browse, edit, upload (drag & drop), download, rename and delete server files; create folders. Path-traversal protected.
📈 Monitoring	Real-time CPU, RAM, disk and network usage, plus per-server and Java process stats.
⚙️ Server settings	Edit server.properties, JVM arguments, memory, max players and ports in the browser.
🌐 Network check	Shows local and public IP and checks whether a server is reachable from the LAN and the internet.
☕ Java management	Detects installed Java versions, picks the right one for the Minecraft version and can install a missing JRE (apt/dnf/yum/pacman, Homebrew, winget, or the Adoptium installer as a fallback).
💾 Backups	Zip archive of a server folder, optional upload to an SFTP server (the server is stopped and restarted around it), download and delete archives from the UI, configurable retention.
🖥 SSH terminal	Optional system shell in the browser via SSH (password or key); available when MineAdmin runs on Linux.
🗄 Database	SQLite out of the box; MySQL supported with automatic data migration and fallback to SQLite if MySQL is unreachable.
🔐 Authentication	Admin account created on first launch; JWT sessions and bcrypt-hashed passwords.
📖 Built-in docs	Help pages inside the UI, grouped by topic (getting started, servers, files, databases, Java, backups, Docker, network).
🐳 Docker	Ready-made Dockerfile (Ubuntu 24.04 with OpenJDK 17 and 21) and docker-compose.yml.

Supported server cores

Core	Description	Source
Vanilla	Official Mojang server	launchermeta.mojang.com
Paper	High-performance Spigot fork	api.papermc.io
Purpur	Paper fork with extra features	api.purpurmc.org
Fabric	Lightweight modding platform	meta.fabricmc.net
Forge	Popular modding platform	files.minecraftforge.net
Spigot	CraftBukkit fork	getbukkit.org (falls back to BuildTools)

Java requirements

Minecraft version	Java selected by MineAdmin
1.21+, 1.20.5	21+
1.18 — 1.20.4	17+
1.17	16+
1.16	11+
1.7 — 1.15	8+

Java is detected automatically. If the required version is missing, MineAdmin shows installation instructions in the UI and offers to install it for you.

📸 Screenshots

Monitoring — CPU, RAM, disk and network in real time	Terminal — live console with autocompletion
File manager — browse, edit, upload	First launch — create the admin account

🚀 Quick start

Warning

Using the prebuilt binaries from Releases is strongly discouraged — run MineAdmin from source (or with Docker) instead.

Requirements

• Python 3.10+
• Java 17+ (for MC 1.17+) or Java 21+ (for MC 1.21+) — see Java requirements

From source

# Clone the project
git clone https://github.com/DenisHumen/MineAdmin.git
cd MineAdmin

# Install dependencies
pip install -r requirements.txt

# Run
python main.py

On startup MineAdmin checks dependencies, prepares the data/ folder and prints the local IP and port of the web interface (default 8080).

Docker

# With Docker Compose
docker compose up -d

# Or with plain Docker
docker build -t mineadmin .
docker run -d -p 8080:8080 -p 25565-25575:25565-25575 -v ./data:/app/data mineadmin

Port	Purpose
8080	Web interface
25565-25575	Minecraft servers

Data lives in ./data and survives container restarts.

⚙️ Configuration

data/config.json is created automatically on first launch. Every setting is also available in the web interface (Settings: General, Database, Java, Backups, SSH / Terminal).

Key	Default	Description
web.host / web.port	0.0.0.0 / 8080	Address the web UI listens on
db_type	sqlite	sqlite or mysql
mysql.*	localhost:3306, user root, db mineadmin	MySQL connection (host, port, user, password, database)
secret_key	random (generated)	Key used to sign JWT sessions
default_java_memory / max_java_memory	2G / 4G	Default memory values offered in the UI
servers_dir	data/servers	Where server folders are stored
backup.path	data/backups	Local folder for backup archives
backup.sftp.*	disabled	SFTP upload target (host, port, username, password or key_path, remote_path)
backup.schedule.*	disabled, 24 h, 10	enabled, interval_hours, max_backups — when enabled, only the newest max_backups archives per server are kept
ssh.*	disabled	SSH terminal connection (host, port, username, auth_type = password/key, password, key_path)

Database

• SQLite — default, no setup needed (data/db/mineadmin.db)
• MySQL — switch in Settings → Database
• Data is migrated automatically when you switch
• If MySQL is unavailable, MineAdmin falls back to SQLite automatically

🧭 Usage

1. Open the address printed in the console (e.g. http://192.168.1.100:8080).
2. Create the administrator account on first launch.
3. Click New server → choose a core → a version → Install.
4. When installation finishes, click Start.
5. Use the terminal for commands and the file manager for configuration.

🔌 API

All endpoints live under /api/ and require a JWT (except setup and login):

• POST /api/auth/setup — create the first user
• POST /api/auth/login — log in
• GET /api/servers — list servers
• POST /api/servers — create a server
• POST /api/servers/{id}/start — start
• POST /api/servers/{id}/stop — stop
• WS /ws/terminal/{id} — terminal (WebSocket)
• GET /api/monitoring/stats — system statistics
• GET /api/servers/{id}/files — server files

More endpoints

Endpoint	Description
GET /api/auth/check, GET /api/auth/needs-setup	Token check, first-run check
GET /api/servers/core-types, GET /api/servers/versions/{core_type}	Available cores and versions
GET /api/servers/install-progress/{task_id}	Installation progress
POST /api/servers/{id}/kill, POST /api/servers/{id}/command, GET /api/servers/{id}/output	Force stop, send a console command, recent output
GET/PUT /api/servers/{id}/properties	Read / write server.properties
PUT /api/servers/{id}, DELETE /api/servers/{id}	Update / delete a server
GET /api/servers/{id}/network	LAN / internet reachability check
GET /api/servers/java, POST /api/servers/java/install	Detected Java installations, install Java
GET /api/servers/{id}/files/read, POST …/save, POST …/upload, GET …/download, DELETE …, POST …/mkdir, POST …/rename, GET …/size	File manager
GET /api/monitoring/system, /servers, /java-processes, /network	Monitoring
GET/PUT /api/config, GET /api/config/version, POST /api/config/switch-db, GET /api/config/db-status	App configuration and database
POST /api/config/export, POST /api/config/import	Export / import database contents
GET/PUT /api/config/ssh, POST /api/config/ssh/test	SSH terminal settings
POST /api/backups/{server_id}, GET /api/backups, GET /api/backups/progress/{task_id}, GET /api/backups/download/{file}, DELETE /api/backups/{file}	Backups
WS /ws/system-terminal	SSH system terminal

🛠 Build a standalone executable

The project layout is PyInstaller-compatible:

pip install pyinstaller
pyinstaller --onefile --add-data "app/static:app/static" --add-data "app/templates:app/templates" --add-data "VERSION:." main.py

On Windows use ; instead of : in --add-data. The release workflow (.github/workflows/release.yml) builds Linux, Windows and macOS binaries with additional --hidden-import flags for uvicorn, aiosqlite, aiofiles and multipart — use it as the reference build command.

🧱 Tech stack

• Backend: Python 3.10+, FastAPI, Uvicorn, SQLAlchemy, aiohttp
• Frontend: Vanilla JS (SPA), CSS3 with animations
• Auth: JWT + bcrypt
• DB: SQLite (aiosqlite) / MySQL (aiomysql)
• Terminal: WebSocket; SSH via Paramiko
• Monitoring: psutil
• Container: Docker, Ubuntu 24.04

📁 Project structure

MineAdmin/
├── main.py                  # Entry point: dependency check, banner, starts Uvicorn
├── VERSION                  # Application version
├── requirements.txt         # Python dependencies
├── Dockerfile               # Docker image (Ubuntu 24.04)
├── docker-compose.yml       # Docker Compose configuration
├── AI_GUIDE.md              # Architecture notes for AI assistants
├── image/                   # Screenshots
├── app/
│   ├── webapp.py            # FastAPI app, routers, SPA fallback
│   ├── config.py            # Configuration and paths
│   ├── database.py          # SQLite/MySQL, export/import
│   ├── models.py            # SQLAlchemy models (User, Server, AppSettings)
│   ├── server_manager.py    # Start/stop servers, console I/O
│   ├── downloader.py        # Downloads server jars from official APIs
│   ├── java_manager.py      # Java discovery, selection and installation
│   ├── network_checker.py   # Ports and IP checks
│   ├── system_monitor.py    # CPU, RAM, disk, processes
│   ├── file_manager.py      # File operations
│   ├── backup_manager.py    # Zip backups, SFTP upload, retention
│   ├── ssh_manager.py       # SSH sessions for the system terminal
│   ├── routes/
│   │   ├── auth.py          # Authentication (JWT + bcrypt)
│   │   ├── servers.py       # Server CRUD, start/stop, Java
│   │   ├── files.py         # File manager API
│   │   ├── terminal.py      # WebSocket terminals (server console, SSH)
│   │   ├── config_routes.py # Settings, database switching, SSH
│   │   ├── monitoring.py    # System monitoring
│   │   └── backup.py        # Backups API
│   ├── static/
│   │   ├── css/style.css    # Styles (dark theme, animations)
│   │   └── js/app.js        # SPA frontend
│   └── templates/
│       └── index.html       # HTML template
└── data/                    # Runtime data (created automatically)
    ├── servers/             # Server files
    ├── db/                  # SQLite database
    ├── backups/             # Backup archives
    └── logs/                # Logs

🤝 Contributing

Issues and pull requests are welcome. AI_GUIDE.md describes the architecture and how to add a new core, API endpoint, page or database model.

📄 License

MIT