So my kids were asking to play Minecraft. Didn’t think much about it at first, but then thought why not; it could be fun, I’ve got a spare Pi hanging out, and I’ve got nothing better to do at the moment. Turned out the actual setup was way harder than I anticipated on a Pi. So…we’re going to go through the entire process of how to set up a Minecraft Server on a Raspberry Pi or Linux system with all the pitfalls I ran across. This method worked for me; it may not work for you, but after trying the officially supported method straight from Mojang to several other methods found on Google and not a one worked…yeah, going with this way.

The end result for this particular tutorial is to set up a Minecraft Server that runs both Geyser and Floodgate plugins. Because we’re using Geyser and Floodgate, both Bedrock and Java players can connect to the server regardless of which edition of Minecraft is being used. You will need some decent knowledge of Linux/Raspbian, networking, and the command line to do this. I do not claim credit for the script to set up the server, see the author’s page for that particular script for more options and commentary.

Hardware and Software

Pretty basic hardware list. Basically, you’ll need something to run as an always-on server. Here’s what I’m using:

Raspberry Pi 4B
Minecraft Java edition
Geyser and Floodgate plugins

Of note, as of the writing of this post Raspberry Pi computers are in very short supply. If you can’t find a Pi, anything that can setup and run Docker is fine (which is just about any computer out there). I’ve used this on both a Raspberry Pi and a Lenovo mini-PC running Linux Mint.

Raspberry Setup

OS Setup/Upgrade

If this is fresh Pi, make sure to set up your OS with Bullseye. Found out the hard way Buster doesn’t cut it. Using the Raspberry Pi imager is the easiest way to install Raspberry Pi OS. See this post for a rundown on how to get a Pi up and running. You can skip the VNC viewer install if you want, as we are not going to be needing to access the Pi desktop.

If you are not using the imager but instead need to do an in-place upgrade from Buster (or any other previous distro) to Bullseye we’ll need to do a little more work. Be warned, it takes a while. For the original guide, see this post (external link). Either way, to set up a Minecraft server you will need to make sure you’re running the latest distro.

In-Place Upgrade Steps

Not officially recommended

Be aware that this process is not officially recommended. You will need to make sure your Pi is hardwired, as you will temporarily lose Wi-Fi. Backup any critical files before starting.

SSH into your Pi and update the repository list, install latest packages and dependencies, and reboot:

sudo apt update
sudo apt full-upgrade
sudo reboot

Update to the latest firmware (may require another reboot):

sudo rpi-update

Switch the repository list from Buster to Bullseye by opening the nano editor:

sudo nano /etc/apt/sources.list

Find the following line and change buster to bullseye:

deb buster main contrib non-free rpi

Save your changes and proceed to the next step (Ctrl+O, Y, Enter).

Update the repository lists again using Bullseye instead of Buster, install Node.js and GCC 8, and do a full upgrade. You may receive a notice to restart service during package upgrades without asking, choose “Yes”. This step will take a while:

sudo apt update
sudo apt install nodejs
sudo apt install gcc-8-base
sudo apt full-upgrade

Clean up old packages:

sudo apt autoclean
sudo apt autoremove

Alter the /boot/config.txt file to enable KMS. This is done by default with a clean install by the imager utility, but an in-place upgrade requires a manual intervention:

sudo sed -i 's/dtoverlay=vc4-fkms-v3d/#dtoverlay=vc4-fkms-v3d/g' /boot/config.txt
sudo sed -i 's/\[all\]/\[all\]\ndtoverlay=vc4-kms-v3d/' /boot/config.txt

Finally, reboot:

sudo reboot

Make sure everything works after the reboot and that you have officially updated to Bullseye:

cat /etc/os-release

You should get something like the following:

PRETTY_NAME="Raspbian GNU/Linux 11 (bullseye)"
NAME="Raspbian GNU/Linux"
VERSION="11 (bullseye)"

That’s it for an in-place upgrade. You can re-enable wireless by going to raspi-config and editing the wireless settings.

Server Setup (Any Linux-based system)

Install Docker

We’re going to use Docker to run the server; this allows for easy starting/stopping and backups. To install, its simply:

curl -sSL | sh

Next, give your current user permissions to interact with Docker (i.e. pi):

sudo usermod -aG docker pi

Logout to allow changes to take effect:


Finally, you can test the install by running a test container:

docker run hello-world

Successful installation will result in a welcome message.

Install the Minecraft Server

For a full guide and troubleshooting comments, visit this page. Of note, it was by reading through the comments that I was able to figure out that my main issue with installation was because my Pi was still running the Buster release. The page owner is super responsive to queries and can often walk you through any issues with installation. It’s the easiest way to set up a Minecraft server by far. If running Linux Mint or another distro, you shouldn’t run into any issues.

