Installing and managing a Minecraft server on Ubuntu
I wanted to make a place for my kid to play Minecraft with his pals. I also wanted to try playing with a Raspberry Pi.
I quickly found that Raspberry Pis are near impossible to get a hold of without paying inflated prices, so I ended up with an Orange Pi 4B, a decently-priced Raspberry Pi clone. It'll run you around $130 on Amazon with 4GB RAM and 16GB embedded flash storage, and a shell + power supply.
The Orange Pi documentation is decent, and they have OS images ready to download. This page helped me understand where the included heatsinks are supposed to be attached (spoiler: the CPU and the flash memory, not the RAM).
My kid uses the "pocket" (mobile/tablet) version of Minecraft, which is Bedrock, not Java. So, I went with the Orange Pi Ubuntu image, as I found this excellent tutorial on installing Minecraft Bedrock on Ubuntu.
To get the OS onto the Orange Pi, you'll need an 8GB+ TF / MicroSD card. (They're interchangeable / basically the same thing.) Download the Ubuntu Orange Pi 4B image on your PC (I'm using a Mac), unzip, and flash to the microSD. Vincent Stevenson has a great video tutorial outlining the steps; this slightly older Ubuntu/Orange Pi 3 tutorial has some great detail as well. I used balenaEtcher to flash the .img file in the downloaded zip file, then put the microSD into the Orange Pi.
I connected the Orange Pi to an open LAN port on my router with an ethernet cable, plugged in the power supply, and waited about 30 seconds. Then I opened the admin page for my router (http://192.168.42.1/admin for my SmartRG SR515AC, thanks Sonic!) and found my Orange Pi's IP address in the Device Info > DHCP tab. Finally, I sshd to the Orange Pi from my PC (on the same LAN of course), using the default root/orangepi password in the Orange Pi Ubuntu image: ssh root@192.168.42.XX.
We're in!
___ ____ _ _ _
/ _ \| _ \(_) | || |
| | | | |_) | | | || |_
| |_| | __/| | |__ _|
\___/|_| |_| |_|
Welcome to Orange Pi 3.0.6 Focal with Linux 5.10.43
To wrap up the setup, we need to take a few more steps to prepare the Ubuntu install.
Update Ubuntu dependencies:
sudo apt update
Download needed utils and Java Runtime Environment (headless, since we don't need a GUI to run the server):
sudo apt install curl wget unzip grep screen -y
sudo apt-get install git openjdk-17-jre-headless
Create an admin user:
sudo usermod -a -G mcserver $USER
logout
Log into the new user and create a folder for the server install:
ssh mcserver@192.168.42.XX
mkdir minecraft-server
When I found this Bedrock / Ubuntu tutorial, I figured that would be the way to go. But I quickly realized that the Bedrock server doesn't have an version compiled to run on ARM processors, which is what we have on the Orange Pi. Uh-oh.
The TL;DR: Run a PaperMC (Java) server with the GeyserMC plugin installed to enable Bedrock clients to connect, and with the Floodgate plugin to allow those without a paid Java account to connect. Don't bother with the vanilla Java server, nor with Spigot -- Paper improves on Spigot in a number of ways.
Install and run Paper: copy the URL of the latest build on the Paper downloads page, download it to your Orange Pi, and run it once to get things set up:
# replace with the URL from the Paper downloads page
wget -O paper.jar https://api.papermc.io/v2/projects/paper/versions/1.19.3/builds/372/downloads/paper-1.19.3-372.jar
java -Xms2G -Xmx2G -jar paper.jar --nogui
It will take a while to initialize the first time; once you get to the server prompt, type stop to stop the server. After running it once (maybe twice? can't remember), a plugins/ folder will be created adjacent to the .jar. Download the Spigot builds of Geyser and Floodgate into it:
cd plugins
# replace with the URL from the Geyser and Floodgate downloads pages
wget https://ci.opencollab.dev/job/GeyserMC/job/Geyser/job/master/lastSuccessfulBuild/artifact/bootstrap/spigot/build/libs/Geyser-Spigot.jar
wget https://ci.opencollab.dev/job/GeyserMC/job/Floodgate/job/master/lastSuccessfulBuild/artifact/spigot/build/libs/floodgate-spigot.jar
Run the server one more time to pick up and auto-configure the plugins:
cd ../
java -Xms2G -Xmx2G -jar paper.jar --nogui
Your Minecraft Java server should now be set up and ready to accept Bedrock clients.
You can now connect with your Bedrock client over your LAN, via the Friends tab. It will appear as "Geyser / Another Geyser server". If that's good enough for you, congratulations! However, the whole point for me was so my kid's friends in far-off places can play Minecraft with him. So, we need set a static IP and port forward the required ports.
Minecraft servers expect requests from a Minecraft client on port 25565, via TCP/UDP. Geyser proxy servers communicate over port 19132, via UDP. Therefore, we need to make those ports available from our server via a technique called port forwarding. The approach varies widely across different router makes and firmwares; you can find info for your router on portforward.com.
First, set up a static IP for your Orange Pi on your router. For my Sonic SmartRG router:
- Go to the router admin page (192.168.42.1/admin)
- Navigate to Advanced Setup > LAN and, under "Static IP Lease List", click Add entries
- Switch over to your Orange Pi console and get its MAC address via
ip link - Choose a static IP host ID (the fourth number in the address, after the network ID configured by your router / LAN). E.g.
123is the host ID in192.168.42.123.
Now that your router assigns the same, static IP to your Orange Pi every time it connects to your network, you can find the external (or "public") IP for your Orange Pi. This is the IP that Minecraft clients will use to connect to your server. Switch back over to your Orange Pi console and type curl https://ipinfo.io/ip. Copy this down -- this is your external IP.
Then, forward the necessary ports. For my Sonic SmartRG router, I used this guide on portforward.com. In short:
- Go to the router admin page (192.168.42.1/admin)
- Navigate to Advanced Setup > NAT > Virtual Servers and click Add
- Since my Orange Pi is hardwired to my router, I selected
ipoe_eth4/eth4.1for the "Use interface" dropdown - Create one entry for Minecraft server requests: 25565 for external and internal port start and end, and TCP/UDP for protocol
- Create one entry for Geyser server requests: 19132 for external and internal port start and end, and UDP for protocol
Now you can check that your server is now accessible from the outside world. Start your server from the Orange Pi console as described in the above section, and wait for it to complete startup. You can then use a tool like yougetsignal's port checker for this. Note that, for a correct setup, yougetsignal shows port 25565 (minecraft) as open, but 19132 (geyser) as closed.
Finally, set up your server on a Minecraft Bedrock client (like the iOS version). Our favorite setup tutorial outlines the steps here, but the TL;DR:
- Log into your Microsoft/Minecraft account
- Open the Servers tab from the startup screen
- Scroll to the bottom and tap Add Server
- Give the server a name (that will display only on this client), type in the external IP we found above, and specify port 25565
- Tap the server you just configured to proceed to play!
The static IP assigned here remains fixed across server reboots. However, as soon as the router restarts, the device running the server gets a new static IP. In this case, you won't be able to connect from the Minecraft Bedrock client, and you'll see that yougetsignal's port checker shows the port is closed. For some reason, this also meant I needed to remove the forwarded port configs for 25565 / 19132 that we added in Advanced Setup > NAT > Virtual Servers and re-add them. After this, we're now able to connect from outside the LAN again. Note you'll also need to curl https://ipinfo.io/ip again from the OrangePI to get the newly-assigned static IP, and update that in the server config on your Minecraft client (e.g. on your iPad).
Also, for some reason, the port configured on the client must now be 19132, the Geyser proxy, unlike the 25565 entry we used previously. This may actually be a mistake in my previous documentation; I think Java clients may use 25565, but Bedrock clients need to connect to the Geyser proxy (via port 19132) to get proxied through to our Java/PaperMC server.
TODO
server.properties
start + stop scripts, w/ screen
systemd setup
server maintenance:
ssh mcserver@192.168.42.42
screen -r paper-server
testing server status w/ yougetsignal
As Minecraft clients update, you'll need to keep your server updated as well.
After an accidental Minecraft Bedrock update on our iPad, we started seeing this error when trying to connect:
Outdated Geyser proxy! This server supports the following Bedrock versions: 1.19.20, 1.19.21/1.19.22, 1.19.30/1.19.31, 1.19.40/1.19.41, 1.19.50/1.19.51
Updating is as simple as downloading new JAR files for Paper, Geyser, and Floodgate. Following the same process as Installing Minecraft server above:
# replace with the URL from the [Paper downloads page](https://papermc.io/downloads)
wget -O paper.jar https://api.papermc.io/v2/projects/paper/versions/1.19.3/builds/372/downloads/paper-1.19.3-372.jar
cd plugins
wget https://ci.opencollab.dev/job/GeyserMC/job/Geyser/job/master/lastSuccessfulBuild/artifact/bootstrap/spigot/build/libs/Geyser-Spigot.jar
wget https://ci.opencollab.dev/job/GeyserMC/job/Floodgate/job/master/lastSuccessfulBuild/artifact/spigot/build/libs/floodgate-spigot.jar
Start your server again and you're on the newest shiny!
One note -- when I went through this process, I stumbled into an error (that I didn't capture to paste here, sorry) where Java threw an error that .console_history was in an incorrect format, and would sometimes crash on launch, and other times would not respond to client requests / connections. Because the error was sometimes non-fatal, I didn't notice it in the server output logs at first.
The solution was to just rm .console_history and let it rebuild on the next server launch.
- Orange Pi documentation
- Orange Pi OS images
- Orange Pi 4 review + details
- Installing Ubuntu on Orange Pi 4
- Installing Ubuntu on Orange Pi 3 tutorial
- Minecraft: Bedrock vs Java
- Minecraft Bedrock on Ubuntu tutorial
- SmartRG SR515AC manual
- Paper vs Spigot
- Minecraft wiki: setting up a server
- Minecraft wiki: Port forwarding
- balenaEtcher flash OS to MicroSD
- PaperMC Minecraft server
- GeyserMC plugin
- Floodgate plugin
- Minecraft Server Tools
- Server status checker
- Open port verifier
to me, Gloriane
Start the Minecraft Bedrock Server at Boot on Ubuntu
Creating a startup + shutdown script using screen and a service to manage the server, and start automatically on boot
also: Ubuntu startup script w/ extra server config features Create Ubuntu startup script
consider using Aikar's flags to optimize performance
just noticed that Geyser has a bunch of its own configs in plugins/Geyser-Spigot/config.yml, will want to update some e.g. passthrough-motd
per Geyser/Floodgate instructions, i set auth-type: floodgate in geyser's config.yml
more details on geyser config.yml here
Fri, Jan 6, 9:50 PM (23 hours ago)
to me, Gloriane last bits:
set up script to run on boot, using screen
look into server script i noted above on minecraft wiki
document all this shit (post on GH?)
Eric Socolofsky eric@transmote.com
7:32 PM (1 hour ago)
to me, Gloriane server tools like MOTD and allowlist creator server status (online or not)
created a start-server.sh and stop-server.sh
these manage server thru a linux screen named paper-server
so to manager the server / get to its console, attach to the screen: screen -r paper-server
created minecraft-server.service, borrowing bits from: https://blog.infoitech.co.uk/linux-systemd-service-unit-minecraft/ https://pimylifeup.com/ubuntu-minecraft-bedrock-server/#start-the-minecraft-bedrock-server-at-boot-on-ubuntu https://minecraft.fandom.com/wiki/Tutorials/Ubuntu_startup_script
tested a hard reboot and the server is up
reminder, to get to the server console:
ssh mcserver@192.168.42.42
screen -r paper-server