Installation & Einrichtung

Diese Seite führt einmal komplett durch die Installation von EternalSystem auf einem eigenen Server – von den Voraussetzungen über den Einrichtungs-Assistenten der API bis zur fertigen Cloud mit Proxy, Lobby und eingetragener Lizenz.

Überblick

Voraussetzungen

• Ein Linux-Host (Debian/Ubuntu oder vergleichbar). Die Cloud startet dort die Game-Server.
• Java 21 oder neuer, um die API zu starten (java -version). Die JDKs für die Game-Server installiert die Cloud später selbst – dafür ist kein System-Java nötig.
• MySQL oder MariaDB. Für ein Netzwerk Pflicht, weil sich alle Server dieselbe Datenbank teilen. H2 (Datei) gibt es nur zum Ausprobieren mit einem einzelnen Server.
• Eine Domain fürs Dashboard und ein Reverse-Proxy (Apache oder nginx) davor, am besten mit HTTPS.
• Offene Ports: der Minecraft-Proxy-Port (Standard 25565) nach außen, 443 für das Dashboard. Die API (7070) und die Backend-Server bleiben intern.

1. Jars aus dem Release-Repo holen

Die Binaries liegen öffentlich im Release-Repo LeqitAdam/EternalV1-releases (nur Jars, kein Token nötig). Die Assets eines Releases heißen Eternal-<ver>.jar, EternalApi-<ver>.jar und eternal-web-<ver>.zip.

sudo mkdir -p /opt/eternal
cd /opt/eternal
# EternalApi-<ver>.jar aus dem neuesten Release laden und als EternalApi.jar ablegen
VER=$(curl -s https://api.github.com/repos/LeqitAdam/EternalV1-releases/releases/latest | grep -oP '"tag_name":\s*"v\K[^"]+')
sudo curl -L -o EternalApi.jar \
  "https://github.com/LeqitAdam/EternalV1-releases/releases/download/v$VER/EternalApi-$VER.jar"

Das Dashboard-Zip (eternal-web-<ver>.zip) kommt auf den Web-Host und wird dort entpackt; das Plugin-Jar musst du nicht von Hand verteilen – das erledigt später der Auto-Updater über die Cloud-Templates.

2. Datenbank anlegen

MySQL/MariaDB-Datenbank und -Benutzer anlegen. Der Zugang darf nur aus dem internen Netz erreichbar sein, das Passwort stark.

CREATE DATABASE eternal CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'eternal'@'127.0.0.1' IDENTIFIED BY 'EIN-STARKES-PASSWORT';
GRANT ALL PRIVILEGES ON eternal.* TO 'eternal'@'127.0.0.1';
FLUSH PRIVILEGES;

Die Tabellen legt die API beim ersten Start selbst an.

3. Der Einrichtungs-Assistent

Beim ersten Start fragt die API im Terminal die wenigen Dinge ab, die sie nicht erraten kann, erzeugt die Geheimnisse und schreibt api.yml (die Datei bekommt die Rechte 600, enthält DB-Passwort und Secrets). Später lässt sich der Assistent mit java -jar EternalApi.jar setup erneut starten – die alte Datei bleibt als api.yml.bak.

cd /opt/eternal
sudo java -jar EternalApi.jar setup

Enter übernimmt jeweils den Wert in [Klammern].

1) Datenbank

Zuerst der Typ (mysql/h2, Standard mysql). Bei MySQL folgen Host (127.0.0.1), Port (3306), Datenbank (eternal), Benutzer (eternal) und Passwort. Danach testet der Assistent die Verbindung sofort:

• ✔ Verbindung klappt. – weiter.
• ✘ Verbindung fehlgeschlagen: … – entweder korrigieren (die Abfrage wiederholt sich) oder auf Trotzdem so speichern? (j/n) mit j bestätigen, wenn die DB z. B. erst später erreichbar ist.

2) REST-API

