Legendary Minecraft Java Paper Container- Minecraft Java Edition Paper Dedicated Server for Docker

This is the Docker containerized version of my Minecraft Java Paper Dedicated Server for Linux/Raspberry Pi scripts.

My main blog article (and the best place for support) is here.
The official GitHub repository is located here.
The official Docker Hub repository is located here.

The Bedrock version of the Docker container is available here. This is for Java Minecraft.

Features

• Sets up fully operational Minecraft server in less than a couple of minutes
• Runs the highly efficient "Paper" Minecraft server
• 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)
• Plugin support for Paper + Spigot + Bukkit
• Installs and configures OpenJDK 18
• Automatic backups to minecraft/backups when server restarts
• 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 (separate with a comma for multiple):

docker run -it -v yourvolumename:/minecraft -p 25565:25565 -e NoBackup="plugins/ftp,plugins/test" --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.
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

Plugins

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: https://dev.bukkit.org/bukkit-plugins

TZ (timezone) Environment Variable

You can change the timezone from the default "America/Denver" to own timezone using this environment variable:

docker run -it -v yourvolumename:/minecraft -e TZ="America/Denver" -p 25565:25565 05jchambers/legendary-java-minecraft-paper:latest

A list of Linux timezones is available here

BackupCount Environment Variable

By default the server keeps 10 rolling backups that occur each time the container restarts. You can override this using the BackupCount environment variable:

docker run -it -v yourvolumename:/minecraft -e BackupCount=20 -p 25565:25565 05jchambers/legendary-java-minecraft-paper:latest

QuietCurl Environment Variable

You can use the QuietCurl environment variable to suppress curl's download output. This will keep your logs tidier but may make it harder to diagnose if something is going wrong. If things are working well it's safe to enable this option and turn it back off so you can see the output if you need to:

docker run -it -v yourvolumename:/minecraft -p 25565:25565 -p 19132:19132/udp -p 19132:19132 -e QuietCurl=Y 05jchambers/legendary-java-minecraft-paper:latest

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.
The symptom you will have is that nobody will be able to connect.
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.

Here are some additional links:

• https://jamesachambers.com/official-minecraft-bedrock-dedicated-server-on-raspberry-pi/comment-page-8/#comment-13946
• https://jamesachambers.com/minecraft-bedrock-edition-ubuntu-dedicated-server-guide/comment-page-53/#comment-13936
• https://jamesachambers.com/minecraft-bedrock-edition-ubuntu-dedicated-server-guide/comment-page-49/#comment-13377
• https://jamesachambers.com/legendary-minecraft-bedrock-container/comment-page-2/#comment-13706

Troubleshooting Note - Hyper-V

There is a weird bug in Hyper-V that breaks UDP connections on the Minecraft server. There are two fixes for this. The simplest fix is that you have to use a Generation 1 VM with the Legacy LAN network driver.
See the following links:

• https://jamesachambers.com/minecraft-bedrock-edition-ubuntu-dedicated-server-guide/comment-page-54/#comment-13863
• https://jamesachambers.com/minecraft-bedrock-edition-ubuntu-dedicated-server-guide/comment-page-56/#comment-14207

There is a second fix that was shared by bpsimons here.
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

Buy A Coffee / Donate

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

• PayPal: [email protected]
• Venmo: @JamesAChambers
• CashApp: $theremote
• Bitcoin (BTC): 3H6wkPnL1Kvne7dJQS8h7wB4vndB9KxZP7

Update History

