Template System

Templates are the blueprints for server instances. Each template is a directory inside templates/ that contains everything a server needs to run: the server JAR, plugins, configs, and world data.

Directory Structure

templates/
  Proxy/              # Template for the Proxy group
    velocity.jar
    velocity.toml
    forwarding.secret
    plugins/
  Lobby/              # Template for the Lobby group
    server.jar
    plugins/
    server.properties
  BedWars/            # Template for the BedWars group
    server.jar
    plugins/
    world/
  global/             # Overlay applied to ALL backend servers
    plugins/
      shared-plugin.jar
  global_proxy/       # Overlay applied to ALL proxy servers
    plugins/
      proxy-plugin.jar

Each group config references a template by name via the template field in its group configuration:

[group]
name = "BedWars"
template = "BedWars"

Template stacking

Groups can reference multiple templates with the templates = [...] list field. Each template is applied in order, so later entries override files from earlier ones. This lets you compose a group from a base template plus one or more overlays without duplicating files:

[group]
name = "BedWars"
# First "base" is laid down, then "bedwars-overlay" overwrites any conflicts
templates = ["base", "bedwars-overlay"]

If both template and templates are set, the single-value template field is treated as the first entry in the stack.

How Templates Are Applied

When a service starts, Nimbus prepares its working directory in the following order:

1. Copy group template -- Files from templates/<TemplateName>/ are copied to services/<ServiceName>/
2. Apply global overlay -- Files from templates/global/ are copied on top (for backend servers) or templates/global_proxy/ (for proxy servers), overwriting any conflicting files
3. Patch configs -- Server configs are automatically patched (ports, forwarding, etc.)
4. Accept EULA -- For Paper, Purpur, Leaf and other servers, eula.txt is auto-accepted

Static vs Dynamic Template Handling

Symlink Optimization

Large directories that are read-only at runtime (such as libraries/) are symlinked instead of copied. This saves significant disk space and speeds up service startup, especially for modded servers where the libraries/ directory can be hundreds of megabytes.

The following directories are automatically symlinked:

• libraries/

services/ModdedSMP-1/
  libraries/ -> /absolute/path/to/templates/ModdedSMP/libraries/
  server.jar
  mods/
  ...

Config Patching

Nimbus automatically patches server configuration files to ensure correct port binding and proxy forwarding. You do not need to manually set ports or forwarding secrets.

server.properties (Paper/Purpur/Leaf/Folia)

Nimbus sets:

• server-port -- Assigned port from the port allocator
• online-mode=false -- Required when behind a Velocity proxy

If server.properties doesn't exist, Nimbus creates a minimal one.

velocity.toml (Velocity proxy)

Nimbus sets:

• bind -- Assigned proxy port (starting at 25565)
• player-info-forwarding-mode -- modern if all backends are 1.13+, otherwise legacy
• online-mode=true -- The proxy handles authentication

Paper Velocity Forwarding

For Paper servers behind a Velocity proxy, Nimbus configures modern forwarding:

• Copies forwarding.secret from the Velocity template to each backend
• Patches paper.yml (Paper 1.13-1.18) or config/paper-global.yml (Paper 1.19+) to enable Velocity support
• If neither config file exists yet, creates both formats so whichever version picks it up

BungeeCord/Legacy Forwarding

When pre-1.13 servers are in the network, Nimbus uses legacy forwarding:

• Sets bungeecord: true in spigot.yml on all backend servers
• Configures Velocity with player-info-forwarding-mode = "legacy"

Fabric Proxy Forwarding

For Fabric servers, Nimbus configures FabricProxy-Lite:

• Creates/patches config/FabricProxy-Lite.toml
• Sets hackOnlineMode and secret based on the forwarding mode
• Auto-downloads FabricProxy-Lite and Fabric API from Modrinth if not present

Forge/NeoForge Proxy Forwarding

For Forge and NeoForge servers, Nimbus configures proxy-compatible-forge:

• Creates config/proxy-compatible-forge-server.toml
• Sets forwarding mode (MODERN or LEGACY) and secret
• Auto-downloads the proxy-compatible-forge mod from Modrinth if not present

Software Resolver

Nimbus automatically downloads server software when it's not already present in the template directory. No manual JAR downloads needed.

Supported Software

Version Resolution

For modded servers, if modloader_version is left empty in the group config, Nimbus fetches the latest stable version:

• Forge -- Latest promoted version from the Forge promotions API
• NeoForge -- Latest stable version matching the Minecraft version
• Fabric -- Latest stable loader version (always uses the newest stable loader since it's backwards compatible)

Via Plugin Auto-Deployment

When your network includes servers running different Minecraft versions, Nimbus can auto-download ViaVersion and ViaBackwards to backend server templates.

Via plugins are downloaded from the Hangar repository (PaperMC's plugin repository) and placed in the template's plugins/ directory. They are only installed on backend servers, never on the proxy. If you select ViaBackwards without ViaVersion, Nimbus automatically includes ViaVersion as a required dependency.

EULA Auto-Acceptance

For Paper, Pufferfish, Purpur, Leaf, and Folia servers, Nimbus automatically accepts the Minecraft EULA by creating eula.txt with eula=true. This prevents the server from halting on first launch waiting for manual EULA acceptance.

Modpack Installation

Nimbus supports installing modpacks from multiple sources into templates:

• Modrinth slug -- e.g., cobblemon
• Modrinth URL -- e.g., https://modrinth.com/modpack/cobblemon
• CurseForge slug -- e.g., curseforge:all-the-mods-10 (requires [curseforge] api_key in nimbus.toml)
• CurseForge URL -- e.g., https://curseforge.com/minecraft/modpacks/all-the-mods-10
• Server pack ZIP -- Pre-built server files (e.g., CurseForge's "Server Pack" download)
• Local .mrpack file -- A Modrinth .mrpack file on disk

How It Works

Modrinth / CurseForge packs (.mrpack):

1. The .mrpack is downloaded (if not local) and its modrinth.index.json is parsed
2. The modloader and Minecraft version are detected from the pack's dependencies
3. Server-side mods are downloaded in parallel (up to 8 concurrent downloads)
4. File integrity is verified using SHA-1 hashes
5. The overrides/ and server-overrides/ directories from the pack are extracted to the template

Server pack ZIPs:

1. The ZIP is analyzed for installer JARs (neoforge-*-installer.jar, forge-*-installer.jar) and startup scripts (startserver.sh)
2. The modloader type, version, and Minecraft version are auto-detected
3. All server files (mods, configs, data) are extracted to the template — installer JARs and startup scripts are skipped (Nimbus manages its own startup)
4. The modloader is installed via Nimbus's standard installer pipeline

Supported Modloaders

The modpack installer automatically detects and configures the correct modloader:

Global Template Overlays

Global templates let you share plugins and configs across all servers of a given type.

Global overlays are applied after the group-specific template, so they overwrite any conflicting files. This is useful for:

• Shared plugins that every server needs
• Common configuration files
• Network-wide resource packs

templates/
  global/
    plugins/
      ChatFormat.jar          # Your own shared plugin
    server.properties         # Common server settings
  global_proxy/
    plugins/
      YourProxyPlugin.jar     # Your own shared proxy plugin