Docker Installation Guide
Docker on Windows - Docker Desktop / WSL
BE ADVISED! We do not support Docker for Windows! There is currently a known issue with volume permissions that will permanently destroy your Minecraft world if running on Docker under WSL/WSL2, Windows 11 / DOCKER DESKTOP!
On Stop or Restart of the MC Server, there is a 90% chance the World's Chunks will be shredded irreparably!
Please only run Docker on Linux based systems, If you are using Windows we have a portable installs, more information can be found here: Windows Installation
Crafty 4 we have focused on building our DevOps Principles, implementing build automation, and securing our containers, with the hopes of making our Container user's lives abit easier.
Two big changes introduced with Crafty 4:
- We now provide pre-built images for you.
- Containers now run as non-root, using practices used by OpenShift & Kubernetes (root group perms).
This article will go slightly more in depth on how you can set up Crafty on Docker!
(Remember you can find a quick start guide on the repositories README.md)
Docker is required. See the official installation documentation
Prepare the bind mounts
Before we start getting into the meat things an important thing to know and understand is how we utilize volumes for persistent storage, if you are moving from a different install method to docker please customize you're paths accordingly!
To achieve host file acces in a non-root user environment we employ the root group file permissions method instead of requiring users to set a UID & GID.
To make the end users life easier in terms of volume and permissions we actively set permissions via a Wrapper when the container starts for the first time (if no/empty config folder is present.)
This means any mounted volume in the container location
/crafty will have
special bit applied
group perms set to
Triggering automated mount permission repair
If you require the permissions to be set again, put files in the
/import mount, then restart the container. This will trigger the wrapper to fix permissions over all bind mounts on container start, until
/import is empty.
DO NOT bind
'/' (root) on your host system, as this will have grave consequence! If you don't feel comfortable with what you're doing stop and use the defaults below!
When referring to file system locations in a containered Crafty instance, don't use host pathing as that wont exist in the container, please refer to the corresponding container location below:
|Local location||Container location||Usage|
|./docker/backups||/crafty/backups||Storage for Server backups|
|./docker/logs||/crafty/logs||Storage for Crafty logs|
|./docker/servers||/crafty/servers||Storage for Imported/Built Servers|
|./docker/config||/crafty/app/config||Storage for Crafty's config and database files|
|./docker/import||/crafty/import||Where you will drop server zips/directories for crafty to import|
RE: Imports --- We understand this is not ideal for everyone, you can upload smaller zips through the Web GUI
The Crafty Docker images can be deployed in multiple ways:
Using Docker CLI
docker run \ --name crafty_container \ --detach \ --restart always \ -p 8000:8000 \ -p 8443:8443 \ -p 8123:8123 \ -p 19132:19132/udp \ -p 25500-25600:25500-25600 \ -e TZ=Etc/UTC \ -v "/$(pwd)/docker/backups:/crafty/backups" \ -v "/$(pwd)/docker/logs:/crafty/logs" \ -v "/$(pwd)/docker/servers:/crafty/servers" \ -v "/$(pwd)/docker/config:/crafty/app/config" \ -v "/$(pwd)/docker/import:/crafty/import" \ registry.gitlab.com/crafty-controller/crafty-4:latest
docker run \ --name crafty_container \ --detach \ --restart always \ -p 8000:8000 \ -p 8443:8443 \ -p 8123:8123 \ -p 19132:19132/udp \ -p 25500-25600:25500-25600 \ -e TZ=Etc/UTC \ -v "/$(pwd)/docker/backups:/crafty/backups" \ -v "/$(pwd)/docker/logs:/crafty/logs" \ -v "/$(pwd)/docker/servers:/crafty/servers" \ -v "/$(pwd)/docker/config:/crafty/app/config" \ -v "/$(pwd)/docker/import:/crafty/import" \ arcadiatechnology/crafty-4:latest
If you'd rather not use the prebuilt image and assuming you have
the repository cloned, in the root directory where the
located run use the following:
docker build . -t crafty-4 docker run \ --name crafty_container \ --detach \ --restart always \ -p 8000:8000 \ -p 8443:8443 \ -p 8123:8123 \ -p 19132:19132/udp \ -p 25500-25600:25500-25600 \ -e TZ=Etc/UTC \ -v "/$(pwd)/docker/backups:/crafty/backups" \ -v "/$(pwd)/docker/logs:/crafty/logs" \ -v "/$(pwd)/docker/servers:/crafty/servers" \ -v "/$(pwd)/docker/config:/crafty/app/config" \ -v "/$(pwd)/docker/import:/crafty/import" \ crafty-4
A fresh build will take several minutes depending on your system, but will be rapid thereafter.
The provided examples will pull/build the image, start Crafty in a container and publish ports needed for the Panel. '100 x Ports for Minecraft Servers, udp port for bedrock, and 8123 for dynmap(optional)'.
All Crafty data will be stored in the
present working directory(pwd) where you ran the
docker run command The container will automatically restart after a system reboot.
Using Docker Compose
With Docker Compose you can easily deploy and update your containerized crafty instance!
If you are building from docker-compose you can find the compose file in ./docker/docker-compose.yml
Providing you have the repository cloned, just
cd to the
/docker directory where the build yml is included
Use tagged versions of Crafty
Arcadia produced images support both
amd64 out the box, if you have issues though you can build our image yourself with the local build examples above. Bare in mind some packages may require tweaking as a few are sometimes missing for certain architectures.
Support for third-party container images
As with any software, image variants built by third-parties come in many shapes and sizes.
Please be advised if you are running a container that does not use our official image we will not be able to provide you support. We can only support Arcadia images where we are familiar with the environment.
The image is located at:
Expose Crafty on different ports
Crafty will require various ports to be exposed to be able to be accessible.
The following is a list of the ports that are required:
|8000||Required for http > https redirects|
|8443||Required for Panel Access|
|8123||Required for Dynmap(Optional)|
|19132/udp||Required for Bedrock Minecraft Server|
|25500-25600||Required Port range for Minecraft servers|
The port range for Minecraft servers has been reduced to 100 ports. This should be more than enough, you can of course increase this if required but remember higher ranges could cause the docker daemon's networking to stall.
Docker Port Syntax
If you are looking to re-map these ports it's as simple as changing the left most option(external) in the previous examples.
You can as well bind host networking as another option, This is pretty overkill and This will discard any published ports, It is useful to optimize performance in situations where a large range of ports is required...
Example: Engine & Compose:
You must keep in mind in the security implications of this as binding to the host does give dbus access!
Update Crafty Container
Updating to the newest version of crafty or switching should be easy as pi, in most instances, migrations of the database are handled internally by crafty.
⚠️ Always refer to update recommendations given by crafty staff when upgrading between major versions that may include breaking changes. ⚠️
To update crafty that was installed using Docker Engine:
To update Crafty that was installed using Docker Compose:
- Take a backup of your volume mounts.
Download the newest/build release and update your Crafty instance:
Docs coming soon!
Back up Crafty
Crafty does not have any built in backup/restore methods currently, This is something that you will need to do manually, or using automation of your choice! It should be as simple as backing up your volume mounts!
Great work, You're ready to proceed to the next step 🎉
How to access the dashboard
Troubleshooting / FAQ
The following information may be of some use if you encounter problems using Crafty and Docker
Java paths inside the container
As the container comes pre-built with most required versions of Java, you will need to select the correct one for the server version that you are using.
The following table will detail the Java versions and their locations:
|MC Version||Java Version||Container location|
|1.16.5 vanilla/Forge||Java 11||/usr/lib/jvm/java-11-openjdk-amd64/bin/java|
|1.17 +||Java 17||/usr/lib/jvm/java-17-openjdk-amd64/bin/java|
|MC Version||Java Version||Container location|
|1.16.5 vanilla/Forge||Java 11||/usr/lib/jvm/java-11-openjdk-arm64/bin/java|
|1.17 +||Java 17||/usr/lib/jvm/java-17-openjdk-arm64/bin/java|
Diagnose potential problems
- Read container logs:
Enter running container:
From within the container you can administer the Crafty container as you would normally administer on a bare metal instance, bare in mind though crafty runs in
daemon modein the container and will not accept commands.
When updating from legacy Crafty Docker images, or transferring files in and out of the volume mounts, you might counter permission problems.
If this happens just restart the container and the wrapper should correct the permissions on the volume mounts. If the wrapper is unable to resolve this, ensure the file permissions on your host are
<your local user>:root for the bind mounts.
Minecraft World Chunk Corruption
On restarting a Minecraft server inside of crafty if you are receiving a whole bunch of chunk corruptions/truncation, You are likely running on
Docker for Windows This is not supported by our image and other Minecraft images due to volume mount issues with
Docker for Windows.
We mentioned this at the start of this documentation and on the quick start README.md, And don't have much information on how you can recover worlds affected by this. If you are using
Docker for Windows it is unsupported, ⚠️Proceed at your own risk⚠️
Error during connection
The following error is usually indicated when there is an issue with the docker daemon or it is not running, Please ensure your docker daemon is running and restart if required.
How to Setup Forge
We recommend using 'Crafty's Server Builder Tool' to create a Forge server
Select the correrct Java version for Forge
Java is packaged with our image, you will need to ensure you select the correct version to run Forge 1.18 or 1.19 Please refer to the Version table
Here are the steps to get Forge server running:
STEP 1 Run Forge Installer, select directory like
/forgeto extract to. After doing so zip the directory
/forgeto a archive called
STEP 2 Copy this zip file to
<docker dir>/docker/importand return to the 'Crafty Dashboard'.
STEP 3 Click Create a server, and follow the instructions in zip import. (The Import should be pretty quick.)
Import field Example Server Name
Select root dir
Select 'forge' or whatever the parent directory of /libraries is.
Server Executable file
4GB (or whatever)
4GB (or whatever)
<Your choice, I left as default 25565>
STEP 4 When the forge server has been imported we are going to need to do a little bit of deconstruction of the .sh file created by the Forge installer.
Your Server Execution Command will look something like this:
- STEP 5 You should now be good to start the server, it will take a moment for information to display on the Terminal because Forge servers are chonkers.
Help and Feedback
Help and Feedback
Hi there Zedifus here! I've tried to be as comprehensive as possible writing this documentation.
If you require any further help, please reach out to us on Discord for non-commercial, and email@example.com for commercial support.
If you have any feedback related to this, or have any changes you would like to see please do let us know!