Hytale Server Dashboard

Web-Dashboard zur Verwaltung eines Hytale Dedicated Servers unter Linux (Debian/Ubuntu).

Screenshots

Dashboard (Hauptseite)

Verwaltung (Management-Seite)

Features

Dashboard (Hauptseite `/`)

Service-Status: ActiveState, SubState, MainPID, Uptime
Disk-Auslastung: Belegung der Server-Partition mit visueller Anzeige
Version: Aktuelle und verfuegbare Server-Version, manuelles/automatisches Update
Auto-Update-Check: Stuendliche Versionspruefung mit geplantem Update bei Spielern
Backup-Uebersicht: Liste der vorhandenen Backups mit Groesse, Datum, Label und Kommentar
Manuelle Backups: Direkte Erstellung benannter Backups mit optionalem Kommentar
Logs: Live-Tail der letzten 150 Zeilen (Auto-Polling)
Server-Steuerung: Start/Stop/Restart Buttons, Backup ausloesen

Verwaltung (Zweite Seite `/manage`)

Spieler-Liste: Online/Offline-Status, Letzter Login, aktuelle Welt, OP-Status
Server-Konsole: Befehle direkt an den Server senden (via FIFO Pipe)
Konfiguration: Server Config und World Config live editieren (JSON)
Backup-Verwaltung: Backups und Update-Backups anzeigen, loeschen und wiederherstellen (World/Full)
Seed-Anzeige: Ermittlung von World-Seeds fuer Backup- und Update-Backup-Eintraege
Mod-Verwaltung: Mods auflisten, aktivieren/deaktivieren, loeschen, hochladen (.zip)
CurseForge Integration: Mods direkt aus CurseForge suchen und installieren

Setup & Auth (`/setup`)

Auth-Status: Token/Session-Status anhand relevanter Server-Logs
Login Start: Auth-Flow direkt aus dem Dashboard anstossen
Token-Backups: Auth-Token separat sichern und gezielt wiederherstellen

Monitoring & Performance

SQLite-Datenbank: Schnelle Datenspeicherung fuer Spieler und Metriken
Background Worker: Kontinuierliche Datensammlung (TPS, CPU, RAM) mit stabiler SQLite-Lock-Behandlung
Stabile Zeitfenster: Performance-Historie und Cleanup nutzen robuste UTC-Zeitvergleiche
Prometheus Metrics: /metrics Endpoint fuer Grafana-Integration
Performance History: 24h Verlaufsdaten fuer Graphen

Allgemein

Dark-Theme UI
HTTP Basic Authentication
Responsive Design
Toast-Benachrichtigungen
API-Antwortzeiten <15ms (dank SQLite-Cache)

Voraussetzungen

Debian 12+ / Ubuntu 22.04+
Python 3.11+
Java 25 (Adoptium/Temurin empfohlen; x64/arm64 unterstützt)
Mindestens 4 GB RAM (mehr je nach Spieleranzahl/View Distance)
systemd
Hytale Dedicated Server Binary (von Hypixel)

Docker Installation

Das Dashboard kann als Docker Container betrieben werden und ueberwacht einen Hytale Server Container.

Voraussetzungen

Docker und Docker Compose installiert
Hytale Server laeuft als Docker Container (z.B. hytale-server)

Installation

# Repository klonen
git clone https://github.com/zonfacter/hytale-dashboard.git
cd hytale-dashboard

# .env Datei erstellen
cat > .env << EOF
DASH_USER=admin
DASH_PASS=dein-sicheres-passwort
ALLOW_CONTROL=true
CF_API_KEY=dein-curseforge-api-key

# Docker-spezifische Einstellungen
DOCKER_MODE=true
HYTALE_CONTAINER=hytale-server
HYTALE_SERVER_DIR=/opt/hytale-server
EOF

# Container starten
docker-compose up -d

Das Dashboard ist dann unter http://localhost:8088 erreichbar.

Umgebungsvariablen

Variable	Standard	Beschreibung
`DOCKER_MODE`	`true`	Docker-Modus aktivieren
`HYTALE_CONTAINER`	`hytale-server`	Name des Hytale Server Containers
`HYTALE_SERVER_DIR`	`/opt/hytale-server`	Server-Verzeichnis auf dem Host
`DASH_USER`	`admin`	Dashboard Benutzername
`DASH_PASS`	`change-me`	Dashboard Passwort
`ALLOW_CONTROL`	`true`	Start/Stop/Restart erlauben
`CF_API_KEY`	-	CurseForge API Key

Docker Compose Services

Service	Port	Beschreibung
`dashboard`	8088	Web-Dashboard (FastAPI)
`worker`	-	Background-Worker (Metriken sammeln)

Volumes

Volume	Beschreibung
`./data`	SQLite Datenbank (Persistenz)
`$HYTALE_SERVER_DIR`	Server-Verzeichnis fuer Config/Mods
`/var/run/docker.sock`	Docker Socket fuer Container-Steuerung

Docker vs Native Modus

Hinweis: Backup-Restore und Token-Restore sind aktuell nur im Native-Modus (systemd) verfuegbar; im Docker-Modus liefert die API eine klare Fehlermeldung.

