Server Startup: mustard.gorgarath.net

This document describes the startup configuration used for this Minecraft server, including the Java version, JVM arguments, and the reasoning behind the current settings.

The configuration is selected for a heavily modded NeoForge server running on Java 21, with an emphasis on consistent performance, reduced garbage collection pauses, and reliable long-term server operation.

The server is currently deployed using the community-maintained NeoForge Pterodactyl egg. Details of the deployed hosting environment, configured container image, and egg configuration are documented in server-environment.md.

The startup command documented below overrides the default command supplied by the NeoForge Pterodactyl egg. The JVM arguments have been customized to support the performance requirements of this server.

Document Scope

This document describes the currently deployed Java runtime configuration and the reasoning behind each JVM argument.

It does not document:

• Pterodactyl node configuration.
• Container or egg configuration.
• Server hardware.
• Minecraft or NeoForge configuration.
• Detailed historical startup configurations that are no longer in use.

Those topics are documented separately where appropriate.

Configured Startup Command

This command reflects the currently deployed startup configuration and should be considered the authoritative reference for the server's JVM startup arguments.

java -Xms20G -Xmx20G -Dterminal.jline=false -Dterminal.ansi=true --add-modules=jdk.incubator.vector -XX:+UseZGC -XX:+ZGenerational -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:+PerfDisableSharedMem -Xlog:gc*:file=logs/gc.log:time,uptime,level,tags:filecount=5,filesize=20M @unix_args.txt --nogui

Java Version

This startup configuration is intended for the following Java runtime:

Java Runtime:
Java 21

Configured Container Image:
ghcr.io/ptero-eggs/yolks:java_21

The JVM arguments, particularly the garbage collection and module settings, are selected specifically for Java 21.

Changing Java versions may require reviewing these settings, especially:

• Garbage collector options.
• Module flags.
• Performance-related JVM arguments.

The container image should be updated together with the documented Java runtime to avoid unexpected differences between the documented and deployed environments.

JVM Memory Settings

The initial and maximum heap sizes are intentionally set to the same value to avoid heap resizing during runtime and provide more predictable memory behavior. This is generally the recommended behavior for a dedicated server.

The total system memory requirement is higher than the configured heap because Java also requires memory outside the heap for:

• Java non-heap memory.
• Native libraries.
• Mod loader overhead.
• File caching.
• Operating system usage.

The configured Pterodactyl memory allocation and underlying host resources must allow enough additional memory beyond the Java heap allocation. Reducing available host memory without adjusting -Xms and -Xmx may cause startup failures or operating system memory pressure.

-Xms20G

Sets the initial Java heap size to 20 GB.

The JVM starts with a 20 GB initial heap allocation rather than beginning with a smaller heap and expanding over time.

Reason:

This avoids the overhead of repeatedly expanding the heap during operation and provides more consistent memory availability.

-Xmx20G

Sets the maximum Java heap size to 20 GB.

The JVM will not allocate more than 20 GB for the Java heap.

Reason:

The server has sufficient available memory for a fixed heap allocation, and maintaining the same minimum and maximum heap size provides predictable performance for a heavily modded server.

Terminal Settings

-Dterminal.jline=false

Disables JLine terminal handling.

Reason:

Useful for servers managed through environments such as Pterodactyl, containers, remote consoles, or other environments where advanced terminal handling may cause issues.

-Dterminal.ansi=true

Enables ANSI color support in console output.

Reason:

Allows Minecraft logging output to retain color formatting where supported.

Java Module Configuration

--add-modules=jdk.incubator.vector

Enables Java's Vector API module.

Reason:

Some Minecraft-related optimizations and libraries may use vectorized CPU instructions when available.

This module must be explicitly enabled because it is an incubator feature in Java 21.

Garbage Collection Settings

-XX:+UseZGC

Uses the Z Garbage Collector (ZGC).

Reason:

ZGC is designed for large heaps while keeping garbage collection pause times very low.

This is beneficial for this server because long garbage collection pauses can cause:

• Server tick delays.
• Player lag spikes.
• Timeout issues.

-XX:+ZGenerational

Enables generational ZGC.

Reason:

Generational ZGC separates short-lived and long-lived objects, allowing garbage collection to operate more efficiently.

