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 probably not compatible with the regular Minecraft.

My instructions have been tested thoroughly and they work. I recommend you pay close attention to each step. It is not difficult, but you need to be conscientious.

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

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 either a Raspberry Pi 2 or a Raspberry Pi 3. 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.
  • 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.
  • 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.

Instructions

• You need to put the latest version of the Linux distribution for Raspberry Pi, Raspbian on the SD card. My instructions assume that you get the full version. For some reason, many people prefer the “lite” version, but they also seem to encounter more problems. Please use the full version (the lite and the full versions are both free). 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 files takes 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. 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. Plug the monitor, the keyboard, and the mouse. Plug the power in and it should start. If, like it happened to me, the card won’t stay plugged in, just use a rubber band.
• 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, 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.
• 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.
  1. First, tell it to expand the file system so that it uses all the SD card.
  2. For safety, I recommend changing the default password (the default account is called pi with password raspberry).
  3. You want to tell the Raspberry Pi to boot in the shell: Console Autologin Text console, automatically logged in as 'pi' user.
  4. In Internationalisation Options, you may want to configure the time and locale.
  5. 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.)
  6. You want to assign the minimum amount of memory to the GPU (16 is enough) from Advanced Options.
  7. 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.
  8. 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).
  9. 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 pi@raspberrypi.local.
  • On a Mac, just go to Terminal (Finder/Applications/Utilities/Terminal) and type ssh pi@raspberrypi.local.
  • 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 pi@raspberrypi.local 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:

  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: java -jar BuildTools.jar. This will take forever. Go drink coffee. After a long time, in my case, it created a file called spigot-1.9.jar as well as many other files. Type ls spigot*.jar to find how the jar files is called, I will assume that you have spigot-1.9.jar. Adapt the instructions below according to the actual name of the file.
• Once this is done, start the server for the first time: java -jar -Xms512M -Xmx1008M spigot-1.9.jar nogui. This will create a file called eula.txt. You need to edit it with the command nano eula.txt. Make sure it reads eula=true.
• Start the server a second time: java -jar -Xms512M -Xmx1008M spigot-1.9.jar nogui. 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 raspberrypi.local. Once you have verified that everything works, type stop.
• 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.
• We are going to create a convenient script to start the server. Type nano minecraft.sh and write the following four lines of code:

  if ! screen -list | grep -q "minecraft"; then
    cd /home/pi/minecraft
    screen -S minecraft -d -m java -jar  -Xms512M -Xmx1008M spigot-1.9.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.

  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.9.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:

  proc            /proc           proc    defaults          0       0
  /dev/mmcblk0p6  /boot           vfat    defaults          0       2
  /dev/mmcblk0p7  /               ext4    defaults,noatime  0       1
  

  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
  

  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. 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.

• You are done, congratulations!

And voilà! The result is a “robust” and low-cost Minecraft 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. At the bash prompt, type sudo shutdown -h now. Wait a few seconds, then unplug the Raspberry Pi.

The 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.