• June 29th 2024
• Updated default version to 1.21 (remember, you never need to wait for updates to change Minecraft versions, just use -e Version=1.21)
• May 19th 2024
• Updated default version to 1.20.6 (remember, you never need to wait for updates to change Minecraft versions, just use -e Version=1.20.6)
• Update OpenJDK version to 21
• December 13th 2023
• Updated default version to 1.20.4 (remember, you never need to wait for updates to change Minecraft versions, just use -e Version=1.20.4)
• September 30th 2023
• Updated default version to 1.20.2 (remember, you never need to wait for updates to change Minecraft versions, just use -e Version=1.20.2)
• June 9th 2023
• Updated default version to 1.20 (remember, you never need to wait for updates to change Minecraft versions, just use -e Version=1.20)
• March 25th 2023
• Migrate paper.yml to paper-global.yml
• March 16th 2023
• Update to 1.19.4 (make sure you have backups safely saved from your backups folder before upgrading as they are rotated)
• January 25th 2023
• Removed check for terminal and will let the Minecraft server throw an error if environment is not appropriate
• January 14th 2023
• Change connectivity test from google.com to papermc.io to prevent blocking in certain countries
• January 12th 2023
• Remove broken ScheduleRestart environment variable -- this needs to be done in your OS using docker restart (typically with crontab in Linux or Task Scheduler in Windows)
• December 7th 2022
• Update to 1.19.3
• November 19th 2022
• Add "QuietCurl" environment variable which will suppress the progress meter on curl keeping the logs much tidier
• Remove fixpermissions.sh and add 3 lines into main start.sh file
• November 7th 2022
• Fail immediately if ran without an interactive terminal (as the Minecraft server won't work without one)
• October 30th 2022
• Add RISC architecture support
• Switch from ubuntu:latest to ubuntu:rolling
• Switch from using Adoptium to using ubuntu:rolling OpenJDK
• Removed SetupMinecraft.sh
• Fix bug with new ScheduleRestart environment variable
• October 21st 2022
• Added new environment variable "BackupCount" to control the number of backups the container keeps
• NoBackup optional environment variable can now be multiple paths to files to skip backups on separated by a comma. Example: plugins/test,plugins/test2
• October 20th 2022
• Added new environment variable "NoBackup" to skip a folder from backup activities
• Added new environment variable "NoPermCheck" to skip permissions check during startup
• Added new environment variable "ScheduleRestart" -- this schedules the container to shut down at a certain time which combined with the --restart switch gives daily reboot functionality
• October 8th 2022
• Upgrade to OpenJDK 19
• September 27th 2022
• Fix SIGTERM catching in certain situations by running java with the "exec" command which passes execution completely to that process (thanks vp-en)
• Remove screen application
• September 20th 2022
• Update to OpenJDK 18.0.2.1
• August 29th 2022
• Add TZ environment variable to set timezone
• Add environment variables to docker-compose.yml template
• August 22nd 2022
• Add NoScreen environment variable -- disables screen which prevents needing an interactive terminal (but disables some logging)
• August 17th 2022
• Add XX:-UseAESCTRIntrinsics to java launch line to prevent encryption issue on 10th Gen Intel processors
• August 10th 2022
• Adjust query.port in server.properties to be the same as the main server port to keep the "ping port" working properly
• Add enforce-secure-profile=false to default server.properties to prevent login errors
• Add text editor inside the container (nano) for diagnostic/troubleshooting purposes
• August 6th 2022
• Update to 1.19.2
• July 31st 2022
• Upgrade Adoptium OpenJDK to 18.0.2
• July 27th 2022
• Update to 1.19.1
• July 13th 2022
• Update base Ubuntu image
• June 27th 2022
• Update base Ubuntu image
• June 15th 2022
• Fix 1.19 paperclip.jar upgrades
• June 11th 2022
• Update to Paper experimental 1.19 release as default installation
• Make sure you have backups of your server from your "backups" folder stored separately before upgrading
• If you have problems with 1.19 you need to restore a backup to go back to 1.18 as it will not take your server data files on 1.18 once the 1.19 structures/data have been added
• June 7th 2022
• Add docker-compose.yml file for use with Docker Compose
• May 25th 2022
• Updated documentation (additional packages no longer required and a base Docker install will work)
• May 21st 2022
• Added multiarch support with separate images for each architecture
• Switched from JDK to JRE to save space
• Added Adoptium OpenJDK support for s390x and ppc64le architectures
• May 17th 2022
• Bump Dockerfile base image to ubuntu:latest
• May 16th 2022
• Add -DPaper.IgnoreJavaVersion=true to allow OpenJDK 17 to run the older Paper Minecraft versions (thanks NotMick)
• May 15th 2022
• Added screen -wipe to beginning of start.sh to prevent a startup issue that could occur if there was a "dead" screen instance (thanks grimholme)
• May 12th 2022
• Added platform argument to avoid issues on aarch64 platforms
• May 11th 2022
• Fixed optional MaxMemory environment variable (adding missing M for megabytes in -Xmx java parameter)
• May 10th 2022
• Initial release -- thanks to everyone who kept asking about it so I would finally put it together!