Building a portable Minecraft server

Minecraft-BannerOriginal Article

Minecraft is a lot of fun, especially when you play with friends. Minecraft servers are great but they aren’t very portable and rely on a good Internet connection. What about if you could take your own portable server with you – say to the park – and it will fit inside a lunchbox?

This post is about doing just that, building a small, portable minecraft server that you can use to host pop up crafting sessions no matter where you are when the mood strikes.


where shell instructions are provided in this document, they are presented assuming you have relevant permissions to execute them. If you run into permission denied errors then execute using sudo or switch user to elevate your permissions.

Bill of Materials

The following components are needed.

Item QTY Notes
Raspberry Pi 2 Model B 1 Older version will be too laggy. Get a new one
4GB MicroSD card with raspbian installed on it 1 The faster the class of SD card the better
WiPi wireless USB dongle 1 Note that “cheap” USB dongles often won’t support hostmode so can’t create a network access point. The “official” ones cost more but are known to work.
USB Powerbank 1 Make sure it’s designed for charging tablets (ie 2.1A) and the higher capacity the better (5000mAh or better is good).


I am assuming you’ve done the following with regards to getting your Raspberry Pi operational.

  • Latest Raspbian is installed and is up to date – run ‘apt-get update && apt-get upgrade’ if unsure.
  • Using raspi-config you have set the correct timezone for your location and you have expanded the file system to fill the SD card.
  • You have wireless configured and you can access your network using wpa_supplicant
  • You’ve configured the Pi to be accessible over SSH and you have a client that allows you do this (eg ssh, putty etc).


I’ll break the setup into a few parts, each focussing on one aspect of what we’re trying to do. These are:

  • Getting the base dependencies you need to install everything on the RPi
  • Installing and configuring a minecraft server that will run on the Pi
  • Configuring the wireless access point.
  • Automating everything to happen at boot time.

Configure your Raspberry Pi

Before running minecraft server on the RPi you will need a few additional packaged than you have probably installed by default. From a command line install the following:

sudo apt-get install oracle-java8-jdk git avahi-daemon avahi-utils hostapd dnsmasq screen

Java is required for minecraft and building the minecraft packages

  • git will allow you to install various source packages
  • avahi (also known as ZeroConf) will allow other machines to talk to your machine by name rather than IP address (which means you can connect to minecraft.local rather than or similar).
  • dnsmasq allows you to run a DNS server and assign IP addresses to the machines that connect to your minecraft box
  • hostapd uses your wifi module to create a wireless access point (so you can play minecraft in a tent with your friends).

Now you have the various components we need, it’s time to start building your minecraft server.

Download the script repo

To make this as fast as possible I’ve created a repository on Github that has all of the config files in it. Download this using the following commands:

mkdir ~/tmp
cd ~/tmp
git clone

This will place a folder called ‘mc-config’ inside your ~/tmp directory. Everything will be referenced from there.

Get a spigot build

It is possible to run Minecraft using the Vanilla Minecraft server however it’s a little laggy. Spigot is a fork of CraftBukkit that seems to be a bit more performance oriented and a lot more stable. Using the Vanilla minecraft server I was experiencing lots of lag issues and crashes, with Spigot these disappeared entirely.

The challenge with Spigot is you have to build the server from scratch as it can’t be distributed. This takes a little while on an RPi but is mostly automated. Run the following commands.

mkdir ~/tmp/mc-build
cd ~/tmp/mc-build
java -jar BuildTools.jar --rev 1.8

If you have a dev environment setup on your computer you can do this step locally and it will be a lot faster. The key thing is at the end to put the spigot-1.8.jar and the craftbukkit-1.8.jar files on the RPi in the ~/tmp/mc-build/ directory. You can do this with scp.

Now wait a while. If you’re impatient, open up another SSH connection to your server and configure your access point while the build process is happening.

//time passes

After about 45 minutes, you should have your own spigot build. Time to configure that with the following commands:

cd ~/tmp/mc-config

