Editing Tutorials/Setting up a server (section)

== Common instructions ==
The general gist of running a ''Minecraft'' server is that you will need to install <code>java</code>, run the server, accept the EULA, and run it again. Once you have installed <code>java</code> and opened up a command line, everything is basically the same.

* Check the [[Server/Requirements|system requirements]] for CPU, RAM, and disk space.
* Install Java. Use the OS-specific instructions below for this.
* Download your server jar file from the [https://minecraft.net/download/server download page].
* Make a new folder for the jar file and move it there. This will be where all the configuration and the world files will be stored, so you don't want these to just sit in "Downloads".
* Open a command prompt or a terminal interface. (On windows: search for cmd. On macOS: open terminal in launchpad."
* Check again if Java is available. Type <code>java -version</code>.
* Type <code>cd</code> (change directory), followed by the path to the folder where you placed your server jar file. You can drag the folder into the terminal window to get the path, if you have a GUI open.
* Run the server for the first time by typing {{code|java -jar minecraft_server.jar --nogui}} (replacing the jar name (minecraft_server.jar in this case) by whatever you named the jar file to be).
* A file called {{code|eula.txt}} will be generated after you run the server for the first time. Open it in a text editor and change <code>eula=false</code> to <code>eula=true</code>. It signifies that you have read and understood the end user license agreement that you'll follow when using the software. If you don't do this, the server will shut down immediately when you try to start it.
* Now the server has been set up, and you can simply run it with {{code|java -jar minecraft_server.jar}}. If you don't want a GUI for typing commands, add a space and {{code|--nogui}} to the command. (Some people say it makes the server much much faster.) You can also use a few other switches described below.

At this point you should have a basic server running. See [[#Configuring the environment|Configuring the environment]] for more information about configuring your server. One of the things you definitely want to do is [[#Writing a script to launch the server|writing a script to launch the server]] so you don't have to remember the command line.

=== Java options ===
Java options should be added between the  {{code|java}} and the {{code|-jar}}  on the command line, or in your startup script.

; Memory limits
: The most important thing for a ''Minecraft'' server is memory to run with. <code>-Xmx</code> defines how much memory it is allowed to use. {{code|-Xmx2G}} (2 gigabytes) is more than enough for a home server with 5 players on default [[simulation distance]] (5&times;21<sup>2</sup> = 2205 chunks simulated), but do scale it up by your actual settings. Setting the value too low causes frequent GC stops. Making it too high can make GC too long on Java 8 &ndash; a version you should not be using in the first place.
: {{code|-Xms}} (the initial memory size) is the next biggest knob, but ''only'' affects startup performance. If your server also runs things other than ''Minecraft'', set it to 1/4 of the maximum size (so for our case, {{code|-Xms512M}}) for a good balance: the JVM will be allowed to return some memory to the OS when it's not needed. (The return algorithm is ''very'' conservative, so it has very minimal effect on long-term performance.) If your server is fully dedicated to ''Minecraft'', feel free to go higher: making it equal to the maximum size disables heap scaling and gives maximum startup speed.
: A "soft max heap size" ({{code|1=-XX:SoftMaxHeapSize=1G}}) is available for some versions of JRE. The JRE will try to only use that much memory, but will go over to a maximum of <code>-Xmx</code> if necessary. If you are running many things on your server, this may be useful.
; GC
: The default GC on Java 9+ used by modern ''Minecraft'' is G1GC (Java 8 also has it, but it is off by default). The flags used by the official launcher {{code|1=-XX:+UnlockExperimentalVMOptions -XX:+UseG1GC -XX:G1NewSizePercent=20 -XX:G1ReservePercent=20 -XX:MaxGCPauseMillis=50 -XX:G1HeapRegionSize=32M}} works reasonably well, though of course [https://github.com/brucethemoose/Minecraft-Performance-Flags-Benchmarks#server-g1gc better flags (brucethemoose)] exist. ([https://aikar.co/2018/07/02/tuning-the-jvm-g1gc-garbage-collector-flags-for-minecraft/ Aikar's famous flags] are good, but not optimal.)
: On Java 14+, ZGC is available. This GC is almost lag-free with millisecond-level pauses. Delete all GC-related flags and simply use {{code|-XX:+UnlockExperimentalVMOptions -XX:+UseZGC}}. Tuning flags other than {{code|-Xmx}} are [https://docs.oracle.com/en/java/javase/17/gctuning/z-garbage-collector.html#GUID-9957D441-A99A-4CF5-9522-393E6DE7D898 a lot less important] compared to in GCs (the default is quite good), although {{code|1=-XX:-ZProactive}} is worth a try if you want to trade memory for lag.
; VM
: On [https://stackoverflow.com/questions/31078803/usage-of-d32-and-d64-while-launching-java Solaris], use <code>-d64</code> to tell the JVM to use your 64-bit processor properly. Since nobody uses Solaris, this is irrelevant.
: Calculations may be made faster with GraalVM, benefiting operations such as chunk generation. A basic version is bundled in the common "HotSpot" Java 9&ndash;15, but it was later removed due to maintenance burden. Now you need to download it separately: use [https://github.com/brucethemoose/Minecraft-Performance-Flags-Benchmarks#graalvm-enterprise-edition instructions from brucethemoose].

To sum up, a reasonable flag combination can be as simple as {{code|1=-Xmx4G -Xms1G -XX:SoftMaxHeapSize=3G -XX:+UnlockExperimentalVMOptions -XX:+UseZGC}}. That is it. There are bits that you can squeeze from complicated flags, but you would get much more from [[Mods|modified server software]]. In fact, all serious discussions (e.g. Aikar and brucethemoose) of server performance assume some degree of modding.

=== Minecraft options ===
Options for the server JAR go ''after'' the {{code|-jar minecraft_server.jar}} part. Run with <code>--help</code> to see all available arguments that can be passed to the server. Below is a list of available commandline options for the server.

; <code>--bonusChest</code>
: If a [[bonus chest]] should be generated, when the world is first generated.
; <code>--demo</code>
: If the server is in demo mode. (Shows the players a demo pop-up, and players cannot break or place blocks or eat if the demo time has expired)
:Equivalent to playing ''Minecraft'' without a account, you have about 5 in-game days before your trial ends.
; <code>--eraseCache</code>
: Erases the lighting caches, etc. Same option as when optimizing single player worlds.
; <code>--forceUpgrade</code>
: Forces upgrade on all the chunks, such that the data version of all chunks matches the current server version (same as with sp worlds).
:This option significantly increases the time needed to start the server. 
; <code>--help</code>
: Shows this help.
; <code>--initSettings</code>
: Loads the settings from 'server.properties' and 'eula.txt', then quits.
; <code>--jfrprofile</code>
:Initializes the Java Flight Recorder on the server. Only available on 1.18+.
; <code>--nogui</code>
: Doesn't open the GUI when launching the server.
: You will still be able to interact with your server, but you must use the cmd or Terminal if enabled.
:* <code>nogui</code> does the same thing as this option for backward compatibility with very old versions of the server, but <code>--nogui</code> is preferable as it matches the format of other options
; <code>--safeMode</code>
: Loads level with vanilla datapack only.
; <code>--serverId <String></code>
: Gives an ID to the server. (??)
: Used only in crash reports. If not given, then the "Server Id" detail is not added to crash reports.
; <code>--singleplayer <String></code>
: Runs the server in singleplayer mode. <String> is the name of the Singleplayer player.
: The Singleplayer player data is loaded from <code>Player</code> in the <samp>level.dat</samp> file.
: Monsters spawn ignoring the 'spawn-monsters' property unless the [[difficulty]] is Peaceful. Animals spawn ignoring the 'spawn-animals' property.
: The default [[permission level]] is 0 (ignoring the 'op-permission-level' property) unless otherwise specified for a player in ops file.
: The permission level required for the {{cmd|/publish}} command is 4. Although the server is already published.
: The permission level required for the {{cmd|/seed}} command is 0, not 2.
: Blacklists are disabled. These commands are not available: {{cmd|/ban-ip}}, {{cmd|/banlist}}, {{cmd|/ban}}, {{cmd|/pardon}}, {{cmd|/pardon-ip}}.
: The local IP is '127.0.0.1' ignoring the 'server-ip' property. Use of authentication is disabled ignoring the 'online-mode' property. Prevention of proxy connections is disabled ignoring the 'prevent-proxy-connections' property.
: The default game mode (the 'gamemode' property) is still used for new players, but does not change the world's default game mode (<code>GameType</code> in the <samp>level.dat</samp> file).
; <code>--universe <String></code>
: The folder in which to look for world folders. (default: {{code|.}}, the current directory)

The following options are available from [[server.properties]] too. It might be a better idea to edit that file instead for easier management:
; <code>--world <String></code>
: The name of the world folder in which the level.dat resides. (default: {{code|world}})
: This is the same as {{code|level-name}}.
; <code>--port <Integer></code>
: Which port to listen on, overrides the server.properties value. (default: -1, read from server.properties)
:See [[Server.properties]], option "server-port", for restrictions on this value.

=== Example command line ===
* Running a world found in the folder "cold" on port 1337, with 1G of RAM allowed: <code>java -Xmx1G -jar minecraft_server.jar --port 1337 --nogui --world cold</code>.