First up, create a Docker volume to drop the installation in (replace yourvolumename with a unique volume name such as “minecraft”:

docker volume create yourvolumename

Launch the server and open required ports. I’m using the default ports in this case, but you can change the ports to anything else (recommended from a security standpoint) with additional scripts located on the author’s page. Replace yourvolumename with the name of the Docker volume you just created:

docker run -it -v yourvolumename:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 05jchambers/legendary-minecraft-geyser-floodgate:latest

And that is pretty much it. This script was the most comprehensive and easiest way to get the server up and running initially. However, exiting the terminal stops the container. So, we’ve still got a few steps. Type exit to stop the server for now.

Edit your file

Before you really dig into the game you want to define how your server will behave.

If you followed the rest of the guide, your server properties will be, most likely, at /var/lib/docker/volumes/yourvolumename/_data/. So, to open up and edit the file:

sudo nano /var/lib/docker/volumes/yourvolumename/_data/

You should see a text file like this:

#Minecraft server properties
#Tue Sep 27 10:19:28 MDT 2022
motd=The Mays Minecraft Server

I’m not going to dig into all of the different server properties. The only items I will point out are the game mode, difficulty, and flight options. By default, the game mode is “survival”. You will take damage, need to eat, and can die. You can set this to “creative” for a more open game in which you will not take damage or need to eat. Likewise, if you set allow-flight=true, then you can fly if you have a plugin that allows it.

For a complete explanation of each property see this page.

Run the server with restart option

So we want the server to run on its own and restart if it stops for some reason. We’re going to use a Docker run command with restart options. So, in the command line type:

docker run -d --restart unless-stopped -it -v yourvolumename:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 05jchambers/legendary-minecraft-geyser-floodgate:latest

This command runs the container, tells it to restart, and restart unless it is manually stopped. Of note, the container has to successfully start and run for it to work so you will not get stuck in an infinite start/stop loop. No point in having a server if you can’t connect without manually logging in and running it each time.

Connect to the Server

On the client of your choosing (I’ve used Xbox, PC, and Android so far) download the Minecraft app and launch it. You’ll want to play the game and connect to a new server. Enter the IP address of the server and leave the port at default (if you went with the default ports used in the setup script). Join the server and you should be placed into your own, fresh Minecraft world. If you’re having issues connecting, make sure your ports are opened on the machine running the server.

That’s it! At this point you have set up a Minecraft server that is available to local LAN players. This server is local to your network, so nobody from the outside world can just join. That is a topic for another day to set up external access to your server. That being said, you can join externally using a VPN. Another perk to this setup is that it works across any platform: Xbox, PC, Android, and iOS.


Optional: Set up Portainer

Portainer is an optional way to easily manage docker containers. You can manage docker entirely from the command line, but I like a nice GUI. It’s an easy setup.

Start by pulling Portainer:

sudo docker pull portainer/portainer-ce:latest

Next, run Portainer. Note that if you want to change the default port of 9000, do it here.

sudo docker run -d -p 9000:9000 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest

This names the container, runs it, and restarts it if it ever goes offline. Lastly, make sure you have opened the port assigned to Portainer to access it with a browser.

Next, access the web GUI by going to your Pi’s IP address (use hostname -I in the command line if you’re not sure) and the Portainer port (http://yourpiip:9000).

On the first launch of the web interface you will need to set up an admin user. Pick a username and set a strong password and hit “Create User”. Since docker is already running, you most likely will not need to do anything further. Hit the home link and you should see a page like this:

Portainer home page

Clicking on the docker instance opens up the dashboard, where you can view basic info about the docker instance. Clicking on your containers will show a list of running containers:

portainer container list

Clicking on a running container will allow you to stop, start, kill, restart, pause, resume, or remove the container. Additionally, the quick actions icons allow you to view common container actions.

Optional: Let friends play with you

This requires a registered domain name, or you will need to use a hosted Minecraft service (of which there are plenty). You’ll need to set up DNS records to point to your server and open router ports to send requests through the firewall to the server.

DNS Setup

I use Cloudflare, but the process is similar for other hosting services. We’re going to set up a friendly name so you don’t have to post or give out your public IP. First up, set up an A record that points to your public IP:

A Name: Target: Public IP TTL: auto

Next up define a SRV record. This will tell any incoming requests on the Minecraft service ports to go to your subdomain on those ports:

SRV Name: minecraft Service: _minecraft Protocol: UDP TTL: Auto Priority: 0 Weight: 5 Port: 19132 Target:

Couple of notes here. The Bedrock clients will connect via UDP to port 19132. If you changed the default port, make sure to change that port here. Second, make sure the target is identical to the A record you just set up.

Once that’s done, give it up to 24 hours to propagate. If you use Cloudflare it’s pretty much instant.

Port Forward your Router

Last up you will need to tell your router to let incoming requests to your Minecraft port go through and to point them at the server. You’ll need to log in to your router’s admin panel. Port forwarding is usually under the firewall settings.

To set up the port forward just define the incoming port (19132) and tell your router to send that to the server IP address on the same port. I won’t go into detail, since it’s a little different for every router; check your router documentation if you get stuck. One important note, though, is to not open any more ports than necessary since each open port is a security risk. If possible, change your port from the default to something random if you plan on exposing your server to the internet at large.

Author: Zack

Pharmacist, tech guy, pianist, lover of beer, gamer, beach bum. Probably missed something. Just assume I'm into a little bit of everything.


No responses yet

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
Filter by Categories
Alcoholic Drinks (Cocktails)
Cool Stuff
Fish and Seafood
Home and Family
Home Automation
Home Security
Recipe of the Week
Web Hosting