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!
Is there a way with the docker container for it to recognize the PUID and GUID settings? It just seems to run as root no matter what I do.
Also what is the server.properties setting that I need to enable or mark true so that when I type a “cheat code” like “gamemode @a….” to set my kids in creative mode for a while to have fun. I cannot see to get that working. I set the server.properties enable-command-block=true but that did not help (which is hard when root owns the file and the container is up hence my first question).
Appreciate any help… really like the ability to use both clients and all the work… it will be a blast for the kids as my current is a bland Bedrock they play on.
Hey Jeffrey,
The server is running as root *inside the container*. That’s not the same as running on root on your system. The container is completely isolated from the rest of your system and that is the point.
If you’re trying to use PUID / GUID settings you are defeating the point of the design of the container. The whole design is that it’s separate and isolated. It should *not* be able to interact with your real system’s PUID and GUID settings.
If you want to integrate the server with your system you should use the standalone version instead. You can do whatever you want with permissions / GUIDs / PUIDs / etc. The whole point of this container is that it does *not* interact with your system at all and it is completely isolated.
In other words the server is running as root in it’s own fake isolated Ubuntu container. That’s why you get the startup warning about it running as root. It’s because the Bedrock server is way, way too stupid to know it’s running inside a Docker container. It doesn’t know and that’s why it’s warning you. If your server got hacked they would have access to a fake Ubuntu operating system that lives in memory and will be completely wiped out when the container is restarted.
Remember, the whole point of Docker is that it’s *not* using your operating system or the real root account. It’s not even using a user account. It’s a completely isolated and independent system that cannot impact your main system. It’s way more secure than running it with a standard user account on your real operating system.
If you went to the standalone version you would get rid of that root warning message and you’d be far less secure because if you got hacked they would have access to everything on the server that your user account does. If this container gets hacked? They’ll be very confused honestly when none of their changes they make to the fake system in memory can even survive restarting the server (they aren’t written to disk anywhere, it’s not real, it’s just in RAM and everything any attacker did would be lost after restarting the container).
As far as the console commands all of them work just by typing them in the console. If you want to use them in game you need to op yourself first with op yourplayername.
Hopefully that helps!
Thank you for the response…. I understand docker and the entire reason for why it is how it is. All I was hoping for was a way to make it run under the PUID/GUID I use for most everything else because I have Code-Server setup on my headless linux docker host to edit all my yaml files. This running as root means I have to stop the container to edit anything, edit the file, the restart the container. I know for changes to take affect you have to restart it anyways but I cannot even drop jar files into the folder structure because it has it locked down. Anyways….
Thanks for the lead on the op-permission-level in the server.properties. I stopped the server, changed it to 2, and restarted. The / menu has no op option for me to make myself an operator so I guess I need to google how to do that next. Sorry I am a Windows and Linux Virtualization and Engineer for a living so the docker, server, etc is all not a problem and i enjoy playing the game with the kids, but getting the server setup for them I am ca complete newbie at this….
Appreciate the help!
So is this error going to prevent me from being able to get to the server command-line environment and make myself or a kid an operator? This is the in the log at startup of the container.
ServerMain WARN Advanced terminal features are not available in this environment
Hey Jeffrey,
You’re missing the necessary flags in your config file. Please see the example documentation here.
Terminal features not enabled? That would be:
stdin_open: true # docker run -i
tty: true # docker run -t
You’re going to want to use all of the flags I use in the documentation whether you understand them or not. They’re there because they are needed. Docker does not enable the advanced terminal features by default.
I understand what you want to do with the permissions and PUID/GUID. I knew from your first post. You’re not the first one to try and and it’s specifically designed not to work that way.
Use the standalone version if you want to do this as it’s not secured in a way that will prevent you from trying to make the permissions more convenient to use at the cost of your security. This is the isolated version. If you want to un-isolate it you would need to fork it for sure.
Hopefully that helps!
Thank you…. this got me closer…. updated my compose yml and this got rid of the warning…. I had not seen your example docker-compose.yml which is my fault as I poked around the github for a while looking for one and should have found it. I get the PUID/GUID thing and have a simple worked around I can use to stop the container when and if I want to make an change to something so it not a huge deal.
Thanks again…. now how do I access the terminal…. i tried a browser over both ports (which I didnt see published in the logs but thought I would try)…. I tried doing a docker exec -i rcon-cli….. i see in the server.properties the rcon is mapped to the 25565 but not picking that up for some reason…. sorry to be such a needy newb… i really have been looking around the github and google for several hours before responding with this question and tried a lot of things.
In case this helps this is my compose:
#
# Minecraft - Minecraft+Geyser+Floodgate+Paper
#
minecraft-geyser:
container_name: minecraft-geyser
image: 05jchambers/legendary-minecraft-geyser-floodgate:latest
environment:
#- PUID=${PUID}
#- PGID=${PGID}
- TZ=${TZ}
- Port="25565"
- BedrockPort="19132"
- BackupCount=10
stdin_open: true # docker run -i
tty: true # docker run -t
entrypoint: [ "/bin/bash", "/scripts/start.sh" ]
volumes:
- ${USERDIR}/media/minecraft-geyser:/minecraft
ports:
- 25565:25565
- 19142:19132/udp
- 19142:19132
restart: unless-stopped
Hey Jeffrey,
To attach to the console just use:
docker container ls
docker attach xxxx
Then you can just type directly into the console!
Hey James! Thanks again for your hard work maintaining this. I have been using your docker implementation without issues for a while now. I have to apologize in advance that my Linux experience is almost entirely self taught through playing with my Pi, so the following may be very dumb or obvious.
I was researching a process from /scripts/start.sh that is consistently my highest GPU using process, almost constantly more than the actual java process. Is it normal operation for /scripts/start.sh to have higher CPU usage as the java process?
Ah, I noticed that I typo’d CPU to GPU in the above, but I don’t see a way to edit it. Apologies! To clarify, I was only looking at CPU performance in all instances.
Hey Andrew,
Great question! So the end of start.sh looks like this:
# Start server
echo "Starting Minecraft server..."
if [[ -z "$MaxMemory" ]] || [[ "$MaxMemory" -le 0 ]]; then
exec java --add-modules=jdk.incubator.vector -XX:+UnlockDiagnosticVMOptions -XX:-UseAESCTRIntrinsics -DPaper.IgnoreJavaVersion=true -Xms400M -jar /minecraft/purpur.jar
else
exec java --add-modules=jdk.incubator.vector -XX:+UnlockDiagnosticVMOptions -XX:-UseAESCTRIntrinsics -DPaper.IgnoreJavaVersion=true -Xms400M -Xmx${MaxMemory}M -jar /minecraft/purpur.jar
fi
# Exit container
exit 0
Notice here that Java runs before start.sh finishes. That’s because when it starts that Java line start.sh will pause on it until Java terminates.
The very last line of exit 0 will close the entire container. That basically won’t happen until Java is closed. Basically Java is a child process of start.sh so start.sh will always have been running slightly longer. Depending on what task manager you are using this will look different. Some of the fancier ones will show that Java is a child process of start.sh and others will just show start.sh as having more CPU cycles ran.
Hopefully that helps!
Thank you so much!
Is there a reason for this to show upu in the console logs? It looks like an attempt at login with no id from an Oracle ip address… And it happens about once per hour… (I even added the ip to banned-ips and it still appears)
[07:48:46] [Server thread/INFO]: /192.9.244.59:36102 lost connection: Internal Exception: io.netty.handler.codec.DecoderException: java.lang.IndexOutOfBoundsException: readerIndex(16) + length(8) exceeds writerIndex(16): PooledUnsafeDirectByteBuf(ridx: 16, widx: 16, cap: 256)
Hey Larry,
If you google that error it’s almost always mod related. Specifically it’s when you’re running plugins that are for versions older than 1.19 and haven’t been updated. Do you have any mods installed?
Hi James,
Currently trying to use a Synology NAS with Portainer to host the minecraft server. Was previously using https://docker-minecraft-server.readthedocs.io/en/latest/ which uses Docker Compose to start a container (works just fine). Using your image, however, the stack successfully deploys but It gives me an (ERROR: A named volume was not specified for the Minecraft server data). Looking through the container information, I can see that the volume has already been mapped though. Kinda a noob here and couldn’t figure out what I might have done wrong. Do you have any idea what I might have done wrongly?
This is my docker-compose code:
services:
minecraft:
image: 05jchambers/legendary-minecraft-geyser-floodgate:latest
container_name: minecraftbedrockjava
environment:
– MaxMemory=3G
– TZ=Singapore
volumes:
– /volume1/docker/minecraft:/data
network_mode: host
restart: always
Hey Darius,
Take a look at the example docker-compose.yml file:
version: "3.5"
services:
minecraftbe:
image: 05jchambers/legendary-minecraft-purpur-geyser:latest
restart: "unless-stopped"
ports:
- 25565:25565
- 19132:19132
- 19132:19132/udp
volumes:
- minecraft:/minecraft
stdin_open: true # docker run -i
tty: true # docker run -t
entrypoint: [ "/bin/bash", "/scripts/start.sh" ]
# Environment variables
environment:
Port: "25565"
BedrockPort: "19132"
TZ: "America/Denver" # timezone
#BackupCount: 10 # Number of backups the server keeps
#MaxMemory: 2048 # Maximum memory usage for Java
#Version: 1.19.3 # Use custom version
#NoBackup: "plugins" # Optional folder to skip during backups
#NoPermCheck: "Y" # Optional flag to skip permissions check
#NoViaVersion: "Y" # Optional flag to disable ViaVersion plugin
#QuietCurl: "Y" # Optional flag to reduce curl log output by suppressing progress meter
volumes:
minecraft:
driver: local
Notice the way you are mounting the volume:
– /volume1/docker/minecraft:/data
There is no “data” folder used by this script. Try using my example docker-compose or if you want to fix yours specify the correct volume mountpoint like this:
– /volume1/docker/minecraft:/minecraft
Hopefully that helps!
Hi James,
I’m a Bedrock player, and have a three-player Bedrock Realm that I was thinking of downloading locally and running on my Raspberry Pi 4 (8GB)
Which version do you think would perform better on Pi? Your Bedrock Docker Server or this Java+Bedrock server?
Thanks in advance for any insight you can give
Hey AnthonyKellyYip,
I’d definitely recommend this version instead. It will give you a lot more flexibility and you have plenty of memory available.
Hopefully that helps!
Thanks for the reply. I’ll try this version then. Do I need to append anything to the commands for it to run on ARM64? I’m very new to Docker and fairly new to Raspberry Pi, so I’m reading Docker guides and stumbing my way through this as I go
Please ignore that arm64 question… I’m good 😂
I’m sure I’ll be back with more questions later
Hey AnthonyKellyYip,
I’m glad you got it going, definitely don’t hesitate to stop by with more questions if they come up!
Hey James,
Non minecraft related but “this” webpage related question: Did we lose the option to search within the comments section?
I was using it a lot to find answers to some of the problems i could find (most of the time the problem was discussed already)
I cannot find the search box anymore
Hey Elborderas,
Yes, I haven’t renewed the license for that yet. I’ll definitely investigate getting that turned back on again. Thanks for letting me know you found it useful!
Hello James, everything is working smoothly.
If I start the server, I‘ve got the message:“… updating to the most recent paperclip version. Latest paperclip found :196 and it is downloading everytime at startup.“
Pulling the newest version, I get the message:“It‘s already the newest.“
Can you help or explain this contradiction and is it bad for joining the server?
Best regards
Hey Michael,
I just updated the container last night. Can you try pulling the latest again?
Hey James,
Just for understanding: I stopped the container, then I entered „ docker pull 05jchambers/legendary-minecraft-geyser-floodgate:latest“ and after pulling the newest version I restarted the container – this steps are right?
In the log file is written the same as before pulling „downloading newest paperclip version (about 10.2 mb)“
Hey James,
Maybe you could help again. In the Docker-Log-FIle I still get the following message *** Warning, you’ve not updated in a while! *** Please download a new build as per instructions from https://papermc.io/downloads/paper *** I stopped the container and then entered the pull command. After that, I get the message that I have already downloaded the latest version. On the Paper page, the latest version is 1.20.2 (#238). However, this is version 1.20.2, so do I have to trigger the update manually and if so, what should the command be called if I have installed on an extra volume.
Best regards, MIchael
Hey Michael,
I’m guessing your external volume has permission issues and it’s failing to update. What are the permissions set to? Just try deleting the paperclip.jar so you have nothing installed on there and see if it can even redownload it. I doubt it by the sound of it.
Hopefully that helps!