Installing Modpacks

Eranio

Installing Modpacks

Complete guide to the 8-step installation process, egg switching, backup creation, file preservation, config merging, direct install, and all possible errors.

Before You Install

Installation Type Detection

The plugin looks up the pack stored for the server in the table server_installed_modpacks to determine the installation type:

The 8-Step Installation Process

Step 1: Preserve

Important files are saved to memory before any deletion:

Root files preserved:

• server.properties
• eula.txt
• ops.json
• banned-players.json
• banned-ips.json
• whitelist.json
• usercache.json

Directories preserved (recursive):

• /config/, Mod configuration files
• /plugins/, Plugin JARs and configs

Log: "[Modpack] Files preserved successfully"

Step 2: Backup

An automatic backup is created with a German-language name based on the installation type:

• Backup count is managed, oldest deleted when limit reached
• Log: "[Modpack] Backup created" with backup name and server UUID
• On failure: Log error "[Modpack] Failed to create backup", installation continues

Step 3: Delete

All server files are deleted except protected directories:

Protected (never deleted):

• worlds, World data
• plugins, Plugin directory
• logs, Server logs

Log: "[Modpack] Files deleted successfully" On failure: Log error "[Modpack] Failed to delete server files"

Step 4: Download (⬇)

1. Server is killed (stopped forcefully)
2. Egg switched to "Minecraft Modpack Installer"
3. Variables set: MODPACK_PROVIDER, MODPACK_ID, MODPACK_VERSION_ID
4. Server reinstalled, triggers the download
5. Wait for download, max 300 seconds timeout

Log: "[Modpack] Switched to installer egg" Timeout warning: "[Modpack] Download timeout" with elapsed and max_wait

Step 5: Extract

After download completes, extraction is monitored:

• File stability monitoring: Checks file sizes repeatedly
• 3 consecutive stable checks = decompression complete
• Dynamic timeout based on file stability

Log/timeout: "[Modpack] Decompression timeout" if stability never reached

Step 6: Restore

Preserved files are restored to the server:

• Root files restored to their original locations
• /config/ and /plugins/ conditionally restored:
  • If Update (keep configs): Skip /config/ and /plugins/ (they'll be merged in Step 7)
  • If Change/Fresh/Update (delete): Restore everything

Log on failure: "[Modpack] Failed to restore important files"

Step 7: Merge

Config files are intelligently merged, preserving your custom values while incorporating new structure:

Wait: Up to 45 seconds for mods/ and config/ directories to appear after extraction.

Config Merge Strategies

Log success: "[Modpack] Config file merged successfully" with file, old_size, merged_size Log warning: "[Modpack] Could not merge config file" with file and error

Plugin Config Merging

After root config merge, the plugin also merges /plugins/PluginName/ subdirectories:

• Scans each plugin's config directory
• Merges individual config files using the same format strategies
• Skips files where old or new content is empty
• Log: "[Modpack] Plugin config file merged successfully"

Step 8: Finalize

1. Minecraft version checked: taken from the install record, read from the files if the provider did not report it
2. Egg switched back to "Minecraft Modpack Runtime" with the matching Java image and start command
3. Pack saved in server_installed_modpacks with Minecraft and Java version
4. Install record closed with status done

Log: "[Modpack] Switched to runtime egg" Log: "[Modpack] Installation completed successfully" with server UUID and elapsed time

Java and Start Command

The pack decides which Java version the server needs. The plugin finds that out on its own:

1. At the start of the install it asks the provider which Minecraft version the chosen pack version is built for. Modrinth reports game_versions, CurseForge gameVersions (or the version in the file name when that list is empty).
2. For ATLauncher, FeedTheBeast, Technic and VoidsWrath the version is read from the installed files after the download: modrinth.index.json, manifest.json, libraries/net/minecraft/server or versions.
3. At the end the runtime egg gets the matching Docker image and start command.

If no version can be found, Java 21 is used.

Start command

Every modpack server starts with Aikar's G1 flags. The command reads the memory limit of the server each time it starts:

Forge and NeoForge packs from 1.17 on start through unix_args.txt, all others through server.jar. Java 8 packs use the same flags without argument files.

Install record

Every install is written to the table server_modpack_installs the moment it starts: provider, pack, version, Minecraft version, where the version came from, Java version, image and status (running, done, failed, aborted). The installer reads this record during the install and at the end. When the install is done, Minecraft and Java version are also stored with the installed pack in server_installed_modpacks.

Installation Actions Matrix

Cross-Plugin Cleanup

When a modpack is installed or changed, the plugin automatically cleans up data from other plugins:

Game Mods Cleanup

• Dynamically resolves Eranio\GameMods\Services\SafeCacheService and CacheKeyService
• Clears server_installed_mods table for the server
• Flushes Game Mods cache
• Log: "Cleaned database mods for server {uuid}"
• Warning if class not found: "GameMods classes not found. Skipping cache cleanup."

Minecraft Plugins Cleanup

• Dynamically resolves Eranio\MinecraftPlugins\Services\SafeCacheService and CacheKeyService
• Clears minecraft_installed_plugins table for the server
• Flushes Minecraft Plugins cache
• Log: "Cleaned database plugins for server {uuid}"
• Warning if class not found: "MinecraftPlugins classes not found. Skipping cache cleanup."

Table Not Found Handling

If a table doesn't exist (plugin not installed): "Table '{table}' does not exist. Skipping cleanup."

Post-Response Execution

The installation runs after the HTTP response via app()->terminating() callback. This prevents Livewire serialization errors and allows the progress widget to display immediately.

Progress Widget

During installation, a custom progress widget shows all 8 steps:

Translation Keys for Steps

Complete Error Reference

Installation Start

Backup Errors

Download Errors

Extraction Errors

Restore Errors

Merge Errors

Cross-Plugin Cleanup Errors

File Operation Errors

• moveFileOrDirectory(), tries 5 rename methods with fallbacks
• writeFileToRepository(), tries 3 signature attempts for daemon compatibility
• readFileFromDaemon(), primary method + API fallback