Das Dashboard erkennt automatisch ob es in Docker laeuft und verwendet entsprechende Befehle:

Funktion	Native	Docker
Server Status	`systemctl show`	`docker inspect`
Logs	`journalctl`	`docker logs`
Start/Stop	`systemctl start/stop`	`docker start/stop`
Update (Stop/Start)	`systemctl stop/start`	`docker stop/start`
CPU/RAM	`ps`	`docker stats`

Compatibility & Release Gate

Fuer stabile Releases (weniger Hotfixes) werden diese Checks vor Merge nach master verpflichtend ausgefuehrt:

# 1) API/Symbol-Contract
bash scripts/contract_check.sh

# 2) Runtime-Preflight auf Zielsystem/Container
bash scripts/preflight_compat.sh --server-dir /opt/hytale-server

# 3) API-Smoke (mit gueltigen Dashboard-Credentials)
BASE_URL=http://<host>:<port> DASH_USER=<user> DASH_PASS=<pass> bash scripts/release_smoke.sh

Die vollstaendige Checkliste steht in RELEASE_CHECKLIST.md.

Mit Prometheus & Grafana

Fuer vollstaendiges Monitoring entkommentiere die Services in docker-compose.yml:

# Alle Services inkl. Monitoring starten
docker-compose up -d

Schnellinstallation (Native, Empfohlen)

Das Installations-Script richtet alles automatisch ein:

# Repository klonen
git clone https://github.com/zonfacter/hytale-dashboard.git /tmp/hytale-dashboard

# Installation starten
sudo /tmp/hytale-dashboard/install.sh

Das Script:

Installiert alle Abhaengigkeiten (Python, Java, etc.)
Erstellt Benutzer und Verzeichnisse
Konfiguriert Systemd Services
Richtet Firewall-Regeln ein
Fragt nach Passwort und optionalem CurseForge API Key
Zeigt am Ende alle naechsten Schritte an

Nach der Installation muss nur noch der Hytale Server heruntergeladen werden (OAuth-Authentifizierung erforderlich).

Manuelle Installation

Falls du die Installation manuell durchfuehren moechtest:

Hytale Server Installation

Java 25 installieren (Adoptium empfohlen)

Hytale benötigt Java 25. Installation und Verifizierung:

java --version

Erwartete Ausgabe (Beispiel):

openjdk 25.0.1 LTS
OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.1+8 (build 25.0.1+8-LTS, mixed mode, sharing)

1. System-User anlegen

sudo useradd -r -m -d /opt/hytale-server -s /bin/bash hytale

2. Server-Dateien herunterladen

Es gibt zwei Optionen: Downloader CLI (empfohlen) oder manuelles Kopieren aus dem Launcher.

Den Hytale Downloader von der offiziellen Quelle beziehen und unter /opt/hytale-server/.downloader/ ablegen:

sudo mkdir -p /opt/hytale-server/.downloader
sudo chown -R hytale:hytale /opt/hytale-server

# Als hytale-User einloggen
sudo -u hytale bash
cd /opt/hytale-server

# Downloader ausfuehren (erfordert einmalige OAuth-Authentifizierung)
.downloader/hytale-downloader-linux-amd64 \
  -download-path .downloader/game.zip \
  -credentials-path .downloader/.hytale-downloader-credentials.json

Beim ersten Start oeffnet sich ein OAuth-Flow im Browser. Nach der Authentifizierung werden die Credentials gespeichert.

Nützliche CLI-Optionen:

-print-version (Version ohne Download)
-version (Downloader-Version)
-check-update (Downloader-Updates prüfen)
-patchline pre-release (Pre-Release Kanal)
-download-path game.zip (Ziel-Datei)
-skip-update-check (Update-Check überspringen)

Manuell aus dem Launcher kopieren (schnell zum Testen)

Pfad der Launcher-Installation:

Windows: %appdata%\Hytale\install\release\package\game\latest
Linux: $XDG_DATA_HOME/Hytale/install/release/package/game/latest
macOS: ~/Application Support/Hytale/install/release/package/game/latest

Kopiere Server/ und Assets.zip in dein Server-Verzeichnis.

3. Server entpacken

cd /opt/hytale-server
unzip .downloader/game.zip

Die Verzeichnisstruktur sollte so aussehen:

