2nd April 2016, 22 min read

Setting up a “robust” Minecraft server (Java Edition) on a Raspberry Pi

My kids are gamers, and they love Minecraft. Minecraft sells its client software, but the server software is freely available. Since it is written in Java, it can run easily on Linux. Meanwhile, you can order neat little Raspberry Pi Linux computers for less than $50. So, putting two and two together, you can build cheaply a little box (not much bigger than my hand) that can be used as a permanent, low-power, perfectly silent game server. And you can expose your kids to servers, Linux and so forth.

There are many guides to setting up a Minecraft server on a Raspberry Pi, but the information is all over the place, and often obsolete. So I thought I would contribute my own technical guide. It took me a couple of long evenings to set things up, but if you follow my instructions, you can probably get it done in a couple of hours, once you have assembled all the material.

We are going to setup a Minecraft server for the old-school Java-based Minecraft. There are other Minecraft versions (e.g., on mobile devices) but they require different software. To be clear: if you are running Minecraft on a smartphone, a console or a tablet, it is may not compatible with the regular (Java) Minecraft. You can use Geyser to support console and android clients, but it is not covered by the current guide: you will have to do extra work on your own afterward if you need such support.

My instructions have been tested thoroughly and they work. They have worked for years. I recommend you pay close attention to each step. It is not difficult, but you need to be conscientious. Regularly, people complain that they instructions are out-of-date or incorrect: whenever we investigate, we find that these people have not followed the instructions properly. Many people try to go faster and skip steps or they fail to read everything. At this point in time, thousands of people have successfully followed these instructions. If they do not work for you, it is almost certainly because you did not follow them properly. Start again, and be conscientious.

You can make different choices and improvise, but if you do so, please understand that you are likely on your own to fix the problems you create.

Some people like to see a video of the setup:
Wakka Gaming & Tech made a video from this guide. (The video is not part of these instructions and was made by a tier. Please follow primarily these written instructions.)

Prerequisites

You need a working computer connected to the Internet. My instructions work whether you have a Mac, a Windows PC or a Linux box.
You need to buy a Raspberry Pi. I recommend getting a Raspberry Pi 4. Getting the model with 4GB of RAM might be a nice bonus. I tried long and hard to get a stable and fast server running on a first-generation Raspberry Pi, but it was not good. I find that the Raspberry Pi 3 is much better than the Raspberry Pi 2, unsurprisingly. I recommend that you dedicate the Raspberry Pi to the sole purpose of running a single Minecraft server. Trying to run other software, or more than one server, on the same Raspberry Pi is likely to cause troubles. So if you want to do several projects with a Raspberry Pi, then order several Raspberry Pis.
You need a power cord to go with the Raspberry Pi.
Moreover, you need a micro SD card. I recommend getting, at least, an 8GB card. Given how cheap cards are, you might as well get a larger card so that you do not ever have to worry about running out of space. I recommend getting the fastest card you can find. (Speed is normally indicated as a number, such as 5 or 10. Higher numbers are better.) For good measure, get several cards. SD cards wear out so you should plan on replacing the SD card; avoid re-using older SD cards. Be mindful that some cards are defective and will trigger random write errors. These errors might show up as mysterious failures in your Raspberry Pi. For this reason, I recommend getting more than one card: always have a backup.
I recommend getting a nice plastic box to enclose your Raspberry Pi, just so that it is prettier and sturdier.
You might also need an ethernet cable if you do not have one already. If you are going to use the Raspberry Pi, it is best to connect it directly to your router: wifi is slower, more troublesome and less scalable. I have had no end of trouble trying to run a Raspberry Pi server using wifi: I don’t know whether it is possible.
Though it is not strictly necessary, I urge you to get a heat sink for the CPU of the Raspberry Pi. The processor of the Raspberry Pi may heat up and when it does, the performance of the computer may drop drastically.
An HDMI cable, an HDMI-compatible monitor or TV, a USB keyboard and a USB mouse are also be required at first though not to run the server per se. The Raspberry Pi 4 needs a micro-HDMI to HDMI cable unlike the older Raspberry Pis that relied on a standard HDMI cable.

Instructions

