![Minecraft Geyser + Floodgate Paper Minecraft Server](https://jamesachambers.com/wp-content/uploads/2022/08/Minecraft-Geyser-Docker-Container-1024x576.webp)
This is a new Docker container to automatically set up and run a Minecraft server that both Java and Bedrock players can connect to! This allows everyone to play on your server no matter which edition of Minecraft you are using. It uses the Geyser and Floodgate plugins to accomplish this.
Since it uses the Paper Minecraft server it also supports any additional plugins that are compatible with Paper / Spigot. This gives you the ability to do many things that are currently impossible to do in Bedrock if you are hosting the official Bedrock dedicated server.
It is fully compatible with my Paper Minecraft Java Server Container and you can swap between these two containers without changing any configuration.
The official GitHub page is located here.
The Docker Hub page for the container is located here.
It’s now possible to convert your worlds between Bedrock and Java versions. Check out my guide on Chunker here for more information.
Features
- Sets up fully operational Minecraft server that allows both Java and Bedrock clients to connect
- Runs the highly efficient “Paper” Minecraft server
- Runs Geyser to allow Bedrock clients to connect and Floodgate to allow them to authenticate with their Bedrock credentials to a Java server
- Plugin support for Paper / Spigot / Bukkit
- Uses named Docker volume for safe and easy to access storage of server data files (which enables more advanced Docker features such as automatic volume backups)
- Installs and configures OpenJDK 18
- Automatic backups to minecraft/backups when server restarts
- Full logging available in minecraft/logs folder
- Updates automatically to the latest version when server is started
- Runs on all Docker platforms including Raspberry Pi
Usage
First you must create a named Docker volume. This can be done with:
docker volume create yourvolumename
Now you may launch the server and open the ports necessary with one of the following Docker launch commands.
With default ports:
docker run -it -v yourvolumename:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 --restart unless-stopped 05jchambers/legendary-minecraft-geyser-floodgate:latest
With custom ports:
docker run -it -v yourvolumename:/minecraft -p 12345:12345 -e Port=12345 -p 54321:54321/udp -p 54321:54321 -e BedrockPort=54321 --restart unless-stopped 05jchambers/legendary-minecraft-geyser-floodgate:latest
With a custom Minecraft version (add -e Version=1.X.X, must be present on Paper’s API servers to work):
docker run -it -v yourvolumename:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 -e Version=1.17.1 --restart unless-stopped 05jchambers/legendary-minecraft-geyser-floodgate:latest
With a maximum memory limit in megabytes (optional, prevents crashes on platforms with limited memory, -e MaxMemory=2048):
docker run -it -v yourvolumename:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 -e MaxMemory=2048 --restart unless-stopped 05jchambers/legendary-minecraft-geyser-floodgate:latest
Using a custom timezone:
docker run -it -v yourvolumename:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 -e TZ="America/Denver" --restart unless-stopped 05jchambers/legendary-minecraft-geyser-floodgate:latest
Skipping backups on a certain folder:
docker run -it -v yourvolumename:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 -e NoBackup="plugins" --restart unless-stopped 05jchambers/legendary-minecraft-geyser-floodgate:latest
Skipping permissions check:
docker run -it -v yourvolumename:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 -e NoPermCheck="Y" --restart unless-stopped 05jchambers/legendary-minecraft-geyser-floodgate:latest
Change number of backups:
docker run -it -v yourvolumename:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 -e BackupCount=1 --restart unless-stopped 05jchambers/legendary-minecraft-geyser-floodgate:latest
Configuration / Accessing Server Files
The server data is stored where Docker stores your volumes. This is typically a folder on the host OS that is shared and mounted with the container. I’ll give the usual locations here but if you’re having trouble just do some Googling for your exact platform and you should find where Docker is storing the volume files.
You can find your exact path by typing:
docker volume inspect yourvolumename
This will give you the fully qualified path to your volume like this:
{ "CreatedAt": "2022-05-09T21:08:34-06:00", "Driver": "local", "Labels": {}, "Mountpoint": "/var/lib/docker/volumes/yourvolumename/_data", "Name": "yourvolumename", "Options": {}, "Scope": "local" }
On Linux it’s typically available at:
/var/lib/docker/volumes/yourvolumename/_data
On Windows it’s at
C:\ProgramData\DockerDesktop
but may be located at something more like
\wsl$\docker-desktop-data\version-pack-data\community\docker\volumes\
if you are using WSL (Windows Subsystem for Linux).
On Mac it’s typically
~/Library/Containers/com.docker.docker/Data/vms/0/
If you are using Docker Desktop on Mac then you need to access the Docker VM with the following command first:
screen ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty
You can then normally access the Docker volumes using the path you found in the first step with docker volume inspect.
Most people will want to edit server.properties. You can make the changes to the file and then restart the container to make them effective.
Backups are stored in the “backups” folder
Log files with timestamps are stored in the “logs” folder.
Plugin Support for Paper / Spigot / Bukkit
This is a “Paper” Minecraft server which has plugin compatibility with Paper / Spigot / Bukkit.
Installation is simple. There is a “plugins” folder on your Docker named volume.
Navigate to your server files on your host operating system (see accessing server files section if you don’t know where this is) and you will see the “plugins” folder.
You just need to drop the extracted version of the plugin (a .jar file) into this folder and restart the container. That’s it!
Some plugins have dependencies so make sure you read the installation guide first for the plugin you are looking at.
A popular place to get plugins is: dev.bukkit.org
Troubleshooting Note – Oracle Virtual Machines
A very common problem people have with the Oracle Virtual Machine tutorials out there that typically show you how to use a free VM is that the VM is much more difficult to configure than just about any other product / offering out there.
It is because there are several steps you need to take to open the ports on the Oracle VM. You need to both:
- Set the ingress ports (TCP/UDP) in the Virtual Cloud Network (VCN) security list
- *and* set the ingress ports in a Network Security Group assigned to your instance
Both of these settings are typically required before you will be able to connect to your VM instance. This is purely configuration related and has nothing to do with the script or the Minecraft server itself.
I do not recommend this platform due to the configuration difficulty but the people who have gone through the pain of configuring an Oracle VM have had good experiences with it after that point. Just keep in mind it’s going to be a rough ride through the configuration for most people.
Troubleshooting Note – Hyper-V
There is a weird bug in Hyper-V that breaks UDP connections on the Minecraft server. The easy workaround for this is that you have to use a Generation 1 VM with the Legacy LAN network driver.
There is a second fix that was shared by bpsimons here. For that fix you need to install ethtool first with sudo apt install ethtool. Next in your /etc/network/interfaces file add “offload-tx off” to the bottom as the issue appears to be with TX offloading.
Here’s an example:
# The primary network interface auto eth0 iface eth0 inet static address 192.168.1.5 netmask 255.255.255.0 network 192.168.1.0 broadcast 192.168.1.255 gateway 192.168.1.1 offload-tx off
This can also be done non-persistently with the following ethtool command:
ethtool -K eth0 tx off
Additional Support
The comments section right here is the best place for support. The second best place is the GitHub issues section.
I will add additional documentation based on what problems people are running into / questions people are asking because right now I’m not really sure what those will be yet. Definitely let me know if you need any of these things!
Hey!
This is a great container. I’ve installed it on pi5 8gb on nvme with ubuntu and it runs smoothly for even 10+ players.
However I have found an issue which is very annoying. Mainly if someone connects from ps5 minecraft – there is no problem but when this ps5 tries to enable split screen the game crashes… (Not the server but the game on ps5) There is a message saying that some invalid packet was found. It is occuring at the stock configuration of the server. Has anyone had this issue? Or has anyone a sollution to it?
Regards 🙂
Hello Blevar,
It seems to be a common PS5 specific issue in Minecraft. The best test (if you haven’t already) is to try running a vanilla Bedrock server temporarily and see if it crashes on it still. If it does it’s definitely specific to the PS5 build of Minecraft.
Hopefully that helps!
Do the environment variable mappings support things like setting the seed, mode, etc.?
Here’s my docker compose Services entry:
minecraft-java-creative:
container_name: minecraft-java-creative
image: 05jchambers/legendary-minecraft-geyser-floodgate:latest
tty: true
entrypoint: [ "/bin/bash", "/scripts/start.sh" ]
stdin_open: true
ports:
- 25566:25565
- 19136:19132/udp
- 19136:19132
- 19137:19133/udp
- 2226:2222
environment:
PUID: 1000
PGID: 1000
PORT: "25565"
BEDROCKPORT: "19132"
TZ: America/Los_Angeles
EULA: true
Level: "JavaCreative"
MODE: creative
FORCE_GAMEMODE: true
DIFFICULTY: normal
VIEW_DISTANCE: 16
MEMORY: 32G
SEED: "-698247204184653391"
ALLOW_CHEATS: true
ENABLE_SSH: true
volumes:
- minecraft-java-creative-volume:/minecraft
The seed doesn’t seem to be taking effect, nor is the MODE, nor do the PUID/PGID values. Are these not supported?
Hey David,
Oh I see what you did there! So while it would be possible to add a way to pass those variables onto the server the way it works right now you would just go and edit the config files after creating the server.
What I would recommend doing is first start up the server with just default settings. Next go ahead and close it down and then go into your Docker volume files and make the changes to either server.properties or the .yml config files for Paper.
After editing the seed I would remove your “world” folder (as well as world_nether and world_the_end if they are there). The reason for that is that when you started the server for the first time it generates the spawn area with the old seed. If you remove the world folder after setting these options it will force it to regenerate everything (including the spawn) using your new seed.
Hopefully that helps!
Hey and thanks for this setup. Im gonna build a server for my kids with lots of plugins.
But im kinda new to coding and commands etc. Do you have a list of commands to control the server, and when i reboot the server, does it automaticly starts?
Hey Tommy,
The best place to start for the commands is here. You can also use /help inside of the game once you’ve given yourself admin rights. To do that type op yourname in the server console.
Hopefully that helps!
Hi James,
Happy to report that things have been fantastic with this for us! I ended up creating an entirely new world when I did some work on the physical server it’s running on by adding in a whole host of new SSD’s into a RAID format, and managed to completely forget to backup our world (oops!). Anyways, I recently started getting this notification when starting up the server after a reboot, curious if there’s something extra I need to do?
*** Warning, you’ve not updated in a while! ***
*** Please download a new build as per instructions from https://papermc.io/downloads/paper **
Shows Java 19 under that line. Just wondering if this could be a similar issue to a while back when Geyser had changed some things and basically broke your script. Is it safe to manually update? Just don’t want to break to neat world we’ve been building!
Hey Arathi,
I’ve released updates that will safely take you to OpenJDK 21 here. I would recommend updating to the latest version and it should take care of this!
James – I am trying to install WorldEdit and is appears to need JDK 21. I just pulled your latest and did a restart, but it still seem to be using JDK 19.
Hey CardinalFang,
Can you do a:
docker image prune
and then answer yes to remove dangling images
then do a:
docker image ls
This will give you the image ID (look for 05jchambers) and then do a:
docker image rm xxxx
to remove any copies of the image cached on your device
Now try running again to make sure you’re pulling the latest images!
BTW: Welcome back! You have been sorely missed.
docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
05jchambers/legendary-minecraft-geyser-floodgate latest 4bb1bc424280 5 hours ago 497MB
05jchambers/legendary-minecraft-geyser-floodgate 24cdba30dc07 5 months ago 531MB
hello-world latest ee301c921b8a 12 months ago 9.14kB
docker image rm 24cdba30dc07
Error response from daemon: conflict: unable to delete 24cdba30dc07 (must be forced) - image is being used by stopped container 0426a729edaf
I had to force removal (rm -f) and then remove the priort container (docker containter rm
It now appears to be using the updated image. Thanks!
Glad to be back and very glad it’s working, take care!
Hi James,
in history you post “Updated default version to 1.20.5” (incl. new Java-Version). What I have to do, to change my existing server to the new version?
Tried to delete all containers and image. Create a new one (with different name). Do “sudo docker pull 05jchambers/legendary-minecraft-geyser-floodgate:latest”.
With command:
sudo docker run -it -v mcs:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 -e BackupCount=1 -e TZ=”Europe/Berlin” –restart unless-stopped 05jchambers/legendary-minecraft-geyser-floodgate:latest
always starts 1.20.4 furthermore
With command:
sudo docker run -it -v mcs:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 -e Version=1.20.5 -e BackupCount=1 -e TZ=”Europe/Berlin” –restart unless-stopped 05jchambers/legendary-minecraft-geyser-floodgate:latest
it ends in an error:
Downloading mojang_1.20.5.jar
Applying patches
Starting org.bukkit.craftbukkit.Main
Exception in thread "ServerMain" java.lang.UnsupportedClassVersionError: org/bukkit/craftbukkit/Main has been compiled by a more recent version of the Java Runtime (class file version 65.0), this version of the Java Runtime only recognizes class file versions up to 63.0
at java.base/java.lang.ClassLoader.defineClass1(Native Method)
at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1013)
at java.base/java.security.SecureClassLoader.defineClass(SecureClassLoader.java:150)
at java.base/java.net.URLClassLoader.defineClass(URLClassLoader.java:524)
at java.base/java.net.URLClassLoader$1.run(URLClassLoader.java:427)
at java.base/java.net.URLClassLoader$1.run(URLClassLoader.java:421)
at java.base/java.security.AccessController.doPrivileged(AccessController.java:712)
at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:420)
at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:588)
at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:521)
at java.base/java.lang.Class.forName0(Native Method)
at java.base/java.lang.Class.forName(Class.java:495)
at java.base/java.lang.Class.forName(Class.java:474)
at io.papermc.paperclip.Paperclip.lambda$main$0(Paperclip.java:38)
at java.base/java.lang.Thread.run(Thread.java:1589)
What am I doing wrong?
Frank
Hey Frank,
It looks like Paper never released a version for 1.20.5. That’s my fault for assuming they would.
They are however doing 1.20.6 and I’ve just released the latest version which should pull those.
Hopefully that helps!
Hey James,
I’ve been using your container for months now with my kids so they can play on their tablets and I can host on my Ras Pi 4. Thanks so much for putting this together.
Do those pull requests on the GitHub repo for the Java 21 issue look okay? I might just try working around it myself locally if it’s as easy as just telling the image to get Java 21 during the docker build.
Thanks again!
Hey John,
Sorry for being slow updating these. I hadn’t checked the pull requests but I did update everything. Can you try with the latest version or if you’ve already got it working that is excellent!
Hi James,
How can I get MC 1.20.6 to use openjdk 21 vs. 19?
I have java 21 installed, but get the java UnsupportedClassVersionError error in craftbukkit as though it doesn’t see the newer version.
Thanks!
Larry
Hey Larry,
Go ahead and try with the latest version which has upgraded to OpenJDK 21!