This is a simple but fully-featured minecraft server installer for linux. It should serve as an example of how to properly(TM) deploy a personal minecraft server with the following features:

• 🚀 Server starts automatically when players connect and shuts down when idle
• ⏱️ Utilizes PaperMC and Aikar's JVM flags for maximum performance
• 🔒 Sandboxed execution with systemd, no docker
• 💾 Creates proper incremental world backups after each server stop
• 🖥️ Background console access via tmux (also remotely via ssh)
• 🔢 Account multiplexing allows a single account to have two or more player characters
• 🗺️ Awesome 3D online map using BlueMap
• 🔋 Single-command scripts to update server and plugins
• 🐙 Ready for configuration file tracking via git
• Includes vanilla enhancements by vane

To begin the automatic installation, simply run the provided bootstrap script. Afterwards you can continue configuring your server, or jump straight to the Usage section if you are happy with the defaults.

curl -sL https://oddlama.github.io/minecraft-server/bootstrap | sudo bash
# Connect to the console (Press Ctrl+b then d to detach again)
sudo minecraft-attach server
# Don't forget to foward or expose TCP ports 25565 (server), 25566 (multiplexer 1)
# and 8100 (online map). The map will be available under https://<your-ip>:8100

You may want to review the script before executing it. In summary, the script will perform the following steps:

• Check whether all required tools are installed
• Create a new minecraft user for the server (if not existing)
• Update the server jars and download all plugins
• Install, enable and start the systemd services

At this point, your proxy server is already running and the actual server will be started once you connect to it. Now is the time to review or change the server configuration. The main directory of your server is /var/lib/minecraft/deploy. All files in that directory must be accessible to the minecraft user, so before changing anything it is a good idea to open a terminal as the minecraft user by executing sudo runuser -u minecraft bash.

The following sections are dedicated to things that you might want to configure now. All other settings that were already changed by this script compared to the minecraft default are listed in Default Settings.

When you are happy with your configuration, continue to the Usage section.

Before your server is started for the first time, you can can specify a seed via level-seed= in server.properties. To find a good seed before generating your world, have a look at Cubiomes Viewer.

By default there is no protection enabled, everyone can join and play. You can enable a classic whitelist with whitelist on.

Another option that vane provides is a feature similar to a graylist. This allows anyone to connect to your server but in a no touch, only look! kind of way. To modify anything about the world, a player must either be opped, or be assigned to the user group with perm add player_name user, or any higher group. To enable the graylist, set the following option:

# server/plugins/vane-admin/config.yml
world_protection:
  enabled: true

Additionally, if you assign a player to the verified group with perm add player_name verified, they may vouch for other users by using /vouch other_player. This will lift the other user into the users group. Useful to give your friends the permission to invite other people they know. It will be stored who vouched for whom.

The text and icon in your server list now controlled by the proxy instead of your server.properties. Edit proxy/plugins/vane-velocity/config.toml to change the text to your liking. You can also set different texts based on whether the server is currently started or not.

To set a server icon, simply drop a file name server-icon.png in your server/ directory, next to where the paper.jar is.

In the following you will learn how to use the features of this deploy to access the console, update your server among other things.

Access to your server console is crucial. The services keep both the proxy and server console in the background at all times, so you can access them from any terminal on your server (also remotely via ssh!).

sudo minecraft-attach server # Open the server console
sudo minecraft-attach proxy  # Open the proxy console

Once you execute one of the commands above, you will be presented with the respective console. If that command fails, make sure the system services are running! Press Ctrl + b followed by d to leave the console. This will put it in the background again.

The awesome 3D online map comes fully preconfigured. All you need to do is open https://<your-server-address>:8100 in your favourite browser, when your server is online. Replace your-server-address with the IP or domain name you use to connect in minecraft.

If you have an external webserver, BlueMap can be configured to be always available.

A multiplexer is an additional port for your server. When someone connects via this port, they will be logged into a secondary player character. This also works while being logged in on the main server. Very useful for account sharing or to hand out spectator accounts. Just add a new serverlist entry for the multiplexer and enjoy having multiple accounts!

Two accounts is not enough? Adding additional multiplexers is simple:

1. Forward or expose a new port. (e.g. 25567)
2. Add a new config for the multiplexer in proxy/plugins/vane-velocity/config.toml:

   [auth_multiplex.2]
   port = 25567
   allowed_uuids = [] # anyone may use this multiplexer
   

3. (Repeat for each additional multiplexer you want to add)

To disable this feature altogether, just remove all auth_multiplex.* sections from the config.

To update the server jars and all plugins, we first stop all services, run the updater and then start them again. To do this, execute the following commands as root:

systemctl stop minecraft-proxy minecraft-server    # Stop services
cd /var/lib/minecraft/deploy                       # Change into deploy directory
./update.sh                                        # Run update script
systemctl start minecraft-proxy minecraft-server   # Start services again