This is useful for Minecraft servers because the game constantly creates and removes temporary objects during:

• Entity processing.
• Chunk loading.
• World generation.
• Mod operations.

-XX:+DisableExplicitGC

Prevents applications from forcing explicit garbage collection.

Reason:

Some software may request garbage collection manually, which can cause unnecessary pauses.

This allows ZGC to control collection timing without unnecessary application-triggered requests.

JVM Runtime Behavior

-XX:+AlwaysPreTouch

Reserves and initializes the configured heap memory pages during startup.

Reason:

This moves some memory allocation work from runtime into startup.

Benefits:

• More consistent runtime performance.
• Reduced chance of allocation-related pauses.

Trade-off:

• Longer server startup time.
• Memory is committed immediately.

-XX:+PerfDisableSharedMem

Disables Java performance monitoring shared memory files.

Reason:

Avoids creating unnecessary performance data files.

This is commonly used on dedicated servers where external Java monitoring tools are not being used.

Garbage Collection Logging

-Xlog:gc*:file=logs/gc.log:time,uptime,level,tags:filecount=5,filesize=20M

Enables garbage collection logging.

Logs are stored at:

logs/gc.log

Log rotation:

• Maximum of 5 log files.
• Maximum size of 20 MB per file.

Important:

The logs directory must exist before starting the server with GC logging enabled for the first time.

JVM logging initialization occurs before Minecraft begins loading. If the directory does not exist, the JVM cannot create the GC log file and the server will fail to start before Minecraft can create missing directories.

Reason:

Provides historical information for diagnosing:

• Memory issues.
• Garbage collection behavior.
• Unexpected lag spikes.
• Performance problems.

Minecraft Server Arguments

@unix_args.txt

Loads additional server arguments from:

unix_args.txt

The file path is relative to the Pterodactyl container working directory (/home/container). The server must be started from the directory containing this file.

Reason:

NeoForge servers commonly store additional launch arguments in this file.

Keeping these arguments separate prevents the startup command from becoming unnecessarily large and makes it easier to maintain.

--nogui

Disables the Minecraft graphical user interface.

Reason:

Dedicated servers do not require the graphical interface.

Benefits:

• Reduced resource usage.
• Better compatibility with server hosting environments.

Future Review Considerations

Review these settings if:

• The modpack size changes significantly.
• The number of players increases substantially.
• The server hardware changes.
• Java versions change.
• Performance problems appear.
• NeoForge or mod loader changes introduce new JVM requirements or recommendations.

Potential areas to revisit:

• Heap size (-Xms / -Xmx).
• Garbage collector choice.
• Vector API usage.
• Additional JVM performance options.
• Container image and Java runtime version.

Server Environment Notes

This server is hosted using Pterodactyl.

When modifying startup settings, consider:

• The configured Pterodactyl memory allocation must remain higher than the Java heap allocation to provide memory for JVM non-heap usage, native libraries, mod libraries, and operating system overhead.
• Changes should be tested during maintenance periods.
• Performance changes should be monitored using server metrics and logs.
• Any directories or files referenced directly by startup arguments must exist before starting the server.

JVM arguments are processed before Minecraft initialization. If a referenced file or directory does not exist, the server may fail to start before Minecraft has an opportunity to create missing files or directories.

Currently required files and directories include:

• logs/ — Required for garbage collection logging (-Xlog:gc*).
• unix_args.txt — Required by the NeoForge launch arguments (@unix_args.txt).

Related Documentation

The following documents provide additional information about this server's deployment and configuration.

Change History

2026-08-03

Updated the Related Documentation section to improve link relevance and align with the current server documentation structure.

2026-08-03

Reviewed and refined the startup configuration documentation.

Clarified that the configuration is selected for the current server environment rather than universally optimized, improved descriptions of JVM behavior and argument purposes, clarified Java runtime dependencies, and added related documentation references.

2026-07-26

Initial documentation created for the current Java 21 startup configuration.

The current configuration replaces a previous startup configuration based on Aikar's JVM flag recommendations with a ZGC-based tuning strategy optimized for the current server environment.

This change was made due to using Java 21 with a large heap allocation, where ZGC provides more appropriate low-pause garbage collection behavior for the server workload.

This document records the reasoning behind the active JVM configuration while documenting major configuration changes through the change history.