• Port der API (Standard 7070). Das Dashboard spricht nur mit ihr.
• Adresse des Dashboards für CORS, z. B. https://dashboard.example.org. * erlaubt alle Origins (nur fürs Ausprobieren).
• Läuft die API hinter Apache/nginx? Bei j vertraut sie dem Header X-Forwarded-For, damit das Login-Rate-Limit die echte Client-IP sieht statt der Proxy-IP. Standard ist j, sobald oben eine konkrete Dashboard-Adresse angegeben wurde.

3) Eternal Cloud

Auf die Frage „Auf diesem Rechner Services betreiben?" mit j antworten, wenn dieser Host die Server starten soll (der Normalfall). Dann folgen:

• Name dieses Nodes (Node-1).
• Bind-Adresse der Proxys: 0.0.0.0 = von außen erreichbar (Port 25565 muss offen sein), 127.0.0.1 = nur lokal. Die Backend-Server binden immer auf 127.0.0.1 und laufen mit online-mode=false – sie dürfen nie direkt aus dem Internet erreichbar sein.
• Adresse für Spieler (Domain/IP, nur für die Anzeige im Dashboard).
• RAM-Budget für alle Services in MB (0 = unbegrenzt). Der Assistent schlägt den Systemspeicher minus 2 GB vor.
• Linux-Benutzer für die Server (run-as-user): erscheint nur, wenn die API als root läuft. Der vorgeschlagene Benutzer minecraft muss existieren (sudo useradd -r -m minecraft). Leer = die Server laufen als root (nicht empfohlen).

Geheimnisse notieren

Zum Schluss zeigt der Assistent zwei frisch erzeugte Werte in einem Kasten:

• den Admin-Key (Dashboard-Login über den Reiter „API-Key", siehe Dashboard-Konten) – gewährt Vollzugriff und ist der Bootstrap-Zugang, solange noch kein Rang Dashboard-Rechte hat.
• das Plugin-Secret (internal.shared-secret) – nur ohne Cloud nötig, dann in plugins/Eternal/config.yml unter api.shared-secret eintragen.

Beide einmal sicher notieren. Anschließend steht api.yml neben dem Jar.

4. systemd-Unit

Damit die API dauerhaft und beim Boot läuft, die mitgelieferte Unit tools/api/eternal-api.service installieren. Sie startet als root (für JDKs/niedrige Ports) und gibt dem Node beim Stopp 90 s zum sauberen Herunterfahren aller Services.

sudo cp eternal-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now eternal-api
# Logs mitlesen:
journalctl -u eternal-api -f

[Unit]
Description=Eternal API + Cloud node
After=network-online.target mariadb.service mysql.service
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/eternal
ExecStart=/usr/bin/java -Xms256M -Xmx1G -jar /opt/eternal/EternalApi.jar
User=root
Restart=always
RestartSec=5
TimeoutStopSec=90
KillMode=mixed
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

5. Reverse-Proxy fürs Dashboard

Das entpackte Dashboard (eternal-web) ist eine statische Angular-App auf dem Web-Host. Der Reverse-Proxy liefert diese Dateien aus und reicht alles unter /api an die Eternal-API auf 127.0.0.1:7070 weiter. Wichtig: die WebSockets für die Live-Konsole, den Service-Push und die Live-Ansicht laufen alle über /api/cloud/ws/* und müssen durchgereicht werden (Upgrade-Header).

In api.yml passend dazu server.trust-forwarded-for: true und unter cors.allowed-origins die Dashboard-Domain eintragen (der Assistent macht das bereits).

Apache

Module aktivieren: sudo a2enmod proxy proxy_http proxy_wstunnel rewrite headers.

<VirtualHost *:443>
    ServerName dashboard.example.org
    DocumentRoot /var/www/eternal-web

    # Angular-SPA: echte Dateien direkt, sonst index.html (Client-Routing)
    <Directory /var/www/eternal-web>
        Options -Indexes
        AllowOverride None
        Require all granted
        FallbackResource /index.html
    </Directory>

    ProxyPreserveHost On
    # REST-API unter /api  ->  Eternal-API auf 127.0.0.1:7070
    ProxyPass        /api/ http://127.0.0.1:7070/
    ProxyPassReverse /api/ http://127.0.0.1:7070/

    # WebSockets (Live-Konsole & Service-Push) durchreichen
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteRule ^/api/cloud/ws/(.*)$ ws://127.0.0.1:7070/cloud/ws/$1 [P,L]
</VirtualHost>

nginx

# Upgrade-Header fuer WebSockets
map $http_upgrade $connection_upgrade { default upgrade; '' close; }

server {
    listen 443 ssl;
    server_name dashboard.example.org;
    root /var/www/eternal-web;

    # Angular-SPA
    location / { try_files $uri $uri/ /index.html; }

    # REST-API + WebSockets unter /api  ->  127.0.0.1:7070
    location /api/ {
        proxy_pass http://127.0.0.1:7070/;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # greift fuer /api/cloud/ws/* (Konsole, Service-Push, Live-Ansicht)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 3600s;
    }
}

Der abschließende Slash in ProxyPass /api/ http://127.0.0.1:7070/ bzw. proxy_pass http://127.0.0.1:7070/; entfernt das /api-Präfix, sodass /api/cloud/ws/services bei der API als /cloud/ws/services ankommt.

Das Dashboard aktualisiert sich nicht über die API – dafür läuft auf dem Web-Host ein eigener Updater. Details unter Auto-Updates.

6. Erstes Dashboard-Login

Dashboard im Browser öffnen (https://dashboard.example.org), beim Login den Reiter API-Key wählen und den im Assistenten notierten Admin-Key eintragen. Damit ist man drin, auch wenn noch kein Rang Dashboard-Rechte hat.

Danach echte Konten und Rechte einrichten: In-Game-Code-Login, Passwort setzen und die eternal.web.*-Rechte über den Rollen-Editor vergeben. Wie das genau geht, steht unter Dashboard-Konten und Rechte.

7. Cloud einrichten

Jetzt die Eternal Cloud bestücken – alles im Dashboard unter Cloud. Ausführlich auf der Seite Eternal Cloud; in Kürze:

1. Cloud → Java: ein JDK installieren (Adoptium/Temurin, z. B. 21 oder 25). Vorhandene JDKs unter /usr/lib/jvm werden erkannt.
2. Cloud → Versionen: Paper (oder Purpur/Folia/Spigot/Vanilla) und BungeeCord (oder Velocity) installieren. Paper wird einmal vorgepatcht, ein Start ist danach nur noch Kopieren.
3. Cloud → Services → Erste Einrichtung: legt die Tasks Proxy und Lobby, die Gruppen Global-Proxy/Global-Server und leere Templates an und startet beide sofort.
4. Plugin verteilen: Das Eternal-Jar (cloud/Eternal.jar) wird in jeden Service kopiert; der Auto-Updater hält es aktuell (der Cloud-Ordner steht automatisch in plugin-dirs). Bei statischen Servern oder fremden CloudNet-Templates die Plugin-Ordner in updates.plugin-dirs eintragen.

8. Lizenz eintragen

Die kostenlose Base (core, punishments, reports, lobby) läuft sofort. Für alle anderen Module den Lizenz-Schlüssel unter Dashboard → Lizenz eintragen – er gilt dann netzwerkweit. Wie Lizenzierung funktioniert, steht unter Lizenzierung.

Weiter

• Eternal Cloud – Tasks, Gruppen, Templates, Versionen, Signs & NPCs.
• Auto-Updates – Jars und Dashboard aktuell halten.
• Rechte und Dashboard-Konten – wer was im Dashboard darf.
• Lizenzierung – kostenlose Module, Schlüssel, Offline-Toleranz.