Docker Minecraft Purpur Geyser Server

Minecraft Geyser + Floodgate Purpur Minecraft Server
Minecraft Geyser + Floodgate Purpur Minecraft Server

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. This is the Purpur version. It uses the Geyser and Floodgate plugins to accomplish this.

Since it uses the Purpur Minecraft server it also supports any additional plugins that are compatible with Purpur / 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 (as well as the Geyser + Floodgate version) and you can swap between these 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.


  • Sets up fully operational Minecraft server that allows both Java and Bedrock clients to connect
  • Runs the highly efficient “Purpur” 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 Purpur / 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


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-purpur-geyser: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-purpur-geyser:latest

With a custom Minecraft version (add -e Version=1.X.X, must be present on Purpur’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-purpur-geyser: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-purpur-geyser: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-purpur-geyser

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-purpur-geyser: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-purpur-geyser: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:


On Windows it’s at


but may be located at something more like


if you are using WSL (Windows Subsystem for Linux).

On Mac it’s typically


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.

File Locations

Most people will want to edit 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 Purpur / Paper / Spigot / Bukkit

This is a “Purpur” Minecraft server which has plugin compatibility with Purpur / 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:

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. A 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
offload-tx off

This can also be done non-persistently with the following ethtool command:

ethtool -K eth0 tx off

Buy A Coffee / Donate

People have expressed some interest in this (you are all saints, thank you, truly)

  • PayPal:
  • Venmo: @JamesAChambers
  • CashApp: $theremote
  • Bitcoin (BTC): 3H6wkPnL1Kvne7dJQS8h7wB4vndB9KxZP7

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!

Notify of

Inline Feedbacks
View all comments
1 year ago

James I love your guides, thank you really for your time and the support you give. I was wondering – is it possible to run two or three MineCraft server containers at the same time on the RPI? I like to play different worlds with my son (Survive/Creative) and this setup would be hillarious. Thank you.

Marijn Sijbers
Marijn Sijbers
1 year ago

Just donated a small cuppa coffee. Thanks for creating thus guide and all the support you provide.

1 year ago

This is a great container, really useful for my wife and I to play. I like playing on the mac and she likes the xbox, it works great as a local lan server for that btw! I am trying to docker exec into it but its failing through portainer. What is the best method to do this or to access the minecraft console?

1 year ago

thanks yeah helps a bunch. and again really great containers!

Caleb Rector
Caleb Rector
1 year ago

Appreciate your work on this! I have a server up and going it worked well for a couple of weeks and now I get an error when trying to connect with bedrock clients. Any idea what might be causing the error? Unable to inflate buffer data sounds like it could be permissions related? I have restarted the container but not the server. Java clients connect fine.

[17:03:28] [Network Listener - #1/INFO]: [Geyser-Spigot] / tried to connect!
[17:03:28] [Network Listener - #0/WARN]: [io.netty.util.concurrent.AbstractEventExecutor] A task raised an exception. Task: com.nukkitx.protocol.bedrock.BedrockRakNetSessionListener$$Lambda$6020/0x0000000801d76ab8@2b2758df
java.lang.RuntimeException: Unable to inflate buffer data
at com.nukkitx.protocol.bedrock.wrapper.BedrockWrapperSerializerV9_10.deserialize( ~[Geyser-Spigot.jar:?]
at com.nukkitx.protocol.bedrock.BedrockSession.onWrappedPacket( ~[Geyser-Spigot.jar:?]
at com.nukkitx.protocol.bedrock.BedrockRakNetSessionListener.lambda$onEncapsulated$0( ~[Geyser-Spigot.jar:?]
at io.netty.util.concurrent.AbstractEventExecutor.runTask( ~[netty-common-4.1.77.Final.jar:4.1.77.Final]
at io.netty.util.concurrent.AbstractEventExecutor.safeExecute( ~[netty-common-4.1.77.Final.jar:4.1.77.Final]
at io.netty.util.concurrent.SingleThreadEventExecutor.runAllTasks( ~[netty-common-4.1.77.Final.jar:4.1.77.Final]
at ~[netty-transport-classes-epoll-4.1.77.Final.jar:4.1.77.Final]
at io.netty.util.concurrent.SingleThreadEventExecutor$ ~[netty-common-4.1.77.Final.jar:4.1.77.Final]
at io.netty.util.internal.ThreadExecutorMap$ ~[netty-common-4.1.77.Final.jar:4.1.77.Final]
at Source) ~[?:?]
Caused by: incorrect header check
at Method) ~[?:?]
at Source) ~[?:?]
at com.nukkitx.natives.zlib.Java11Inflater.inflate( ~[Geyser-Spigot.jar:?]
at com.nukkitx.protocol.util.Zlib.inflate( ~[Geyser-Spigot.jar:?]
at com.nukkitx.protocol.bedrock.wrapper.BedrockWrapperSerializerV9_10.deserialize( ~[Geyser-Spigot.jar:?]
... 9 more

Caleb Rector
Caleb Rector
1 year ago

Thanks James, No beta client, the client trying to connect is an gen 7 ipad, iphone 12, kendal fire (not sure of version) and a windows 10 ryzen 5 5600g. Since this was encountered I have not been able to get a bedrock device to connect to the server.

Caleb Rector
Caleb Rector
1 year ago

Appreciate the help James! I tracked it down to a DNS issue, devices off my network could connect to the server but internal to my network it was broken. It was odd because it was getting to the server but MC did not allowing the connection. Removed the domain portion of the hostname internal to my network and it is now working.

Larry Irwin
Larry Irwin
1 year ago

I’m new to docker, but this was fairly simple to get up and running. The Java clients can get in now, but the Bedrock clients aren’t able to for some reason and I’m not sure how to debug it. Their login attempts never appear in the “docker logs -f mcdock” output. The container is running under Ubuntu 22.04.1 LTS on VMWare 6.7 on a Dell R720. Could VMWare 6.7 have UDP issues like Hyper-V?

Larry Irwin
Larry Irwin
1 year ago

Well it appears that it’s working just fine… The problem was all the complicated, round-robin Microsoft auth procedures. We can now get to the server from any client!
(Since I just brought this server instance up for my LAMP applications, I hadn’t set up ufw yet…)

Rob Rogers
Rob Rogers
1 year ago

I’ve been using your excellent Bedrock setup script (“Minecraft Bedrock Edition – Ubuntu Dedicated Server Guide”) and have written some scripts to manage my servers. They use commands like “screen -Rd $1 -X stuff “whitelist add \”$2\”$(printf ‘\r’)”” to execute single Minecraft server commands from outside of the server console. With this Docker/Java setup, is there any way to do the same sort of thing from “outside” of the Docker container, “reaching through” to execute commands on a running server? Some incantation of “docker attach”, perhaps?


Rob Rogers
Rob Rogers
1 year ago

Thanks! Docker certainly has some advantages when dealing with something with multiple moving parts (JVM, server, etc.).

1 year ago

I would offer a better open source suggestion to VScode.

It make look familiar. 😉

Rob Rogers
Rob Rogers
9 months ago

After your helpful answer this sort of thing worked fine: docker exec -it $1 screen -Rd -X stuff “say $2.$(printf ‘\r’)” (that sends a message to the players). However I recently updated the image and screen is no longer part of it. I added it manually (exec’d a shell and used apt-get on the running container), but now whenever I try it I get a “No screen session found” error.

Any help appreciated, thanks.

Rob Rogers
Rob Rogers
9 months ago

Thanks! The main reason I started on the screens route was to support curfews for my grandkids and their friends. A cron job kicks off a bash script that uses screens to broadcast a server message that curfew is coming, then kicks them off and uses the fwhitelist server command to block them till a morning cron job restores their access. (All this at the request of parents who knew there would be temptations to get up at some ungodly hour to play while the parents were asleep.). All this using a text file for the gamer ID’s. It’s an approach I used with your non-Docker Bedrock server setup, which has been great for us. I suppose I could just stop the server, edit the whitelist, and restart it (this may be an example of the obvious solution being overlooked for a “clever” solution :)).

Rob Rogers
Rob Rogers
9 months ago

Thanks again, I’ll look into that. One of the last projects I worked on before retiring in 2016 was setting up swarms of docker containers to test storage servers — I’ll have to dust off that part of my brain.

1 year ago

Silly question I just have the docker restarting with my NUC, how does one access the mc console the typical

docker exec -i rcon-cli

Do I need to enable that flag in my docker-compose. Yml (currently testing with your default example) Thanks for your time and putting this together. Cheers.

1 year ago

Awesome, appreciate it. That did the trick. <3 Thank you

1 year ago

One last thing to possibly integrate into your image or docker compose is mc-router, which basically routes you to the proper mc server by sub domain or instance name. All while using the default ports. Could be tricky seeing this is also includes the bedrock ports. Just thought I’d mention it.

1 2 3 4