You need to put the latest version of the Linux distribution for the Raspberry Pi, Raspberry Pi OS, on the SD card. If you have a recent Raspberry Pi (3 or 4), I recommend getting the 64-bit Raspberry Pi OS, as it may provide better performance and allow you to use more memory. My instructions assume that you get the full version. For some reason, many people prefer the “lite” version, but then they may have difficulty following my instructions. Please use the full version (the lite and the full versions are both free). You can make things work with the “lite” version and even save a few steps and some storage space, but if you go down the “lite” route, you should not expect the instructions to work for you. If you have an old version of the operating system, do not try to upgrade it unnecessarily. Starting from a fresh version is best. Simply follow the instructions from the Raspberry Pi website. Downloading the image file may take forever.
At first, you will need a monitor or a TV (with an HDMI connection), a keyboard and a mouse connected to the Raspberry Pi. Connect your Raspberry Pi to your router through the ethernet cable. Put the SD card in the Raspberry Pi. If, like it happened to me, the card won’t stay plugged in, just use a rubber band. Do so with some care as you can easily damage the SD card or the Raspberry Pi by pushing the card at the wrong angle or with too much strength. It is really, really important that the card be put in the Raspberry Pi nicely: some boxes that you might put the Raspberry Pi into make it difficult to fit the card just right. If needed, remove the Raspberry Pi from the box you put it in to make sure that everything is plugged in just right. Plug the monitor, the keyboard, and the mouse. Plug the power in and it should start.
The Raspberry Pi will launch in a graphical mode with mouse support and everything you expect from a modern operating system: we will soon get rid of this unnecessary luxury. Hopefully, you have Internet access right away. Because I am assuming that you are using an ethernet cable (as opposed to wifi), there should be no configuration needed for Internet access.
By default your username is “pi” on this new Raspberry Pi. Do not change it even if you know how. If you do so, you will need to update all the instructions: you are on your own.
Go to the terminal. On a Raspberry Pi with a graphical desktop, it can sometimes be found on the Desktop itself maybe under the name LXTERMINAL. You should be able to find it quickly by navigating through the graphical desktop and looking the icons. When it launches, the terminal application starts a “bash shell” (by default). In a shell, you type commands followed by the enter key. Try typing pwd, it should return /home/pi. If so, congratulations! You are on your way to becoming a Linux hacker!
(Optional) It helps to know that files in a modern computer are organized into directories (sometimes called folders). Directories can contain other directories, and so forth. On a Raspberry Pi, by default, you have a home directory located at /home/pi. You can create new directories under this home directory. You generally cannot write to files located outside your home directory and its subdirectories, nor can you create new directories everywhere: to do so, you need to invoke administrative privileges which is done by prefixing your commands by the sudo instruction. However, you should only use the sudo when it is strictly necessary as it is a security risk and it affects the file and directory permissions. It might help if you are familiar with the following shell commands:
pwd: gives you the current (working directory).
echo $HOME: gives you the location of your home directory (this should be /home/pi throughout.
cd newdirectory: changes the current directory to newdirectory if it exists.
mkdir newdirectory: creates a new directory called newdirectory under the current directory.
ls: displays all files and directories in the current directory.
cd ..: changes the current directory to the parent directory.
rm myfile: permanently deletes the file called myfile.
cp myfile1 myfile2: creates a new file called myfile2 which has the same content as myfile1.
mv myfile1 myfile2: moves or renames the file myfile1 to myfile1.

Install a few extra packages by typing this command line sudo apt-get install netatalk screen avahi-daemon default-jdk, followed by the enter key. Though the command may span more than one line in your browser, enter it as a single line. __Do not skip this important step. Please do not get into an argument as to whether you need all three packages: just install them, life is short.__

Type java --version. It should return a message telling you which Java version you have. It should be 8 or better. The latest versions of Minecraft require Java 16, but we can still build older versions with Java 8.

Make sure you have plenty of free disk space: type df. This will print a table with several columns. One column should be 'Use%' and another should be 'Mounted on'. Pay attention to the lines where 'Mounted on' is '/' or '/home'. There should be plenty of disk space: it is indicated by a low percentage value under 'Use%'. A percentage of use above 50% might be cause for concern. Should you ever encounter errors later, type `df` to check that you have plenty of disk space.

Try typing screen -list. If it complains that there is no `screen` command, go back to the previous step and install it. Otherwise, you should get a message of the type No Sockets found: that’s good!

Then type sudo raspi-config. This command starts a little configuration tool.

First, tell it to expand the file system so that it uses all the SD card.
For safety, I recommend changing the default password (the default account is called pi with password raspberry).
You want to tell the Raspberry Pi to boot in the shell: Console Autologin Text console, automatically logged in as 'pi' user.
In Internationalisation Options, you may want to configure the time and locale.
You may want to set the overclocking to the maximum setting, if the option is available. (Overclocking is optional and may cause instabilities and crashes.)
You want to assign the minimum amount of memory to the GPU (16 is enough) from Advanced Options. This is important: if you skip this step, some Raspberry Pis will simply not have enough memory to run the server and you will be getting errors.
Under the advanced options, you may want to check the Hostname value. It defaults to raspberrypi, I assume you are not changing it. You may need to change it if you have several Raspberry Pis on your network.
Make sure that the ssh server is on. The term “ssh” stands for “secure shell”, it is a way to connect to the shell of another machine remotely and securely (with encryption).
A nice trick at this point is to find the IP address of the Raspberry Pi on your network. Type ifconfig|grep "inet ". The result might contain two lines, one line with the string “addr:127.0.0.1” and another with a string that looks like “addr:192.168.1.87”. In that case, 192.168.1.87 is your IP address (your address will be different). Note that if you can access your router, you should also be able to find the IP address of your Raspberry Pi, but not everybody can or should access their router.

You can exit raspi-config which should bring you back to the bash shell. Reboot the Raspberry Pi by typing sudo reboot in the bash shell.

From your PC or Mac on the same network, you need to connect by `ssh` to [email protected].

On a Mac, just go to Terminal (Finder/Applications/Utilities/Terminal) and type ssh [email protected].
If you are using Windows, you can access your Raspberry Pi via ssh by using Putty. (If you have Windows 10, Microsoft makes available a Linux subsystem with full support for ssh. If you can make the Linux subsystem work, then typing ssh [email protected] in its bash shell should work.)

If, somehow, raspberrypi.local does not resolve, then replace it by the hard-coded IP address we found previously by typing ifconfig. Using a hard-coded IP address is not a good idea because it may change over time. However, temporarily using the hard coded IP address can allow you to make progress (e.g., check the configuration of the Raspberry Pi).

You should now be in the bash shell on the Raspberry Pi. Once this work, you can unplug the Raspberry Pi from the monitor, the keyboard and the mouse. Your server is now “headless”.

From your home directory on the Raspberry Pi, create a directory where you will install the Minecraft files: mkdir minecraft && cd minecraft. (This is a single command, on a single line.) You can install your files elsewhere, but you need to adapt the instructions below accordingly.

Download the build file for Spigot (your chosen Minecraft software) using the following command line: ```C wget https://hub.spigotmc.org/jenkins/job/BuildTools/lastSuccessfulBuild/artifact/target/BuildTools.jar ```

(Though the command may span several lines in your browser, it is a single line.)

Build the server by entering the following command line: ```C java -Xmx1024M -jar BuildTools.jar --rev 1.16.5```

(one line followed by the return key). You can change the version number (1.16.5) to use a more recent release but be mindful that recent versions of Minecraft require more recent Java versions (e.g., JDK 16). If it complains about not finding the java command, try typing sudo apt install default-jdk (one line followed by the return key) before typing again java -Xmx1024M -jar BuildTools.jar. Once the java program starts, its will take forever. Go drink coffee. After a long time, it will create a file called spigot-1.16.5.jar as well as many other files. If it fails with mysterious errors, make sure that you had enough disk space. Type

<tt>ls spigot*.jar</tt>```


to find how the jar files is called, I will assume that you have <tt>spigot-1.16.5.jar</tt>. The exact name and version number will change over time as spigot gets updated periodically. Adapt the instructions below according to the actual name of the file.

If the build fails with some Java-related error, [please report the issue with spigot](https://www.spigotmc.org/).
<li>Once this is done, start the server for the first time:
```C
<tt>java -jar -Xms512M -Xmx1008M spigot-1.16.5.jar nogui</tt>```


This will create a file called <tt>eula.txt</tt>. You need to edit it with the command
```C
<tt>echo "eula=true" &gt; eula.txt</tt>```


Make sure that the file contains the line <tt>eula=true</tt>, type
```C
<tt>more eula.txt</tt>```


to be sure.
<li>Start the server a second time:
```C
<tt>java -jar -Xms512M -Xmx1008M spigot-1.16.5.jar nogui</tt>```


It will take forever again. Go drink more coffee. Once the server return the command prompt, it should be operational. Have a Minecraft player connect to <tt>raspberrypi.local</tt>. Once you have verified that everything works, type <tt>stop</tt>. If your Raspberry Pi has a lot of memory (e.g., 4 GB or 8 GB) then you can change the -Xmx1008M to something like -Xmx2048M. The number (e.g., 2048M) should not exceed the available RAM. Giving the server more memory may improve the performance. If you have installed the 64-bit Raspberry Pi OS, you may even go safely to larger memory budgets (4096M or more).
<li>If you made it this far, then you got a minecraft server running on your Raspberry Pi. Fantastic! However, we want the server to keep on running even when we are not connected by `ssh` to the server. There are many ways to do this, but we will use `screen` to achieve our goal. It is not the best way, but it should be good enough.
<li>We are going to create a convenient script to start the server. Type <tt>nano minecraft.sh</tt> and write the following __four lines of code__:
```C
if ! screen -list | grep -q "minecraft"; then
  cd /home/pi/minecraft
  screen -S minecraft -d -m java -jar  -Xms512M -Xmx1008M spigot-1.16.5.jar nogui 
fi

It is really important to type the 4-line script (or copy and paste it) accurately. You can also grab the minecraft.sh file from GitHub if you prefer. You must remember to replace spigot-1.16.5.jar with the actual name of your jar file.

The if clause helps to make sure that only one instance runs at any one time (it is not perfect, but should be good enough).

Some people have trouble copying and pasting the content of the minecraft.sh file. As a sanity test, type wc -l minecraft.sh. The shell should return 4 minecraft.sh indicating that the script has 4 lines, if you do not see the number 4, do not continue! If you get any number other than 4, then you did not correctly copied the script, it will not work. I am aware that your browser might represent on the web page the 4 lines as more than 4 lines, but there are exactly 4 lines to be copied.

We also want to check the syntax of the script, so type bash -n minecraft.sh: this command should return immediately without any error. Now that we have verified that the script has four lines and has a valid syntax, let us make the script executable: chmod +x minecraft.sh.

You did remember that I am assuming that you have a file called spigot-1.16.jar, right? If your file name differs, please adapt the script accordingly. Please read the script again, make sure that everything is ok.

To make the server more stable, type nano spigot.yml. Set view-distance: 5. This may or may not be necessary, you can experiment. The downside of this setting is that the clients will get a more limited view.

Optionally, you may want to type nano server.properties and modify the greeting message given by the `motd` variable.

We want the server to start automatically when the Raspberry Pi reboots, so type sudo nano /etc/rc.local and enter su -l pi -c /home/pi/minecraft/minecraft.sh right before the exit command.

Start the server again using the script: ./minecraft.sh while in the bash shell. (I recommend __against__ typing sudo ./minecraft.sh as it would run the server as the root user: you do not want that.) The script will return you to the shell. There should be no error, if there is an error then you need to backtrack and start again: you missed a step somewhere. (These instructions have been thoroughly tested: chances are good that you did not follow them correctly if you are getting an error.)

Your minecraft server (Spigot) is managed using its own console. The console operates a bit like the bash shell: you type commands followed by the enter key. It is also used by the server to log its operations, so you can see what it is currently doing. To access the console of the minecraft server type screen -r minecraft, to return to the shell type ctrl-a d. At any point, you can now disconnect from the server. The server is still running. You do not need to remain connected to the Raspberry Pi.

Spigot makes use of temporary files (located in /tmp). This can cause performance issues and instabilities on a Raspberry Pi. It may even shorten the life of your SD card. It might be better to have temporary files reside in memory. To alleviate the problem, open the file /etc/fstab with a text editor such as `nano` as root (e.g., type sudo nano /etc/fstab). It should look something like this: ```C proc /proc proc defaults 0 0 /dev/mmcblk0p6 /boot vfat defaults 0 2 /dev/mmcblk0p7 / ext4 defaults,noatime 0 1 ```

(Though these three lines may span several lines in your browser, there is really just three lines.) The important point is that there should be no line where the second entry is “/tmp”. Then append a new line:

tmpfs           /tmp            tmpfs   nodev,nosuid,size=1M 0    0

(Though this line may appear as several lines in your browser, it is really just a single line.) Where you append/insert this line does not matter, but please note that you need to create a new line. The format of the fstab file requires that there is one entry per line. The fstab file is read at boot time and you must follow the syntax carefully otherwise you will get an error at the next reboot: so verify your work carefully. For this change to take effect, I recommend simply stopping the Minecraft server, by going to the server prompt (type screen -r minecraft if needed) and then typing stop. Then you can safely reboot the Raspberry Pi (e.g., with the sudo reboot command). If you have done everything right, the server should automatically start following a reboot sequence. In the future, the temporary files will get written to /tmp which is actually a disk in memory. Thus, your SD card won’t get touched so often.

If the command screen -r minecraft because there is no session called “minecraft”, it is like because you did not run the ./minecraft.sh or if you did, it was in error. You must be running the minecraft.sh script first if you want to be able to type screen -r minecraft.

You are done, congratulations!

And voilà ! The result is a “robust” and low-cost Minecraft server. You should be able to access it from a Java-based Minecraft desktop client using either raspberrypi.local or the IP address of the server.

If you ever need to stop the server, just log in with ssh, use screen -r minecraft to get to the server prompt and type stop. (If it complains that there is no minecraft screen, then you probably did not not run the minecraft.sh script first.) At the bash prompt, type sudo shutdown -h now. Wait a few seconds, then unplug the Raspberry Pi.

It is possible to add user-contributed plugins to your server. There are many desirable plugins. For example the lanbroadcaster plugin may allow your server to be automatically discovered by the Minecraft client within the same local network. To add a Minecraft plugin, drop the corresponding jar file in the plugins directory under the minecraft directory (/home/pi/minecraft/plugins) and restart the server (type stop in the server prompt and relaunch minecraft.sh). You can recover plugin jar files from the Internet using the wget or curl commands in a shell followed by the URL such as wget http://thedomain.com/theplugin.jar. If you misplaced the jar file on the Raspberry Pi, you can move it to the right directory with the mv command: mv theplugin.jar /home/pi/minecraft/plugins. If you have the plugin jar files on your Windows PC, you can use sftp to upload them to the Raspberry Pi from your PC. There are free sftp clients such as WinSCP.

You can easily setup several such servers, just buy more Raspberry Pis!

Next, you can make the server available on the Internet using a service like dyn.com, and some work on your router to redirect the Minecraft port (25565) from your router to the Raspberry Pi. It is not very difficult to do but it requires you to know a few things about how to configure your router. You should also be aware of the security implications. I am not going to tell you how to do it because the specifics depend on your exact configuration, on how you access the Internet, how your router is configured and so forth. At best, I could describe various scenarios, but if things go wrong, it could leave you without Internet, with security hole, or with a violation of the terms of services of your Internet provider. So you are on your own if you want to expose your server to the Internet at large.

Want to get your Raspberry Pi to do something different? I recommend simply switching to a different SD card containing the latest Linux distribution for Raspberry Pis. It is generally faster to start anew than to reconfigure a machine and given how inexpensive SD cards are. Don’t waste time reusing an existing card.

You may wonder why setting up a Minecraft server is so complicated. Can’t I or others just package the servers so that it is plug and play? We are limited because the copyright owners of Minecraft do want us to ship ready-to-run Minecraft servers. It should be possible, however, to largely automate the steps that I have outlined. I leave it as an exercise for the reader.

Is there any point to all of this? Probably not. Minecraft servers like Spigot are memory hungry and the Raspberry Pi has little memory. However, the project has stretched my imagination and made me think of new possibilities. I used to recycle old PCs as home servers to provide backups and caching for various projects. I got tired of having old, noisy and bulky PC in my home… but I could literally stack a cluster of Raspberry Pi computers in a shoe box. The fact that they are silent and use little power is really a blessing.

Extra: What if you have installed the Minecraft server, and now want to upgrade it? Sadly, there is no built-in support for in-place updates in Spigot as far as I know. When the software does not support updates, many things can go wrong if you try to force an update so I simply recommend against updates. If you need a new version, just reinstall a new version from scratch. If you want to explore with in-place updates despite my contrary advice, one comment to this post describes a possible approach, but I do not recommend it particularly. It is at your own risks.

Further reading: A short version of this blog post is a chapter in the book “Creative projects with Raspberry Pi” by K. Kearney and W. Freeman.