first commit
This commit is contained in:
Patrick
@@ -0,0 +1,149 @@
|
||||
# MinePanel
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
MinePanel is a Paper plugin that runs an embedded web panel for Minecraft server administration.
|
||||
|
||||
The plugin is compatible with both Paper and Folia (1.21.x).
|
||||
|
||||
The core plugin provides a secure web UI (login, roles, sessions, dashboard pages, logs, users, etc.) and an extension system so extra features can be added as separate jars.
|
||||
|
||||
## What You Get
|
||||
|
||||
### Core (works without extensions)
|
||||
|
||||
- 🖥️ Embedded HTTP server for panel pages and API.
|
||||
- 🔐 First-launch bootstrap flow to create the owner account.
|
||||
- 🛡️ Secure auth with BCrypt + server-side sessions.
|
||||
- 👥 Role/permission based panel access (`OWNER`, `ADMIN`, `VIEWER`).
|
||||
- 📜 Console page with live panel log updates and command sending.
|
||||
- 📊 Overview page with:
|
||||
- TPS, memory, CPU cards
|
||||
- TPS/Memory/CPU time-series charts
|
||||
- Join/leave heatmaps (day x hour)
|
||||
- 🎮 Players page with profile details and activity info.
|
||||
- 🔌 Plugin and bans pages.
|
||||
- 🎨 Themes page.
|
||||
- 🧩 Extension management page.
|
||||
|
||||
### Extension system
|
||||
|
||||
- Core scans `plugins/MinePanel/extensions` on startup.
|
||||
- If no extension jars are installed, you get the default panel only.
|
||||
- If extension jars are present, their routes/tabs/features are loaded after restart.
|
||||
- Extensions are discovered via Java `ServiceLoader` using:
|
||||
- `META-INF/services/de.winniepat.minePanel.extensions.MinePanelExtension`
|
||||
### All Extensions and their features are listed [here](https://github.com/WinniePatGG/MinePanel/tree/main/docs/AVAILABLE-EXTENSIONS.md)
|
||||
## Runtime Configuration
|
||||
|
||||
Default config in `src/main/resources/config.yml`:
|
||||
|
||||
```yaml
|
||||
web:
|
||||
host: 127.0.0.1
|
||||
port: 8080
|
||||
sessionTtlMinutes: 120
|
||||
|
||||
security:
|
||||
bootstrapTokenLength: 32
|
||||
|
||||
integrations:
|
||||
github:
|
||||
token: ""
|
||||
releaseCacheSeconds: 300
|
||||
```
|
||||
|
||||
Use `integrations.github.token` (or environment variable `MINEPANEL_GITHUB_TOKEN`) for authenticated GitHub API requests and higher rate limits.
|
||||
|
||||
## Build
|
||||
|
||||
### Build core + extension jars
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat assemble
|
||||
```
|
||||
|
||||
### Build only core shadow jar
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat shadowJar
|
||||
```
|
||||
|
||||
## Build Outputs
|
||||
|
||||
- Core plugin jar:
|
||||
- `build/libs/MinePanel-<version>.jar`
|
||||
- Reports extension jar:
|
||||
- `build/libs/extensions/MinePanel-Extension-Reports-<version>.jar`
|
||||
- Player-management extension jar:
|
||||
- `build/libs/extensions/MinePanel-Extension-PlayerManagement-<version>.jar`
|
||||
- LuckPerms extension jar:
|
||||
- `build/libs/extensions/MinePanel-Extension-LuckPerms-<version>.jar`
|
||||
- Player Stats extension jar:
|
||||
- `build/libs/extensions/MinePanel-Extension-PlayerStats-<version>.jar`
|
||||
|
||||
## Installation
|
||||
|
||||
1. Copy core jar to your server `plugins` folder.
|
||||
2. Start server once.
|
||||
3. Check console for the bootstrap token.
|
||||
4. Open panel in browser: `http://127.0.0.1:8080` (or your configured host/port).
|
||||
5. Complete setup and create owner account.
|
||||
|
||||
## Installing Extensions
|
||||
|
||||
1. Build or download extension jars.
|
||||
2. Put them in:
|
||||
- `plugins/MinePanel/extensions`
|
||||
3. Restart the server.
|
||||
4. New extension tabs/features become available.
|
||||
|
||||
## Extension Links
|
||||
|
||||
- GitHub releases: `https://github.com/WinniePatGG/MinePanel/releases`
|
||||
- The panel reads extension assets from the latest selected channel (Release or Pre-release).
|
||||
- If the GitHub API rate limit is reached, MinePanel falls back to cached release data and shows a warning in the Extensions tab.
|
||||
|
||||
## Included Extension Artifacts in This Repo
|
||||
|
||||
This repository can build two extension jars:
|
||||
|
||||
- `MinePanel-Extension-Reports-*`
|
||||
- Adds report system features.
|
||||
- `MinePanel-Extension-PlayerManagement-*`
|
||||
- Adds moderation/mute related player-management features.
|
||||
- `MinePanel-Extension-LuckPerms-*`
|
||||
- Adds LuckPerms player details in Players tab (groups, permissions, prefix/suffix).
|
||||
- `MinePanel-Extension-PlayerStats-*`
|
||||
- Adds player kills, deaths and economy balance (if Vault-compatible economy is present).
|
||||
|
||||
## Writing Third-Party Extensions
|
||||
|
||||
Detailed step-by-step guide:
|
||||
|
||||
- `docs/EXTENSIONS.md`
|
||||
|
||||
Implement `de.winniepat.minePanel.extensions.MinePanelExtension`.
|
||||
|
||||
Typical flow:
|
||||
|
||||
1. Implement extension class (`id`, `displayName`, lifecycle hooks).
|
||||
2. Add service descriptor file:
|
||||
- `META-INF/services/de.winniepat.minePanel.extensions.MinePanelExtension`
|
||||
3. (Optional) Register panel routes via `registerWebRoutes(...)`.
|
||||
4. (Optional) Add sidebar tabs via `navigationTabs()`.
|
||||
5. (Optional) Register runtime commands via `ExtensionContext.commandRegistry()`.
|
||||
6. Package jar and drop into `plugins/MinePanel/extensions`.
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Use a reverse proxy + HTTPS in production.
|
||||
- Restrict direct access to panel port (`web.port`) with firewall/network rules.
|
||||
- Treat bootstrap tokens and owner credentials as sensitive secrets.
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user