/opt/hytale-server/
├── Server/
│   ├── HytaleServer.jar
│   ├── auth.enc                    (OAuth Credentials)
│   └── universe/                   (Weltdaten - NEU seit 2026.01!)
│       └── worlds/
│           └── default/
│               ├── config.json
│               └── chunks/
├── Assets.zip
├── config.json
├── mods/
├── backups/
├── start.sh              (Hytale's offizielles Start-Script)
└── .downloader/
    ├── hytale-downloader-linux-amd64
    ├── game.zip
    └── .hytale-downloader-credentials.json

Wichtig / Important: Seit Hytale Server 2026.01 werden Weltdaten in Server/universe/ statt universe/ gespeichert. / Since Hytale Server 2026.01, world data is stored in Server/universe/ instead of universe/.

4. Wrapper-Script installieren

Das Wrapper-Script ermoeglicht die Konsolen-Eingabe ueber eine FIFO Pipe:

sudo cp /opt/hytale-dashboard/start-hytale.sh /opt/hytale-server/start.sh
sudo chmod 755 /opt/hytale-server/start.sh
sudo chown hytale:hytale /opt/hytale-server/start.sh

5. Systemd-Service einrichten

sudo cp /opt/hytale-dashboard/hytale.service /etc/systemd/system/hytale.service
sudo systemctl daemon-reload
sudo systemctl enable hytale.service
sudo systemctl start hytale.service

6. Server-Parameter anpassen (optional)

sudo systemctl edit hytale.service

[Service]
ExecStart=
ExecStart=/opt/hytale-server/start.sh -Xms2G -Xmx4G -jar Server/HytaleServer.jar --assets Assets.zip --bind 0.0.0.0:5520 --backup --backup-frequency 60 --backup-dir backups

Wichtige Flags:

-Xms2G -Xmx4G: Java Heap (min/max)
-XX:AOTCache=HytaleServer.aot: AOT-Cache (optional, kann Startup verbessern)
--bind 0.0.0.0:5520: IP und Port
--backup: Automatische Backups aktivieren
--backup-frequency 60: Backup-Intervall in Minuten
--backup-dir backups: Backup-Verzeichnis

Hinweis: Zu wenig RAM führt oft zu erhöhter CPU-Last durch Garbage Collection. Teste verschiedene -Xmx Werte.

7. Server-Konfiguration (`config.json`)

Die Hauptkonfiguration des Servers liegt in /opt/hytale-server/config.json:

{
  "Version": 3,
  "ServerName": "Hytale Server",
  "MOTD": "",
  "Password": "",
  "MaxPlayers": 100,
  "MaxViewRadius": 32,
  "Defaults": {
    "World": "default",
    "GameMode": "Adventure"
  },
  "PlayerStorage": {
    "Type": "Hytale"
  },
  "AuthCredentialStore": {
    "Type": "Encrypted",
    "Path": "auth.enc"
  }
}

Wichtige Einstellungen:

ServerName: Name des Servers (wird Spielern angezeigt)
Password: Server-Passwort (leer = kein Passwort)
MaxPlayers: Maximale Spieleranzahl
MaxViewRadius: Sichtweite in Chunks
Defaults.GameMode: Standard-Spielmodus (Adventure, Creative, etc.)

8. Authentifizierung und Credentials (`auth.enc`)

Der Hytale-Server speichert Authentifizierungs-Credentials verschluesselt in der Datei auth.enc. Diese wird automatisch erstellt und verwaltet.

/opt/hytale-server/auth.enc       (verschluesselte Auth-Daten)

Wichtig:

Die Datei auth.enc wird beim ersten Start oder Login automatisch erstellt
Sie enthaelt die verschluesselten OAuth-Credentials fuer den Server
Bei der Erstinstallation muss einmalig eine Authentifizierung ueber den Browser erfolgen
Die Credentials werden dann verschluesselt gespeichert und automatisch erneuert
Niemals auth.enc manuell bearbeiten oder löschen (sonst ist Re-Authentifizierung noetig)
Die Datei hat restriktive Berechtigungen (600) und gehört dem hytale-User

Authentifizierung (Device Flow):

/auth login device

Folge den Anweisungen (accounts.hytale.com/device) und gib den Code ein. Hinweis: Pro Lizenz sind bis zu 100 Server erlaubt.

Das Update-Script (hytale-update.sh) bewahrt auth.enc bei Updates automatisch.

9. Firewall konfigurieren

sudo ufw allow 5520/udp comment "Hytale Server"

Wichtige Hinweise zum Server

KillSignal=SIGINT: Der Server muss mit SIGINT gestoppt werden (nicht SIGTERM), damit Spielerdaten (Inventar, Position) korrekt gespeichert werden.
FIFO Pipe: Das Wrapper-Script (start.sh) erstellt eine Named Pipe unter /opt/hytale-server/.console_pipe. Ueber diese Pipe koennen Befehle an die Server-Konsole gesendet werden.
Mods: Mods werden als Unterverzeichnisse in /opt/hytale-server/mods/ abgelegt. Deaktivierte Mods haben das Suffix .disabled.

Dashboard Installation

1. Dashboard-User anlegen

sudo useradd -r -s /usr/sbin/nologin hytale-web
sudo usermod -aG hytale hytale-web
sudo usermod -aG systemd-journal hytale-web

2. Projekt klonen

sudo mkdir -p /opt/hytale-dashboard
sudo chown hytale-web:hytale-web /opt/hytale-dashboard
cd /opt/hytale-dashboard
git clone https://github.com/zonfacter/hytale-dashboard.git .

3. Python Virtual Environment

sudo -u hytale-web bash -c '
cd /opt/hytale-dashboard
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
'

4. Dashboard-Service installieren

sudo cp /opt/hytale-dashboard/hytale-dashboard.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable hytale-dashboard.service

5. Passwort aendern

sudo systemctl edit hytale-dashboard.service

[Service]
Environment=DASH_PASS=DEIN_SICHERES_PASSWORT

6. Sudoers-Regeln einrichten

sudo visudo -f /etc/sudoers.d/hytale-dashboard

Inhalt:

# Hytale Dashboard - Service-Steuerung
hytale-web ALL=(ALL) NOPASSWD: /bin/systemctl start hytale.service
hytale-web ALL=(ALL) NOPASSWD: /bin/systemctl stop hytale.service
hytale-web ALL=(ALL) NOPASSWD: /bin/systemctl restart hytale.service

# Update-Script
hytale-web ALL=(ALL) NOPASSWD: /usr/local/sbin/hytale-update.sh

7. Update-Script installieren

sudo cp /opt/hytale-dashboard/hytale-update.sh /usr/local/sbin/hytale-update.sh
sudo chmod 755 /usr/local/sbin/hytale-update.sh

8. Berechtigungen setzen

# FIFO Pipe und Config muessen vom Dashboard beschreibbar sein
# Hinweis: Universe-Pfad ist Server/universe/ seit Hytale Server 2026.01
sudo chmod g+w /opt/hytale-server/Server/universe/worlds/default/config.json
sudo chmod g+w /opt/hytale-server/mods/

9. Dashboard starten

sudo systemctl start hytale-dashboard.service

10. Firewall

sudo ufw allow 8088/tcp comment "Hytale Dashboard"

Konfiguration

Alle Einstellungen erfolgen ueber Environment-Variablen in der systemd Unit-Datei:

Variable	Standard	Beschreibung
`PORT`	`8088`	Dashboard-Port
`BIND`	`0.0.0.0`	Bind-Adresse
`HYTALE_SERVICE`	`hytale`	Name des Server-Services
`HYTALE_DIR`	`/opt/hytale-server`	Server-Verzeichnis
`BACKUP_DIR`	`/opt/hytale-server/backups`	Backup-Verzeichnis
`DASH_USER`	`admin`	Basic Auth Benutzername
`DASH_PASS`	`change-me`	Basic Auth Passwort
`ALLOW_CONTROL`	`true`	Steuerfunktionen aktivieren
`CF_API_KEY`	(leer)	CurseForge API Key (fuer Mod-Browser)
`UPDATE_CHECK_INTERVAL`	`3600`	Sekunden zwischen automatischen Versionschecks
`UPDATE_NOTICE_MINUTES`	`15`	Minuten Vorlauf fuer geplante Updates bei Spielern
`UPDATE_POSTPONE_COMMAND`	`/postponeupdate`	Chat-Befehl zum Verschieben des Updates

Architektur

/opt/hytale-dashboard/
├── app.py                      # FastAPI Backend (alle API-Endpunkte)
├── worker.py                   # Background-Worker (Metriken sammeln)
├── requirements.txt            # Python-Abhaengigkeiten
├── hytale-dashboard.service    # systemd Unit (Dashboard)
├── hytale-dashboard-worker.service  # systemd Unit (Worker)
├── hytale.service              # systemd Unit (Server, Vorlage)
├── hytale-update.sh            # Update-Script (Version pruefen + installieren)
├── start-hytale.sh             # Server-Wrapper (FIFO Pipe fuer Konsole)
├── data/
│   └── dashboard.db            # SQLite Datenbank (Performance, Spieler)
├── templates/
│   ├── index.html              # Dashboard-Seite
│   └── manage.html             # Verwaltungs-Seite
└── static/
    ├── app.js                  # Dashboard JS (Status, Logs, Version, Updates)
    ├── manage.js               # Verwaltung JS (Spieler, Konsole, Config, Mods)
    └── style.css               # Dark-Theme Styling

Background Worker

Der Worker (worker.py) laeuft als separater systemd-Service und sammelt kontinuierlich Daten:

Performance-Metriken (alle 5 Sekunden): TPS, CPU, RAM, View Radius
Spieler-Events (alle 10 Sekunden): Join/Leave aus Logs parsen
Cleanup (stuendlich): Alte Daten loeschen (24h Performance, 7 Tage Events)

Die Daten werden in einer SQLite-Datenbank gespeichert, was blitzschnelle API-Antworten (<15ms) ermoeglicht.

Prometheus / Grafana Integration

Das Dashboard bietet einen Prometheus-kompatiblen Metrics-Endpoint fuer Monitoring und Grafana-Integration.

Verfuegbare Metriken

Metrik	Typ	Beschreibung
`hytale_tps`	Gauge	Aktuelle TPS (Ticks per Second)
`hytale_cpu_percent`	Gauge	CPU-Auslastung in %
`hytale_ram_mb`	Gauge	RAM-Verbrauch in MB
`hytale_ram_percent`	Gauge	RAM-Auslastung in %
`hytale_view_radius`	Gauge	Aktueller View Radius
`hytale_players_online`	Gauge	Anzahl Online-Spieler
`hytale_players_total`	Gauge	Anzahl bekannter Spieler
`hytale_server_up`	Gauge	Server-Status (1=online, 0=offline)
`hytale_disk_total_bytes`	Gauge	Gesamter Speicherplatz
`hytale_disk_used_bytes`	Gauge	Belegter Speicherplatz
`hytale_disk_free_bytes`	Gauge	Freier Speicherplatz
`hytale_disk_used_percent`	Gauge	Speicherauslastung in %
`hytale_backups_count`	Gauge	Anzahl Backups
`hytale_backups_size_bytes`	Gauge	Gesamtgroesse aller Backups
`hytale_backup_last_timestamp`	Gauge	Unix-Timestamp des letzten Backups
`hytale_mods_count`	Gauge	Anzahl installierter Mods
`hytale_mods_enabled`	Gauge	Anzahl aktivierter Mods

Endpoints

Pfad	Auth	Beschreibung
`/metrics`	Nein	Prometheus Scraping (ohne Auth)
`/api/metrics`	Ja	Prometheus Metrics mit Auth
`/api/performance`	Ja	Aktuelle Performance-Daten (JSON)
`/api/performance/history?hours=24`	Ja	Performance-Verlauf (JSON)

Prometheus Konfiguration

# prometheus.yml
scrape_configs:
  - job_name: 'hytale'
    scrape_interval: 5s
    static_configs:
      - targets: ['YOUR_SERVER_IP:8088']
    metrics_path: /metrics

Grafana Dashboard

Prometheus als Datasource hinzufuegen
Neues Dashboard erstellen
Beispiel-Queries:
- TPS Graph: hytale_tps
- RAM Usage: hytale_ram_mb
- CPU Usage: hytale_cpu_percent
- Player Count: hytale_players_online

Grafana mit Infinity Plugin (Ohne Prometheus)

Die einfachste Methode: Grafana direkt mit dem Dashboard verbinden - kein Prometheus noetig!

Installation (Native)

# Grafana installieren
sudo apt update
sudo apt install -y grafana

# Grafana starten
sudo systemctl enable --now grafana-server

# Infinity Plugin installieren
sudo grafana-cli plugins install yesoreyeram-infinity-datasource
sudo systemctl restart grafana-server

Grafana ist dann unter http://YOUR_SERVER_IP:3000 erreichbar (Login: admin / admin).

Data Source einrichten

Connections → Data Sources → Add data source
Suche nach Infinity
Konfiguration:

Einstellung	Wert
Name	`Hytale Dashboard`
Base URL	`http://localhost:8088`

Authentication:
- Type: Basic Authentication
- User: admin (oder dein Dashboard-User)
- Password: Dein Dashboard-Passwort
Save & Test

Dashboard erstellen

Dashboards → New → New Dashboard
Add visualization
Data Source: Hytale Dashboard

Beispiel: TPS Graph

Einstellung	Wert
Type	JSON
Parser	Backend
Source	URL
URL	`/api/performance/history?hours=6`
Method	GET

Unter Parsing options & Result fields:

Rows/Root: $ (Root-Array)
Columns:
- Selector: timestamp, Type: Timestamp, As: Time
- Selector: tps, Type: Number, As: TPS

Beispiel: Aktuelle Werte (Stat Panel)

Einstellung	Wert
Type	JSON
URL	`/api/performance`

Columns:

Selector: tps, Type: Number, As: TPS
Selector: cpu, Type: Number, As: CPU %
Selector: ram_mb, Type: Number, As: RAM MB
Selector: players_online, Type: Number, As: Players

Verfuegbare API Endpoints fuer Grafana

Endpoint	Beschreibung	Beispiel-Selektoren
`/api/performance`	Aktuelle Werte	`tps`, `cpu`, `ram_mb`, `ram_percent`, `view_radius`, `players_online`
`/api/performance/history?hours=N`	Verlauf (1-24h)	Array mit `timestamp`, `tps`, `cpu`, `ram_mb`
`/api/players`	Spielerliste	`name`, `last_seen`, `online`, `world`
`/api/status`	Server-Status	`service.active_state`, `disk.used_percent`, `backups`

Vorteile dieser Methode

Kein Prometheus noetig
Einfachere Einrichtung
Direkte JSON-Abfrage
Weniger Ressourcenverbrauch

API-Endpunkte

Dashboard

Methode	Pfad	Beschreibung
GET	`/`	Dashboard UI
GET	`/api/status`	Service-Status, Backups, Disk, Version
GET	`/api/logs`	Journal-Logs (150 Zeilen)
POST	`/api/server/{start\|stop\|restart}`	Service steuern
POST	`/api/backup/run`	Backup ausloesen
GET	`/api/version`	Version-Info
POST	`/api/version/check`	Neue Version pruefen
POST	`/api/update/run`	Update durchfuehren
POST	`/api/update/auto`	Auto-Update Toggle
GET	`/api/update/log`	Update-Log

Verwaltung

Methode	Pfad	Beschreibung
GET	`/manage`	Verwaltungs-UI
GET	`/api/players`	Spieler-Liste
POST	`/api/console/send`	Befehl an Server senden
GET	`/api/console/output`	Konsolen-Ausgabe (Journal)
GET	`/api/config/server`	Server-Config lesen
POST	`/api/config/server`	Server-Config schreiben
GET	`/api/config/world`	World-Config lesen
POST	`/api/config/world`	World-Config schreiben
GET	`/api/backups/list`	Backup-Liste
DELETE	`/api/backups/{name}`	Backup loeschen
GET	`/api/mods`	Mod-Liste
POST	`/api/mods/{name}/toggle`	Mod aktivieren/deaktivieren
DELETE	`/api/mods/{name}`	Mod loeschen
POST	`/api/mods/upload`	Mod hochladen (.zip/.jar)
GET	`/api/plugins`	Plugin Store (verfuegbare Plugins)
POST	`/api/plugins/{id}/install`	Plugin installieren

Monitoring

Methode	Pfad	Beschreibung
GET	`/metrics`	Prometheus Metrics (ohne Auth)
GET	`/api/metrics`	Prometheus Metrics (mit Auth)
GET	`/api/performance`	Aktuelle Performance (TPS, CPU, RAM)
GET	`/api/performance/history`	Performance-Verlauf (hours=1-24)

Plugin Store

Das Dashboard enthaelt einen integrierten Plugin Store mit empfohlenen Plugins:

Plugin	Beschreibung	Autor
Nitrado:WebServer	Base plugin fuer Web-APIs. Voraussetzung fuer Query und PrometheusExporter.	Nitrado
Nitrado:Query	Stellt Server-Status (Spieleranzahl, TPS, etc.) via HTTP API bereit.	Nitrado
Nitrado:PerformanceSaver	Passt Sichtweite dynamisch an Ressourcenverbrauch an.	Nitrado
ApexHosting:PrometheusExporter	Exportiert Server- und JVM-Metriken fuer Prometheus Monitoring.	ApexHosting

Installation via Dashboard

Oeffne die Verwaltungsseite (/manage)
Scrolle zum "Plugin Store" Bereich
Klicke "Installieren" beim gewuenschten Plugin
Nach der Installation: Server neu starten

Abhaengigkeiten

Nitrado:Query und ApexHosting:PrometheusExporter benoetigen Nitrado:WebServer
Installiere zuerst WebServer, dann die abhaengigen Plugins

WebServer Konfiguration

Nach Installation von Nitrado:WebServer wird ein HTTPS-Server auf Port 5523 (Spielport +3) gestartet.

Konfiguration anpassen unter mods/Nitrado_WebServer/config.json:

{
  "port": 5523,
  "tls": true
}

Query API Nutzung

Wenn Nitrado:Query installiert ist, zeigt das Dashboard automatisch Live-Daten:

Aktuelle Spieleranzahl
Maximale Spieleranzahl
Server TPS (Ticks per Second)

Die API ist erreichbar unter: https://SERVER:5523/Nitrado/Query

CurseForge Integration

Das Dashboard bietet eine direkte Integration mit CurseForge, der offiziellen Mod-Plattform fuer Hytale.

Features

Mod-Browser: Durchsuche alle verfuegbaren Hytale Mods auf CurseForge
Suche: Finde Mods nach Namen
Versionsauswahl: Zeigt alle verfuegbaren Versionen eines Mods
Ein-Klick-Installation: Installiert Mods direkt in den mods/ Ordner

API Key einrichten

Die CurseForge API erfordert einen API Key. Diesen erhaeltst du kostenlos:

Registriere dich bei CurseForge
Oeffne die Developer Console
Erstelle ein neues Projekt/eine neue App
Generiere einen API Key unter "API Keys"

Konfiguration

Fuege den API Key zur Dashboard-Konfiguration hinzu:

sudo systemctl edit hytale-dashboard.service

[Service]
Environment=CF_API_KEY=DEIN_API_KEY_HIER

Danach Service neu starten:

sudo systemctl daemon-reload
sudo systemctl restart hytale-dashboard

Nutzung

Oeffne die Verwaltungsseite (/manage)
Scrolle zum "CurseForge Mods" Bereich
Nutze die Suche oder browse durch die Mods
Klicke auf "Details" um Versionen anzuzeigen
Waehle eine Version und klicke "Installieren"
Server neu starten nach der Installation

API-Endpunkte

Methode	Pfad	Beschreibung
GET	`/api/curseforge/status`	CurseForge Verbindungsstatus
GET	`/api/curseforge/search`	Mods suchen
GET	`/api/curseforge/mod/{id}`	Mod-Details und Dateien
POST	`/api/curseforge/install/{mod_id}/{file_id}`	Mod installieren

Hinweise

Mods werden als JAR-Dateien direkt in /opt/hytale-server/mods/ installiert
Hytale laedt nur JAR-Dateien aus dem Root des mods/ Ordners
Nach jeder Mod-Installation ist ein Server-Neustart erforderlich
Einige Mods haben Abhaengigkeiten (z.B. Vault Library) - diese zuerst installieren

Server-Konsole

Die Konsole funktioniert ueber eine FIFO Named Pipe:

start.sh erstellt /opt/hytale-server/.console_pipe
tail -f haelt die Pipe offen
Java liest stdin von der Pipe
Das Dashboard schreibt Befehle in die Pipe

Sicherheit

Das Dashboard implementiert umfassende Sicherheitsmassnahmen, um das Host-System vor schaedlichen Befehlen zu schuetzen:

Blockierte Befehle:

Systemsteuerung: stop, restart, reload, shutdown, reboot, poweroff, halt
Benutzerverwaltung: op, deop, ban, unban, whitelist
Plugin-Management: plugins, plugin, execute, eval

Verbotene Zeichen und Muster:

Shell-Metazeichen: ;, &, |, `, $, (), <>, \, Anfuehrungszeichen, Newlines, Tabs
Path-Traversal: ../
System-Pfade: /etc/, /proc/, /sys/, /dev/, /root/, /tmp/, /var/, /opt/ (ausser hytale-server)
Gefaehrliche Befehle: sudo, su, chmod, chown, rm, mv, cp, dd, mkfs, mount, kill, systemctl, service

Zusaetzliche Schutzmasnahmen:

Maximale Befehlslaenge: 500 Zeichen
Null-Byte-Schutz
Defense-in-Depth mit mehrschichtiger Validierung

Diese Massnahmen verhindern Command-Injection, Path-Traversal-Angriffe und den Zugriff auf Systemressourcen ausserhalb des Hytale-Servers.

Verfuegbare Befehle (Auswahl)

Befehl	Beschreibung
`help`	Befehlsliste anzeigen
`save`	Welt speichern
`time set <value>`	Tageszeit setzen
`say <message>`	Nachricht an alle Spieler
`gamemode <mode> <player>`	Spielmodus aendern
`tp <player> <x> <y> <z>`	Spieler teleportieren
`kick <player>`	Spieler kicken
`give <player> <item> <amount>`	Items geben
`weather <clear	rain>`

Hinweis: Blockierte Befehle (stop, op, whitelist, etc.) muessen ueber die entsprechenden Dashboard-Funktionen ausgefuehrt werden, um ordnungsgemaesse Validierung und Protokollierung zu gewaehrleisten.

Update-System

Das Update-Script (hytale-update.sh) unterstuetzt zwei Modi:

Version pruefen

sudo /usr/local/sbin/hytale-update.sh check

Nutzt hytale-downloader -print-version fuer schnelle Abfrage ohne Download.

Update durchfuehren

sudo /usr/local/sbin/hytale-update.sh update

Ablauf:

Neue Version herunterladen
Server stoppen
Backup erstellen (.update_backup_*)
Alte Dateien ersetzen (preserviert: mods, Server/universe, config, logs, credentials)
Server starten

Auto-Update

Kann im Dashboard aktiviert werden. Fuehrt das Update automatisch nach dem naechsten Backup durch.

Geplante Updates (Spieler online)

Der Dashboard-Service prueft stündlich auf neue Versionen. Wenn ein Update verfuegbar ist und Spieler online sind, wird per Chat eine Ankuendigung gesendet und das Update nach 15 Minuten ausgefuehrt. Spieler koennen mit /postponeupdate das Update jeweils um weitere 15 Minuten verschieben.

Troubleshooting

# Dashboard-Logs
journalctl -u hytale-dashboard --no-pager -n 50

# Server-Logs
journalctl -u hytale --no-pager -n 100

# Dashboard manuell starten (Debug)
cd /opt/hytale-dashboard
source .venv/bin/activate
HYTALE_DIR=/opt/hytale-server DASH_USER=admin DASH_PASS=test ALLOW_CONTROL=true \
  uvicorn app:app --host 0.0.0.0 --port 8088

# FIFO Pipe testen
echo "help" > /opt/hytale-server/.console_pipe

# Port pruefen
ss -tlnp | grep 8088

# Berechtigungen pruefen
id hytale-web
ls -la /opt/hytale-server/.console_pipe

Interessante Quellen

Hytale Server Manual: https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual
Keeping your Hytale server up to date: https://hytale.game/en/keeping-your-hytale-server-up-to-date/
Hytale Modding Documentation: https://britakee-studios.gitbook.io/hytale-modding-documentation

Security

Zugriffssicherheit

Passwort sofort aendern! Der Standard change-me ist unsicher.
HTTPS empfohlen: Reverse-Proxy (nginx/caddy) mit TLS vorschalten.

Firewall: Port 8088 nur fuer vertrauenswuerdige IPs freigeben:

sudo ufw delete allow 8088/tcp
sudo ufw allow from 192.168.1.0/24 to any port 8088 proto tcp

User-Isolation: Dashboard laeuft als eigener User (hytale-web), nicht als root oder hytale.
Minimale Sudo-Rechte: Nur die benoetigten systemctl-Befehle und das Update-Script.

Konsolensicherheit

Das Dashboard implementiert mehrschichtige Sicherheitsmassnahmen zum Schutz des Host-Systems vor schaedlichen Konsolenbefehlen:

Command-Injection-Schutz:

Blockierung von Shell-Metazeichen (;, &, |, `, $, (), <>, \, Quotes)
Validierung auf Null-Bytes
Maximale Befehlslaenge (500 Zeichen)