This will run a helper script which will then setup some baseline properties for your server and some plugins to help it be more stable. It will also move the server files to the right spot, configure a minecraft user and set minecraft to run as a service when you boot up.

Once that is complete, you can start your server.

service minecraft-server start

The first time you do this it will take a long time as it has to build out the whole world, create config files and do all sorts of set up things. After this is done the first time however, it will usually only take 10 to 20 seconds to start after this.

Administer your server

We are using a tool called “screen” to run our minecraft server. Screen is a useful utility that allows you to create a shell and then execute things within it and just connect and detach from it as you please. This is a really handy utility say when you are running something for a long time and you want to detach your ssh session and reconnect to it later – perhaps you have a flaky connection.

When the minecraft service starts up it creates a new screen session, and gives it the name “minecraft_server” and runs the spigot server command. The nice thing with this is that once the spigot server stops, the screen will close too.

Now if you want to connect to your minecraft server the way you do it is like this:

sudo screen -r minecraft_server

To leave your server running just hit <CRTL+a> then hit the “d” key. CTRL+A sends an “action” and then “d” sends “detach”. You can keep resuming and detaching like this as much as you like.

To stop the server you can do it two ways. The first is to do it manually once you’ve connected to the screen session then type “stop”. This is good as it means you can watch the minecraft server come down and ensure there’s no errors.

Alternatively just type:

service minecraft-server stop

And this actually simulates doing exactly the same thing.

Connect to your server

Once you’ve got your minecraft server running, attempt to connect to it from your normal computer using multiplayer and then direct connect. The machine address will be minecraft.local (unless you changed it to something else).


Figure: Server selection

Now you have the minecraft server complete you can simply ssh in, run ‘service minecraft-server start’ and your server will come up for you and your friends to play. The next sections will get you portable and automated.

Setting up the WiFi host

The way I’m going to show you to set up the Raspberry Pi is a little different than other tutorials you’ll see. The objective is that if the RPi can discover an SSID that it is allowed to join (eg your home network) then it should join that. If the RPi can’t discover a network it knows, then it should create it’s own and allow other machines to join it.

This means that when you have your minecraft server sitting in your kitchen you can update the OS, download new mods and use it on your existing network. When you take it to the park to have a sunny Crafting session with your friends, the server will create it’s own network that you can all jump onto.

Turn off auto wlan management

By default the OS will try and do the “right thing” when you plug in a network interface so when you go to create your access point, it will actually try and put it on the wireless network again – not the desired result. To change this make the following modifications to /etc/default/ifplugd

change the lines:




Configure hostapd

Now, stop hostapd and dnsmasq from running at boot. They should only come up when needed so the following commands will make them manual.

update-rc.d -f hostapd remove
update-rc.d -f dnsmasq remove

Next, modify the hostapd daemon file to read the hostapd config from a file. Change the /etc/default/hostapd file to have the line:


Now create the /etc/hostapd/hostapd.conf file using this command using the one from the repo.

cd ~/tmp/mc-config
cp hostapd.conf /etc/hostapd/hostapd.conf

If you look at this file you can see we’ve set the SSID of the access point to be “minecraft”, the password to be “minecraft12345” and it has been set to use wlan0. If you want to change any of these things, feel free to do it.

Now you’ll probably want to kill your wireless device with

ifdown wlan0

Make sure all your other processes are finished if you’re doing this and compiling spigot at the same time (or make sure you’re connected via the wired ethernet as well).

Now run hostapd to just check any config errors.

hostapd -d /etc/hostapd/hostapd.conf

If there are no errors, then background the task (ctrl + z then type ‘bg 1’) and look at ifconfig. You should now have the wlan0 interface up as well as a wlan0.mon interface. If this is all good then you know your config is working for hostapd. Foreground the task (‘fg 1’) and stop the hostapd process (ctrl + c).

Configure dnsmasq

Now to get dnsmasq running – this is pretty easy.

Download the dnsmasq example and put it in the right place using this command:

