Skip to content

Nicompter/TheDashboard

BranchesTags

Repository files navigation

TheDashboard

A lightweight web dashboard for your Paper/Spigot Minecraft server. It runs an embedded HTTP server and ships a minimal single‑page UI to manage players, view live logs, run console commands, and control the server.

— English below —

🇩🇪 Übersicht (Deutsch)

Funktionen

  • Web-Dashboard unter http://<host>:<port>/ (Standardport: 4646)
  • Login per Bearer-Token (Passwort) mit Erst-Setup-Dialog
  • Online-Spieler anzeigen (inkl. OP-Badge)
  • Spieler verwalten: Kick, Ban, Unban, OP/Deop
  • Gebannte Spieler mit Grund und Ablaufdatum
  • Operatoren-Liste inkl. Deop und OP hinzufügen
  • Live-Serverlogs (Konsole) mit Auto-Scroll
  • Befehle an die Server-Konsole senden
  • Server stoppen und neu starten (Paper)
  • Whitelist umschaltbar (Switch) und verwalten: Liste einsehen, Spieler hinzufügen/entfernen
  • Live-TPS-Anzeige (1m)

Voraussetzungen

  • Java 21
  • Paper 1.21.x (getestet gegen API 1.21.8)

Installation

  1. JAR in den plugins/-Ordner deines Paper-Servers legen.
  2. Server starten.
  3. Im Browser http://<server-ip>:4646/ öffnen.
  4. Beim ersten Start ist das Standardpasswort aktiv. Setze im Overlay ein neues Passwort oder trage es in die config.yml ein.

Konfiguration (config.yml)

webserver:
  port: 4646
  password: "YOUR_SECURE_PASSWORD" # Bitte ändern!
  # Optional: Pfad zur Logdatei, falls Auto-Erkennung nicht passt
  # logFile: "/absolute/path/to/logs/latest.log"

Hinweise:

  • Das Passwort dient als Bearer-Token. Wähle ein starkes, geheimes Passwort.
  • Ändere unbedingt das Standardpasswort ("YOUR_SECURE_PASSWORD").

Sicherheit

  • Alle Endpunkte außer /, /frontend, /favicon.ico, /auth/status und /auth/set-password sind durch den Authorization: Bearer <password> Header geschützt.
  • Wenn das Dashboard von außen erreichbar ist: hinter einen Reverse Proxy packen und HTTPS aktivieren; Firewall-Regeln setzen.

Web-UI

  • Aufruf: http://<host>:<port>/ oder …/frontend
  • Enthält: Spieler-Liste, Bans, Operatoren, Konsole, Buttons für Restart/Stop, sowie Login-/Setup-Overlay.
  • Whitelist: Über einen Switch in der Server-Karte aktivier-/deaktivierbar. Wenn aktiv, erscheint eine Whitelist-Karte mit Liste; Spieler können über ein Plus-Icon hinzugefügt oder per Papierkorb entfernt werden.
  • Server-Karte zeigt zusätzlich die TPS (1 Minute Durchschnitt) an.

REST-API (Kurzreferenz)

Bei geschützten Endpunkten immer den Header Authorization: Bearer <password> mitsenden.

  • GET /auth/status → { "default": boolean } (ohne Auth)
  • POST /auth/set-password Body: { "newPassword": "..." } (nur solange Standardpasswort aktiv ist; ohne Auth)
  • GET /players → [{ name: string, op: boolean }]
  • GET /banned → [{ name, created, expires, reason, source }] (Zeitstempel in ms; expires null für permanent)
  • GET /ops → ["Name1", "Name2", …]
  • GET /logs → { lines: string[] }
  • POST /kick Body: { name: string, reason?: string }
  • POST /ban Body: { name: string, reason?: string }
  • POST /unban Body: { name: string }
  • POST /op Body: { name: string }
  • POST /deop Body: { name: string }
  • POST /command Body: { cmd: string }
  • GET /stop → Server fährt herunter
  • GET /restart → Server Neustart (falls verfügbar)
  • GET /tps → { tps1m: number|null, tps5m: number|null, tps15m: number|null }
  • GET /whitelist/status → { enabled: boolean }
  • POST /whitelist/enable Body: { enabled: boolean }
  • GET /whitelist/list → ["Spieler1", "Spieler2", …]
  • POST /whitelist/add Body: { name: string }
  • POST /whitelist/remove Body: { name: string }

Beispiele (cURL):

# TPS lesen
curl -H "Authorization: Bearer <PW>" http://localhost:4646/tps

# Whitelist aktivieren/deaktivieren
curl -H "Authorization: Bearer <PW>" -H "Content-Type: application/json" \
  -d '{"enabled":true}' \
  http://localhost:4646/whitelist/enable

# Whitelist-Liste lesen
curl -H "Authorization: Bearer <PW>" http://localhost:4646/whitelist/list

# Spieler zur Whitelist hinzufügen/entfernen
curl -H "Authorization: Bearer <PW>" -H "Content-Type: application/json" \
  -d '{"name":"Player123"}' \
  http://localhost:4646/whitelist/add

curl -H "Authorization: Bearer <PW>" -H "Content-Type: application/json" \
  -d '{"name":"Player123"}' \
  http://localhost:4646/whitelist/remove