Generally you shouldn't need to update the deploy script. The only time it might be necessary is when one the included plugins changes its download location. You will notice when that happens, as ./update.sh will fail. Other updates to this repository will most likely be minor changes.

To update, execute the following commands as root:

systemctl stop minecraft-proxy minecraft-server    # Stop services
cd /var/lib/minecraft/deploy                       # Change into deploy directory
git pull                                           # Get updates from upstream
./contrib/install.sh                               # Re-install the service files
systemctl start minecraft-proxy minecraft-server   # Start services again

Plugins are installed and updated by the update.sh scripts. To add a new plugin, find a download link that always points to the latest version and add an entry at the end of the respective script, similar to those that are already present.

For example to add worldguard, you add the following at the end of server/update.sh:

download_file "https://dev.bukkit.org/projects/worldguard/files/latest" plugins/worldguard.jar

To remove plugins, simply delete the jar file and remove the corresponding line in the script. To remove a vane module, remove it from the list in the for loop.

By default, this setup uses a very lightweight permission plugin called vane-permissions. If you want to use a different permission plugin, be sure remove vane-permissions from the plugins as shown above and follow this guide in order not to break vane with your new plugin.

Your server will automatically create an incremental backup of all three worlds and the plugin folder everytime the server is stopped. You can view all the backups that have been created until now by executing the following commands as root:

cd deploy/server
rdiff-backup -l backups/world

Now if anything happens on your server and you want to revert to an older version, you can do so by simply executing the following commands as root:

cd deploy/server
rm -rf world  # First delete what you want to restore
rdiff-backup -r 1B backups/world world # Restore state from the last backup.
# Repeat analogously for any other folders that you want to restore:
# You can restore world, world_nether, world_the_end, and plugins

The 1B just refers to the last backup, 2B would be the second last. You can also pick any of the times listed by rdiff-backup -l from before (like 2022-06-22T20:21:42+02:00) or pick a relative time like 2D (2 days ago).

If you want to reduce the size of your backups, try rdiff-backup --remove-older-than 6M to delete any backups older than six months. You can also do a lot more specific things with rdiff-backup. Visit their website for more information.

To create backups, the service calls the server/backup.sh file automatically each time the server stops. Feel free to adjust this script to your liking. To completely disable backups, replace the script's content with:

#!/bin/bash
exit 0

This project include a utility script called contrib/organize_configs.sh. If you execute it, it will sort the keys in all your configuration files alphabetically so they can be tracked by git properly. This is necessary as the server will rewrite the configuration files each time the server is started, causing the entries to shift around unpredictably.

The .gitignore files are already setup so you will not accidentally commit your whole world or some cache files. Only configuration files are considered by default. To actually commit your configs, you should fork this project and update your git remote:

# Fork on github first, then replace the remote url:
cd deploy
git remote set-url origin [email protected]:youruser/minecraft-server.git
git add .
git commit -m "Initial configuration commit"
git push

This project comes with a reasonable default configuration for paper (main server) and velocity (proxy server). This ensures that autostarting and account multiplexing work out of the box. Some of these configs depend on your choices in the bootstrap script, denoted below by the (asks) prefix. These are the configuration defaults that differ by default from a freshly generated configuration:

• Configure the proxy server (online mode, autostart, ...)
• Enable one account multiplexer (second player character for each account)

• Remove unnecessary aliases from commands.yml
• Tell PaperMC that a proxy is used.
• Don't have PaperMC restart the server on crash. The system service takes care of that.
• Prevent annoying infinite sound broadcasts (dragon death, end portal, wither).
• Change the moved-too-quickly threshold to be less aggressive (ensures smoother elytra flight).
• Allow players to see entities up to 512 blocks away.
• Lower xp and item merge radius for a more vanilla experience while still reducing lag.

• (asks) Allow TNT duping and bedrock removal.
• (asks) Enable Anti-XRAY.
• (asks) Replenish loot chests after 1-2 realtime days.
• (asks) Disable hopper item move event.

• Set difficulty to HARD
• Increase slots to 6666
• (asks) Increase view distance to 15 chunks
• Increase entity broadcast range (allow players to see entities far away)
• Disable spawn protection (use better setting from vane-admin if you want this)
• Set online mode to false (this is checked by the proxy)
• Listen on port 25501 so proxy can connect (do not forward this port!)

If you want to uninstall this server, simply execute the following commands:

# Disable & stop services
systemctl disable --now minecraft-{proxy,server}
# Remove service files and attach script
rm /lib/systemd/system/minecraft-{proxy,server}.service /usr/bin/minecraft-attach
# Remove user and delete files in /var/lib/minecraft
userdel -r minecraft

• Cubiomes Viewer - To find a good world seed
• MCASelector - To trim e.g. unpopulated chunks

Do you want to suggest a feature or extend this deploy? Please feel free to create an issue or pull-request on github! Also if you want to create and maintain a packaged version of this deploy for your favourite distribution's package manager, feel free to reach out on the Vane Discord Server.