cd ~/tmp/mc-config
mv /etc/dnsmasq.conf /etc/dnsmasq.conf.backup
cp dnsmasq.conf /etc/dnsmasq.conf

dnsmasq is set to listen on wlan0 and allocate IP addresses in the range – The default IP address of the server will be

That’s pretty much all you really need to get dnsmasq configured.

Testing the config

Now it’s time to test all this configuration. It is probably useful to have your RPi connected to a keyboard and monitor or available over eth0 as this is the most likely point where things may need debugging. The following commands will bring down wlan0, start hostapd, configure your wlan0 interface to a static IP address then start up dnsmasq.

ifdown wlan0
service hostapd start
ifconfig wlan0
service dnsmasq start

Assuming you had no errors, you can now connect to your wireless access point from your laptop or phone using the SSID “minecraft” and password “minecraft12345”. Once you are connected you should be given an IP address and you should be able to ping and shell onto minecraft.local.

Congratulations – you’ve now got a Raspberry Pi Wireless Access Point.

As an aside, were you to write some iptables rules, you could now route traffic from the wlan0 interface to the eth0 interface and out onto the rest of your wired network – thus turning your RPi into a router.

Running everything at boot

The final setup task is to make the wifi detection happen at boot time. Most flavours of linux have a boot script called rc.local which is pretty much the final thing to run before giving you your login prompt at a terminal.

Download the rc.local file using the following commands.

mv /etc/rc.local /etc/rc.local.backup
cp rc.local /etc/rc.local
chmod a+x /etc/rc.local

This script checks to see if the RPi came up on the network. If not it will wait a couple of seconds, then start setting up hostapd and dnsmasq.

To test this is all working, modify your /etc/wpa_supplicant/wpa_supplicant.conf file and change the SSID so it’s clearly incorrect. For example if your SSID was “home” change it to “home2”. This way when the RPi boots it won’t find it and the access point will be created.

Park Crafting

Now you have your RPi minecraft server and it can detect networks and make good choices about when to create it’s own network, the next thing you need to do it make it portable.

The new version 2 RPi is more energy efficient, though running both minecraft and a wifi access point is going to use some power.

The easiest way to go mobile is to get a high capacity USB powerbank that is designed for charging tablets. They can be expensive but a large capacity one will keep you going for hours.

This powerbank is 5000mAh and can deliver 2.1amps over it’s USB connection. Plenty for several hours crafting in the park.

Setting this up couldn’t be easier, plug a usb cable into the powerbank and then into the RPi. When you’re done, simply plug the powerbank into your USB charger or computer and charge it up again.

If you want something a little more custom then 7.4v lipo batteries with a step down voltage regulator (such as this one from Pololu: connected to the power and ground pins on the RPi works very well. The challenge here is charging the LiPo again, however if you have the means to balance charge lipos then this will probably be a very cheap option.

If you connect more than 5V to the RPi you WILL destroy it. There are no protection circuits when you use the GPIO pins.

To protect your setup simply put it in a little plastic container like a lunch box. This is how mine travels with me.

Minecraft, Raspberry Pi

A plastic lunchbox will protect your server from spilled drinks, enthusiastic dogs and toddlers attracted to the blinking lights.

Take your RPi and power supply to the park, along with your laptop and some friends then create your own little wifi hotspot and play some minecraft together in the sun.

Going further

If you want to take things a little further, here are some ideas:

  • Build a custom enclosure – maybe something that looks like your favorite minecraft block.
  • Using WiringPi (C) or RPI.GPIO (Python), attach an LCD screen that shows the status of your server and who is connected to the minecraft world.
  • Add some custom LEDs to your enclosure then using RaspberryJuice and the python interface to the API, create objects in your gameworld that can switch the LEDs on and off.
  • Add a big red button to your enclosure that when pressed will “nuke” the game world, removing all blocks and leaving only water.
  • Go a little easier and simply use the button to kick everyone off the server when it’s time to go or your battery is getting low.

Thank you



Leave a Reply