Path-Traversal-Schutz:

Blockierung von ../ Mustern
Verbot von Zugriff auf Systempfade (/etc/, /proc/, /sys/, /dev/, /root/, /tmp/, /var/)
Nur /opt/hytale-server/ ist erlaubt

Systembefehl-Schutz:

Blockierung gefaehrlicher Systembefehle (sudo, su, chmod, chown, rm, mv, cp, dd, mkfs, mount, kill, systemctl, service, reboot, shutdown)
Blockierung von Server-Management-Befehlen die nur ueber Dashboard-Funktionen erlaubt sind (op, deop, ban, whitelist, stop, reload)

Defense-in-Depth:

Mehrschichtige Validierung (API-Ebene + FIFO-Ebene)
Befehle werden nur als Text ueber FIFO Pipe gesendet (keine Shell-Ausfuehrung)
Umfassende Test-Suite mit 85+ Sicherheitstests

Diese Massnahmen verhindern, dass ueber die Webkonsole schaedliche Befehle ausgefuehrt werden koennen, die das Host-System beschaedigen koennten.

Credits

Dieses Projekt wurde vollstaendig von Claude Opus 4.5 (Anthropic) entwickelt und programmiert.

zonfacter hat das Projekt konzipiert, die Anforderungen definiert und Claude bei der Entwicklung angeleitet.