Build aus dem Quellcode

  • Voraussetzungen: Java 21, Internetzugang für Dependencies.
  • Bauen:
./gradlew build
  • Artefakt: build/libs/TheDashboard-1.0-SNAPSHOT.jar

Fehlerbehebung

  • Port belegt: webserver.port in config.yml ändern.
  • Kein Log im Dashboard: webserver.logFile auf die korrekte latest.log zeigen lassen.
  • 401 Unauthorized: Authorization-Header prüfen und Passwort mit UI/Config setzen.
  • Netzwerk/Firewall prüfen, wenn das Frontend „offline“ meldet.

— — —

🇬🇧 Overview (English)

Features

  • Web dashboard at http://<host>:<port>/ (default port: 4646)
  • Login via bearer token (password) with first‑run setup dialog
  • View online players (with OP badge)
  • Player management: kick, ban, unban, op/deop
  • Banned players with reason and expiry
  • Operators list with deop and add-op
  • Live server logs (console) with auto‑scroll
  • Send commands to the server console
  • Stop and restart the server (Paper)
  • Whitelist toggle and management: view list, add/remove players
  • Live TPS display (1m)

Requirements

  • Java 21
  • Paper 1.21.x (built against API 1.21.8)

Installation

  1. Drop the JAR into your server’s plugins/ folder.
  2. Start the server.
  3. Open http://<server-ip>:4646/ in your browser.
  4. On first start the default password is active. Set a new password in the setup overlay or in config.yml.

Configuration (config.yml)

webserver:
  port: 4646
  password: "YOUR_SECURE_PASSWORD" # Change this!
  # Optional: path to the log file if auto‑detection doesn't match
  # logFile: "/absolute/path/to/logs/latest.log"

Notes:

  • The password acts as a bearer token. Choose a strong secret.
  • You must change the default password ("YOUR_SECURE_PASSWORD").

Security

  • All endpoints except /, /frontend, /favicon.ico, /auth/status and /auth/set-password require Authorization: Bearer <password>.
  • If exposed publicly, place behind a reverse proxy and enable HTTPS; restrict access via firewall.

Web UI

  • Access via http://<host>:<port>/ or …/frontend.
  • Includes: player list, bans, operators, console, restart/stop buttons, and login/setup overlays.
  • Whitelist: switch in the server card toggles whitelist on/off. When enabled, a whitelist card appears; players can be added via plus icon and removed via trash icon.
  • Server card shows TPS (1-minute average).

REST API (Quick Reference)

Always send Authorization: Bearer <password> for protected endpoints.

  • GET /auth/status → { "default": boolean } (no auth)
  • POST /auth/set-password Body: { "newPassword": "..." } (only while default password is active; no auth)
  • GET /players → [{ name: string, op: boolean }]
  • GET /banned → [{ name, created, expires, reason, source }] (timestamps in ms; expires null for permanent)
  • GET /ops → ["Name1", "Name2", …]
  • GET /logs → { lines: string[] }
  • POST /kick Body: { name: string, reason?: string }
  • POST /ban Body: { name: string, reason?: string }
  • POST /unban Body: { name: string }
  • POST /op Body: { name: string }
  • POST /deop Body: { name: string }
  • POST /command Body: { cmd: string }
  • GET /stop → stops the server
  • GET /restart → restarts the server (if available)
  • GET /tps → { tps1m: number|null, tps5m: number|null, tps15m: number|null }
  • GET /whitelist/status → { enabled: boolean }
  • POST /whitelist/enable Body: { enabled: boolean }
  • GET /whitelist/list → ["Player1", "Player2", …]
  • POST /whitelist/add Body: { name: string }
  • POST /whitelist/remove Body: { name: string }

Examples (cURL):

# Read TPS
curl -H "Authorization: Bearer <PW>" http://localhost:4646/tps

# Toggle whitelist
curl -H "Authorization: Bearer <PW>" -H "Content-Type: application/json" \
  -d '{"enabled":true}' \
  http://localhost:4646/whitelist/enable

# Fetch whitelist
curl -H "Authorization: Bearer <PW>" http://localhost:4646/whitelist/list

# Add/remove whitelist entries
curl -H "Authorization: Bearer <PW>" -H "Content-Type: application/json" \
  -d '{"name":"Player123"}' \
  http://localhost:4646/whitelist/add

curl -H "Authorization: Bearer <PW>" -H "Content-Type: application/json" \
  -d '{"name":"Player123"}' \
  http://localhost:4646/whitelist/remove

Build from source

  • Prereqs: Java 21, internet access for dependencies.
  • Build:
./gradlew build
  • Output: build/libs/TheDashboard-1.0-SNAPSHOT.jar

Troubleshooting

  • Port in use: change webserver.port in config.yml.
  • No logs visible: set webserver.logFile to the correct latest.log path.
  • 401 Unauthorized: check Authorization header and set the password via UI/config.
  • If the UI shows “offline”, check network/firewall.

Credits

  • NanoHTTPD (embedded HTTP server)
  • org.json (JSON utilities)

About

Best Paper plugin for self hosted Minecraft server

modrinth.com/plugin/thedashboard

Topics

plugin minecraft selfhosted

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages