Eternal Cloud

Eternal Cloud is a standalone node that replaces CloudNet. It is built into the API jar (EternalApi-<ver>.jar) and enabled in api.yml (see Installation). It starts proxy and game servers from templates and manages server versions and JDKs. Everything else – tasks, groups, templates, versions, Java, plugins – is done in the dashboard under Cloud.

Environments and software

Sources include: PaperMC Fill (Paper, Folia, Velocity, Waterfall), Purpur API, Mojang (Vanilla), SpigotMC Jenkins (BungeeCord), mcjars.app (Spigot, Pufferfish, Leaf, Fabric, Quilt, NeoForge, Forge, Sponge, Limbo), GitHub Releases (PowerNukkitX, WaterdogPE).

Tasks, groups, templates

Static vs. dynamic

• Dynamic service: folder cloud/services/<Name>/, built from the templates on every start and deleted after stopping.
• Static service: folder cloud/static/<Task>/<Name>/, kept (important for worlds!). Templates only on the first start, unless an entry is alwaysCopy. In the dashboard under Services → „Statische Services“ ("Static services") with a file browser.

Setup mode (dynamic tasks)

Dynamic servers (lobby, minigames …) start fresh from the template every time. To build them there is setup mode under Cloud → Tasks → task:

1. Start setup: an extra server <task>-Setup-1 starts from the task's templates. It keeps its folder, runs in maintenance (only with eternal.cloud.maintenance) and is no fallback. The normal services keep running.
2. Build: join with /server <task>-Setup-1, build, configure plugins, e.g. set the lobby spawn.
3. Finish setup: the server saves, stops, and its folder (worlds, plugin settings) is copied into the template. Logs, the server jar, crash reports and the Eternal database stay out. Optionally the running services restart afterwards.
4. Discard stops the setup server and deletes it; nothing is copied.

The target is the template named like the task, otherwise the task's last one; with several templates it can be chosen first. Proxies, static tasks and gamemodes (they have their own setup) have no setup mode.

Versions & Java

• Cloud → Java: install JDKs (Adoptium/Temurin). On start, the node automatically picks a suitable Java according to the version boundaries: 1.8–1.16 → 17 (the Eternal plugin needs Java 17; Paper's own Java check is skipped), 1.17 → 16+, 1.18–1.20.4 → 17+, 1.20.5–1.21 → 21+, 26.x → 25+ (or the task setting).
• Cloud → Versionen ("Versions"): install server software. Paper jars are pre-patched once (cache/, versions/, libraries/); after that, starting a service is just copying.

Node: RAM budget and restart

At the top of the cloud you see the RAM the running services use next to the node's budget. With eternal.web.cloud.manage you change both in the dashboard:

• RAM budget: click the RAM chip. The budget covers all services together, 0 = unlimited. It applies at once: new starts are checked against it, running services keep running. It is saved in api.yml (cloud.max-memory-mb), so it survives a restart too.
• Restart node ("Node neu starten"): restarts API and cloud. Every service of this node is stopped and players are disconnected, then the services come back with their minimum count. This only works when the API runs under a service manager, i.e. systemd with Restart=always (as in tools/api/eternal-api.service) or Docker with a restart policy. If the dashboard detects none, it warns first. Under another manager set ETERNAL_SUPERVISED=1 to drop the warning.

Smart scaling

In the task editor:

• preparedServices builds service folders in advance (status PREPARED, no JVM) – starting is then just the JVM start.
• percentOfPlayersForNewService starts another service at this average load (spacing via startDelaySeconds).
• autoStopEmptySeconds stops empty extras, never below minServiceCount.
• replaceIngame: services in status INGAME do not count toward the minimum; a replacement is started.

Ingame status: /service ingame (permission eternal.cloud.service) removes a service from the fallback pool; /service lobby releases it; /service extra <Text> sets a status text.

Deployments & inclusions

• Deployments: on stop (or via „Deploy“ in the dashboard; save-all beforehand), the service folder is copied into the specified templates. Never copied: server.jar, cache/, libraries/, versions/, logs/, session.lock, server.properties, the Eternal database; plus your own exclusions (ordner/, datei, *.log – i.e. folder, file, pattern).
• Inclusions: URLs downloaded into the service before start (map zip, plugin jar); cache keeps them under temp/inclusions/.
• Delete after stop: relative paths that are removed before the deployments.

Cluster (several nodes)

Several machines, one dashboard:

• The head is the normal node with dashboard and database. It decides which node gets which service.
• Workers only run services. They have no HTTP port and no dashboard of their own.

Setting up:

1. Head: enable it in its api.yml, then restart the API. The cluster secret is created in cluster-secret.txt.

``yaml cluster: enabled: true role: head ``

1. Worker: install Java 21+ on the new machine and drop the API jar there.
2. Copy the head's api.yml. The worker needs the same database (MySQL) and the same internal.shared-secret, because tasks and groups are stored signed with it in the database.
3. Adjust:
   • cloud.node-name
   • the addresses (host-address, backend-address, public-address)
   • cloud.api-url: the head's API as the servers reach it
   • paste the block from Cloud → Nodes → Worker hinzufügen (with head URL and secret)
4. Start it, best as a service like the head. The worker shows up under Cloud → Nodes.

How the head distributes:

• New services go to the allowed node with the most free memory budget. Which nodes are allowed is set in the task under Nodes (empty = all).
• Docker tasks only go to nodes with Docker.
• Static services stay on the node that has their folder.
• What the worker fetches itself: templates (changed ones only, compared by hash), cloud/Eternal.jar and missing server versions.
• What goes back to the head: deployments land in the head's templates, dumps and crash reports under Cloud → Reports.
• Everything in the dashboard: console, commands, stop, restart, kill and dumps work for every service as for a local one.
• Players: servers on workers register with the head. Proxies get every backend with its node's backend address.

When a worker drops out:

• Its services stay in the list for 2 minutes, since they most likely keep running.
• If it comes back, the head reconciles.
• If it stays away, the head writes the services off and starts replacements on other nodes.
• When a node restarts after a crash, it ends server processes left over from its last run. This applies to every node, with or without a cluster.

Cloud → Nodes shows every node with memory, services, Docker, addresses and version. There you set a worker's memory budget and remove disconnected workers.

Docker services

Instead of a JVM on the node, every service of a task runs in its own Docker container. Set it in the task editor under Ressourcen → Laufzeit: Docker-Container (resources → runtime).

• Image: empty means eclipse-temurin:<java>-jre. The Java version comes from the task setting or automatically from the server version, e.g. 21 for 1.21.
• Own image: possible, e.g. eclipse-temurin:21-jdk. Heap dumps work then too.
• Folder: the service folder is mounted at the same path. Templates, deployments, static services, console, commands and logs work as usual.
• Network: the container uses the host network, so the server listens on the port the node assigns. Proxy and API reach it like a normal process.
• Security:
  • The container runs as the service user (run-as-user), without Linux capabilities and with no-new-privileges.
  • The memory limit is RAM + 25 % (at least + 256 MB).
  • Credentials go through an env file that is deleted after the start. They never appear on the command line.
• Clean-up: stop and kill remove the container. If one is left after a node crash, the node removes it on its next start.

Disk space

A full disk breaks everything: worlds stop saving and every console fills with errors. The cloud watches it:

• Display: the header of Cloud shows the free space. Below 5 GB it turns red, with a notice and a warning in the log every 10 minutes.
• Below 1 GB no service starts, neither automatically nor by hand. Running services keep running.
• Cleanup (hourly, every 5 minutes when space is short): old logs (30 kept each), spark temp files, crash reports (10 kept each), heap dumps (*.hprof) older than a day, old files in the temp folder.
• Spark: Paper's bundled profiler records in the background all the time. The cloud switches that background recording off (plugins/spark/config.json → backgroundProfiler: false). /spark profiler still works. If the key is already in the file, it stays as it is.
• To find what else takes space (backups, worlds, database), run du -xh -d1 / | sort -h | tail on the server.

Backups

Cloud → Backups backs up automatically:

• the cloud: templates, tasks, groups, api.yml (passwords removed) and the H2 database
• every static server (worlds!)

Schedule: interval and hour, how many zips to keep per target, folder. Running Minecraft servers save first and pause autosave while they are zipped.

Per backup: download it, protect it from deletion (pin), restore it (the old state stays as <name>.before-restore) or upload your own zip.

In a cluster: static servers on workers show up with @ <node>.

• Backing up: the worker zips the folder and sends the zip to the head.
• Restoring: the worker fetches the zip from the head and restores it on its machine.

Offsite (S3)

Under Offsite (S3) every new backup also goes to an S3 bucket. If the machine fails, the backups are then somewhere else.

Verbindung testen (test connection) writes, lists and deletes a small test object. The secret key stays on the node, the dashboard only shows ********. Uploads are streamed, so a big world backup takes no memory (up to 5 GB per file).

Metrics (Prometheus, InfluxDB)

For Grafana & co. in the head's api.yml:

metrics:
  enabled: true
  token: "long-random-string"          # at least 16 characters
  influx:                              # optional
    url: "http://127.0.0.1:8086"
    org: "my-org"
    bucket: "eternal"
    token: "influx-token"
    interval-seconds: 30

• Prometheus: GET /metrics with Authorization: Bearer <token> or ?token=<token>.
• InfluxDB 2: with influx.url, the same values go to its write API every interval-seconds (line protocol).

Reports & dumps

Cloud → Reports:

• Node report: a zip with
  • node, OS, Java, memory and disk facts
  • every service, task and group (passwords, tokens and keys masked)
  • the node log and the API's threads
  • the last 1000 console lines of each running service
• Crash report: created automatically when a service dies while starting or exits with an error code (not on stop/kill). It holds the last console lines, logs/latest.log, the newest crash-reports/ and hs_err_pid*.log. It is written before the folder is deleted, so the evidence survives.
• Thread dump and heap dump: in a service's console (Cloud → open a service).
  • The thread dump shows where a hanging server is stuck. It uses the service Java's jcmd, otherwise SIGQUIT.
  • The heap dump (.hprof) is as big as the used RAM, the server pauses briefly while it is written. It needs a JDK, not just a JRE.

The newest 30 files are kept. Download and delete on the page, permission eternal.web.cloud.manage (dashboard only, not in game).

External plugins

Cloud → Plugins: library cloud/plugins/ (upload in the dashboard or via SFTP). The dashboard reads plugin.yml/bungee.yml/velocity-plugin.json and shows name, version and the templates the plugin is in. „Installieren“ ("Install") copies the jar into the selected templates and removes older versions there. The Katalog ("Catalog") searches Modrinth; without a search term it shows recommendations in four groups:

Modrinth plugins: choose a version → Herunterladen ("Download"; one click, lands in the library) → install into templates. In the version list, the version already in the library is marked In Bibliothek ("in library"), one installed in templates Installiert ("installed", with the templates).

Auto-update

The Auto-Update bar in the library keeps Modrinth plugins up to date:

• Every library jar is recognised at Modrinth by its checksum, including uploaded or URL-loaded Modrinth builds. Jars Modrinth doesn't know (PlotSquared, Citizens, own builds) show „ohne Auto-Update“ ("no auto-update").
• It checks every 6 hours and on Jetzt prüfen ("check now"). It looks for the newest build for the same loaders and the Minecraft version of the tasks whose templates have the plugin (proxy plugins: any version). A build is never less stable than the installed one (release stays release).
• für alle Plugins ("for all plugins") turns auto-update on for every plugin without its own setting. The arrow icon in a row switches it for that plugin only.
• Without auto-update the row shows Update verfügbar ("update available") with the Aktualisieren ("update") button.
• An update downloads the jar from Modrinth, checks its SHA-512 and replaces it in the library and in every template that had the plugin. Running servers keep the old jar until their next restart; until then the row says „Update installiert · wirkt nach Neustart“ ("installed, takes effect after restart").
• Verlauf ("history") lists every update (who, from → to, templates, errors) and is searchable. Everything is stored in cloud/plugins/.updates.json.

Signs, NPCs, navigator

Lobbies receive the service list from the node via push – without the cloud, this stays off.

• Signs: /cloudsign set <Task> while looking at a sign (permission eternal.cloud.signs). A task's services are distributed across its signs; right-click connects. States SEARCHING, STARTING, EMPTY, ONLINE, FULL, INGAME, MAINTENANCE with their own frames; layout in Dashboard → Cloud → Schilder & NPCs ("Signs & NPCs").
• NPCs: /cloudnpc create <Task> [Entity|PLAYER[:Skin]] [OPEN_MENU|CONNECT_BEST|CONNECT_LOWEST|CONNECT_RANDOM] (permission eternal.cloud.npcs). The NPC is frozen, has a hologram (%task% %online% %services%), and a right-click opens the service menu or connects.
  • Player NPC with a skin (default from Minecraft 1.21.9/Paper, a mannequin; on older servers a villager stands in until the update). Without anything else the NPC gets the preloaded skin of its game mode, matched by the task name: lobby, CityBuild, survival, farm world, SkyBlock, BedWars, SkyWars, SkyPvP, TTT, PvP, UHC, build, minigames, event, zombie. PLAYER:<preset> picks a preset (e.g. PLAYER:bedwars), PLAYER:<player name> any player's skin (e.g. PLAYER:Notch). The server loads the skins itself, so they show in offline mode behind the proxy too.
  • In the dashboard (Cloud → Signs & NPCs → edit NPC → Aussehen): player or mob, then the skin — matching the task, one of the presets or a player name, with a head preview.
• Navigator (lobby module): server: "task:BedWars" instead of a fixed server name connects to the best service of the task.

Everything is stored network-wide in the database, per lobby server name.

Proxy display

Netzwerk › Proxy-Anzeige (SyncProxy replacement), stored in the database; every proxy re-reads it every 5 s – with or without a cloud node:

• MOTD frames with animation and separate maintenance MOTDs.
• Tab header/footer with placeholders %online% %max% %proxy% %player% %server% %task% %ping% %version% %time%.
• Slots: fixed value, listener limit or auto slot; full → kick text, eternal.cloud.joinfull may join anyway.
• Maintenance with whitelist (names/UUIDs); eternal.cloud.maintenance gets through.

Modules and permissions per task

With the cloud two settings apply per task instead of per server – new services of a task start right away:

• Einrichtung › Module (eternal.web.modules): modules for every service of a task. A single server with its own setup (list "Einzelne Server") wins over its task; without the cloud the page stays in the dashboard under Server › Module (per server).
• Ränge & Rechte › Rechte je Task (eternal.web.perms): permissions a rank or a player has only on the services of one task (e.g. WorldEdit only on the build server).

What lives where

While the cloud runs (and the account may use it), everything that belongs to the network sits in the Cloud area: logs, live view, map, worlds, lobby map, world rules, proxy display and modules. Ranks and permissions have their own area Ränge & Rechte in the bar on top (/perms): roles & permissions, users & ranks, permissions per task, permission requests, requesting permissions and the permission catalog; old addresses (/admin/users …) lead there. The dashboard keeps only what has nothing to do with the cloud. Without the cloud there is no Cloud area – the same pages (logs, worlds, proxy display …) are in the dashboard. The addresses (/cloud/logs …) are the same either way.

Logs, farm worlds, world rules

These pages work without a cloud node too (then in the dashboard):

• Betrieb › Live-Ansicht (eternal.web.live): watch servers live in 3D, see Replays.
• Betrieb › Logs (eternal.web.logs): API, cloud node, live consoles and log files of every server. Per server the newest 30 rotated logs are kept (the node deletes older ones hourly, the archive of stopped dynamic services too); the overview lists the newest 7, "load older logs" opens the full list.
• Welten › Farmwelten (eternal.web.farm), see Farm worlds.
• Welten › Lobby-Karte (eternal.web.lobbymap), see Lobby.
• Welten › Welt-Regeln (eternal.web.worldrules), see Settings.

Without eternal.web.cloud these pages are in the dashboard.

Player executor

Dashboard → Services → player name: connect, kick, send a message, run a command. The node passes this on to all registered proxies.

Managing in game (/cloud)

On every cloud service, /cloud opens a menu with the node status, all tasks and services. In it:

• Task: start a service, min/max count (left +1, right −1), RAM (±256 MB, shift ±1024), max players, maintenance, fallback, offline, version, delete (shift+click, then confirm).
• Service: join, restart, stop (shift = kill), console (type a command in chat), last log lines, set offline, list of players.

Everything also works as a command: /cloud tasks | services | status, /cloud start <task> [n], /cloud stop|restart|kill|join <service>, /cloud cmd <service> <command>, /cloud log <service> [lines], /cloud task <task> <min|max|memory|players|version|java|port|maintenance|fallback|static|offline> <value>, /cloud create <name> <server|proxy|velocity|limbo> <version> [RAM], /cloud delete <task> confirm, /cloud groups | templates | versions [software].

The push channel (REST & WebSocket)

Everything under /cloud/* (dashboard token) or /cloud/internal/* (plugin secret). Live console via ws://…/cloud/ws/console/<Service>?token=…, service push via /cloud/ws/services. Behind Apache/nginx, these WebSockets must be passed through – the snippets for this are in the Installation.

Security

The API runs as root (JDK installation, low ports) and starts third-party server jars. The essentials:

• Run-as-user: game servers run via runuser as cloud.run-as-user, not as root. Without a user set, the node refuses to start them (unless allow-root-services: true). Be sure to set it during setup – see Installation.
• Permissions are effectively shell access: eternal.web.cloud.manage and .console allow JVM flags, plugins and the console as the service user – give them to owners only (see Permissions).
• Network: only the proxy port should be exposed. Backends bind to 127.0.0.1 with online-mode=false and must never be reachable from the internet.
• Signed configuration: task/group rows in the DB are HMAC-signed; someone with DB write access cannot inject JVM flags or inclusions.
• One token per service instead of the network key; downloads only via HTTPS with a checksum; api.yml is written with mode 600.

Permissions

eternal.web.cloud (view), eternal.web.cloud.manage (change, start, stop, install), eternal.web.cloud.console (console + commands), eternal.web.cloud.java (JDKs), eternal.cloud.maintenance (enter during maintenance). Complete list under Permissions.

Limitations

• Workers need the same MySQL as the head. With H2 the cloud stays on one node.
• The Eternal plugin runs on Spigot/Paper 1.8.8 to 26.x and needs Java 17 or newer. The node therefore starts 1.8–1.16 with Java 17 automatically – unless the task sets a fixed older Java version, then the plugin does not load (see Versions).

Next

• Installation & Setup – set up from scratch.
• Auto-updates – keep the plugin jar in the templates up to date.