This is a containerized version of my Paper Minecraft Java server. The image works great on all Docker platforms including Raspberry Pi!
There is also a version that has Geyser + Floodgate installed which will let Minecraft Bedrock players connect to your Java server!
The official GitHub repository is located here.
The official Docker Hub repository is located here.
The Minecraft Bedrock version of the container is located here. This is for the Java version.
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 in less than a couple of minutes
- Runs the highly efficient “Paper” Minecraft 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 port:
docker run -it -v yourvolumename:/minecraft -p 25565:25565 --restart unless-stopped 05jchambers/legendary-java-minecraft-paper:latest
With custom port:
docker run -it -v yourvolumename:/minecraft -p 12345:12345 -e Port=12345 --restart unless-stopped 05jchambers/legendary-java-minecraft-paper: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 -e Version=1.17.1 --restart unless-stopped 05jchambers/legendary-java-minecraft-paper: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 -e MaxMemory=2048 --restart unless-stopped 05jchambers/legendary-java-minecraft-paper:latest
Using a different timezone:
docker run -it -v yourvolumename:/minecraft -p 25565:25565 -e TZ="America/Denver" --restart unless-stopped 05jchambers/legendary-java-minecraft-paper:latest
Skipping backups on a certain folder:
docker run -it -v yourvolumename:/minecraft -p 25565:25565 -e NoBackup="plugins" --restart unless-stopped 05jchambers/legendary-java-minecraft-paper:latest
Skipping permissions check:
docker run -it -v yourvolumename:/minecraft -p 25565:25565 -e NoPermCheck="Y" --restart unless-stopped 05jchambers/legendary-java-minecraft-paper: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!
I love your software! It is so convenient and trustworthy. I hope you will consider making a Fabric + Lithium version. Sodium client mod is great and gets you hundreds of FPS, but only works with Fabric. I have been using the Fabulously Optimized modpack, which includes Sodium, full controller support, and many other vanilla improvements. It is really good and I would love to use it client side on your server software.
James,
I use your old standalone scripts. How do I move my existing world to the docker container?
Tom
Hey CardinalFang,
It’s pretty easy. You would just move your files to the Docker data folder (described in the guide). If you start the server once and you go in the data folder you’ll recognize all of the files. You can copy them into there.
Hopefully that helps!
Thanks. I reread the guide and figured that out.
Hello, this is great! I thought I read somewhere on here there was a way to “fix” my Bedrock users that weren’t showing their proper skins/clothes, but now that I have the server up and running I can’t find the comment that explained the process to resolve this. Can you point me to that?
I can’t thank you enough for all the work you have done on this project!
Is there a way to access the command line within docker to set an OP like in your non-docker Pi version?
Hey Doug,
Great question! So the answer is that yes you can access the CLI in the same way as the standalone version. It’s just a slightly different looking command. The way we do it is:
docker container ls
docker container attach xxxx
Basically the first command will give you a Docker container ID to attach to (will look something like c37dbe1875da). Simply put that string into the second command in place of xxxx and it will attach you to the CLI where you can op normally.
Hopefully that helps!
Hey James! Thanks for your help when I found your guide on running the server without docker. I have since set up docker and it is so smooth and easy, its amazing!
However, I am running into an issue that may be out of the scope of this blog, but I figured I would ask.
I imported an existing MC world and it runs smooth as can be in the already explored areas. I decided to test and started going in a straight line until the entire Pi hung and had to be power cycled, not entirely unexpected due to world generation.
Okay, so I tried running chunky on the Pi to pre-gen the world. This also would eventually hang the Pi and require a power cycle.
Okay again, so this time I copy the world file to my desktop, run chunky on it there to pre-gen an 8GB world file and then move it back to the Pi.
World loads up fine and looks great. I grab a horse to test it and, sure enough, the Pi hangs and requires a reboot. This is pretty frustrating, as I am not sure what is putting the Pi under such heavy load if it is not having to generate new chunks?
I know the chunk data is there, the world folder is 8GB and the server takes a long time to boot up and I can watch it load through each chunk file in the folder.
The logs around the event are below. I removed any personal info from it. as you can see, the last thing in the log is me taming a horse, not even a disconnect or shut down message:
[16:43:28] [ServerMain/INFO]: Environment: authHost='https://authserver.mojang.com', accountsHost='https://api.mojang.com', sessionHost='https://sessionserver.mojang.com', servicesHost='https://api.minecraftservices.com', name='PROD'
[16:43:36] [ServerMain/INFO]: Loaded 7 recipes
[16:43:40] [Server thread/INFO]: Starting minecraft server version 1.19.4
[16:43:40] [Server thread/INFO]: Loading properties
[16:43:41] [Server thread/INFO]: This server is running Paper version git-Paper-478 (MC: 1.19.4) (Implementing API version 1.19.4-R0.1-SNAPSHOT) (Git: 32875b4)
[16:43:41] [Server thread/INFO]: Using 4 threads for Netty based IO
[16:43:41] [Server thread/INFO]: Server Ping Player Sample Count: 12
[16:43:42] [Server thread/WARN]: [!] The timings system has been enabled but has been scheduled for removal from Paper in the future.
We recommend installing the spark profiler as a replacement: https://spark.lucko.me/
For more information please visit: https://github.com/PaperMC/Paper/issues/8948
[16:43:42] [Server thread/INFO]: [ChunkTaskScheduler] Chunk system is using 1 I/O threads, 1 worker threads, and gen parallelism of 1 threads
[16:43:43] [Server thread/INFO]: Default game type: SURVIVAL
[16:43:43] [Server thread/INFO]: Generating keypair
[16:43:44] [Server thread/INFO]: Starting Minecraft server on *:25565
[16:43:44] [Server thread/INFO]: Using default channel type
[16:43:44] [Server thread/INFO]: Paper: Using Java compression from Velocity.
[16:43:44] [Server thread/INFO]: Paper: Using Java cipher from Velocity.
[16:43:46] [Server thread/INFO]: [Chunky] Loading server plugin Chunky v1.3.52
[16:43:46] [Server thread/INFO]: Server permissions file permissions.yml is empty, ignoring it
[16:43:46] [Server thread/INFO]: Preparing level "world"
[16:43:48] [Server thread/INFO]: Preparing start region for dimension minecraft:overworld
[16:43:49] [Server thread/INFO]: Time elapsed: 555 ms
[16:43:49] [Server thread/INFO]: Preparing start region for dimension minecraft:the_nether
[16:43:49] [Server thread/INFO]: Time elapsed: 375 ms
[16:43:49] [Server thread/INFO]: Preparing start region for dimension minecraft:the_end
[16:43:49] [Server thread/INFO]: Time elapsed: 304 ms
[16:43:49] [Server thread/INFO]: [Chunky] Enabling Chunky v1.3.52
[16:43:50] [Server thread/INFO]: Running delayed init tasks
[16:43:50] [Server thread/INFO]: Done (9.860s)! For help, type "help"
[16:43:50] [Server thread/INFO]: Timings Reset
[16:43:58] [User Authenticator #0/INFO]: UUID of player RareCandyMan is 977dbb6d-c6a4-4699-bc9f-adb534e4cd7f
[16:43:59] [Server thread/INFO]: joined the game
[16:43:59] [Server thread/INFO]: logged in with entity id 4 at ([world]207.48553037115428, 104.73746753185165, -17.165722162258472)
[16:44:33] [Server thread/WARN]: moved too quickly! -17.0426345920295,0.0,-8.495665022755297
[16:44:47] [Server thread/INFO]: issued server command: /gamemode survival
[16:44:47] [Server thread/INFO]: Set own game mode to Survival Mode]
[16:46:36] [Server thread/INFO]: lost connection: Disconnected
[16:46:36] [Server thread/INFO]: left the game
[06:53:06] [User Authenticator #1/INFO]: UUID of player
[06:53:06] [Server thread/INFO]: joined the game
[06:53:06] [Server thread/INFO]: logged in with entity id 586 at ([world]60.85719873182293, 76.0, -95.33661656723741)
[07:00:23] [Server thread/INFO]: has made the advancement [The Parrots and the Bats]
[07:26:34] [Server thread/INFO]: has made the advancement [Sweet Dreams]
[07:27:40] [Server thread/INFO]: has made the advancement [Take Aim]
[08:01:35] [Server thread/INFO]: was slain by Iron Golem
[08:11:43] [Server thread/INFO]: has made the advancement [A Seedy Place]
[08:20:19] [Server thread/INFO]: has made the advancement [Best Friends Forever]
Hey Andrew,
Thanks so much for your kind words about the guide! Thanks for sharing your log file as well. This is a really interesting case. It doesn’t look like the server is crashing.
I think this is a different problem. This looks like a hardware issue. What are the temperatures getting to on the Pi? Do you have those little heat sinks installed?
If you search for Docker containers freezing on the Raspberry Pi you will find a lot of results. There’s some good suggestions in there:
/opt/vc/bin/vcgencmd measure temp
/opt/vc/bin/vcgencmd get_throttled
The temperature is pretty straightforward. The get_throttled should give you 0x0 if the device isn’t being throttled.
The other issue could be RAM. What is the RAM size of this Pi? If it’s a 1GB one then you’ll probably want to limit the memory usage. If you’re running out of memory then that can cause hard lockups like this.
It’s also pretty common for something like this to turn out to be a bad SD card. If you are using a SSD this probably isn’t likely unless the SSD might not be getting enough power. Bad power supplies (or ones that are too small) have been the cause before as well.
You may want to try adding the MaxMemory switch to the startup like this:
-e MaxMemory=600
You may have to experiment with different amounts. If lowering the memory stops it then the issue is simply that Linux doesn’t have enough RAM on that Pi to keep functioning properly.
Those are a couple things to start with at least, hopefully that helps!