Der gesamte Code - Backend (FastAPI/Python), Frontend (HTML/CSS/JavaScript), Systemd-Services, Update-Scripts und Dokumentation - wurde von der KI generiert.

Lizenz

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
.github		.github
docs		docs
scripts		scripts
static		static
templates		templates
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
COMPATIBILITY.md		COMPATIBILITY.md
Dockerfile		Dockerfile
README.md		README.md
RELEASE_CHECKLIST.md		RELEASE_CHECKLIST.md
app.py		app.py
docker-compose.yml		docker-compose.yml
grafana-dashboard.json		grafana-dashboard.json
hytale-backup-manual.sh		hytale-backup-manual.sh
hytale-dashboard-worker.service		hytale-dashboard-worker.service
hytale-dashboard.service		hytale-dashboard.service
hytale-restore.sh		hytale-restore.sh
hytale-token.sh		hytale-token.sh
hytale-update.sh		hytale-update.sh
hytale.service		hytale.service
install.sh		install.sh
prometheus.yml		prometheus.yml
prometheus.yml.example		prometheus.yml.example
requirements.txt		requirements.txt
restore-from-zip.sh		restore-from-zip.sh
start-hytale.sh		start-hytale.sh
test_security.py		test_security.py
worker.py		worker.py

zonfacter/hytale-dashboard

Folders and files

Latest commit

History

Repository files navigation

Hytale Server Dashboard

Screenshots

Dashboard (Hauptseite)

Verwaltung (Management-Seite)

Features

Dashboard (Hauptseite /)

Verwaltung (Zweite Seite /manage)

Setup & Auth (/setup)

Monitoring & Performance

Allgemein

Voraussetzungen

Docker Installation

Voraussetzungen

Installation

Umgebungsvariablen

Docker Compose Services

Volumes

Docker vs Native Modus

Compatibility & Release Gate

Mit Prometheus & Grafana

Schnellinstallation (Native, Empfohlen)

Manuelle Installation

Hytale Server Installation

Java 25 installieren (Adoptium empfohlen)

1. System-User anlegen

2. Server-Dateien herunterladen

Manuell aus dem Launcher kopieren (schnell zum Testen)

3. Server entpacken

4. Wrapper-Script installieren

5. Systemd-Service einrichten

6. Server-Parameter anpassen (optional)

7. Server-Konfiguration (config.json)

8. Authentifizierung und Credentials (auth.enc)

9. Firewall konfigurieren

Wichtige Hinweise zum Server

Dashboard Installation

1. Dashboard-User anlegen

2. Projekt klonen

3. Python Virtual Environment

4. Dashboard-Service installieren

5. Passwort aendern

6. Sudoers-Regeln einrichten

7. Update-Script installieren

8. Berechtigungen setzen

9. Dashboard starten

10. Firewall

Konfiguration

Architektur

Background Worker

Prometheus / Grafana Integration

Verfuegbare Metriken

Endpoints

Prometheus Konfiguration

Grafana Dashboard

Grafana mit Infinity Plugin (Ohne Prometheus)

Installation (Native)

Data Source einrichten

Dashboard erstellen

Verfuegbare API Endpoints fuer Grafana

Vorteile dieser Methode

API-Endpunkte

Dashboard

Verwaltung

Monitoring

Plugin Store

Installation via Dashboard

Abhaengigkeiten

WebServer Konfiguration

Query API Nutzung

CurseForge Integration

Features

API Key einrichten

Konfiguration

Nutzung

API-Endpunkte

Dashboard (Hauptseite `/`)

Verwaltung (Zweite Seite `/manage`)

Setup & Auth (`/setup`)

7. Server-Konfiguration (`config.json`)

8. Authentifizierung und Credentials (`auth.enc`)

Packages