Crafty Docker Images 🐳
Crafty Controller 4.0 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 you will notice is:
- We now provide pre-built images for you guys.
- 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-Controller-4 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!
⚠ PLEASE NOTE: 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 a
special bit applied, And
group perms set to
If you require the permissions to be set again, put files in the import folder then restart the container, permissions will continue to be fixed over all bind mounts on container restart until import is empty. [if your container is taking longer than normal to start make sure you haven't left files in the import folder]
⚠ 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!
|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, we will be looking at building the functionality to upload zips through the dashboard.
The Crafty Docker images can be run in multiple ways:
Using Docker Engine
Container Registry Image
$ 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
This will pull the container from the repository, start Crafty 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 runcommand The container will automatically restart after a system reboot.
Local Image Build
If you'd rather not use the prebuilt image and assuming you have the repository cloned, in the directory where the
Dockerfileis located run use the following:
# REMEMBER, Build your image first! $ docker build . -t crafty $ 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
A fresh build will take several minutes depending on your system, but will be rapid thereafter.
You can track this process with:
docker logs -f crafty_container
Using Docker Compose
With Docker Compose you can easily deploy and update your containerized crafty instance!
Install Docker Compose
# Make your compose file $ vim docker-compose.yml
- Container Registry Image Example
version: '3' services: crafty: container_name: crafty_container image: registry.gitlab.com/crafty-controller/crafty-4:latest restart: always environment: - TZ=Etc/UTC ports: - "8000:8000" # HTTP - "8443:8443" # HTTPS - "8123:8123" # DYNMAP - "19132:19132/udp" # BEDROCK - "25500-25600:25500-25600" # MC SERV PORT RANGE volumes: - ./docker/backups:/crafty/backups - ./docker/logs:/crafty/logs - ./docker/servers:/crafty/servers - ./docker/config:/crafty/app/config - ./docker/import:/crafty/import
- Local Image Build
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
- Make sure you are in the same directory as docker-compose.yml and start Crafty:
docker-compose up -d && docker-compose logs -f
Use tagged versions of Crafty
The provided image supports both
amd64 out the box, if you have issues though you can build it yourself with the
compose file in
The image is located at:
Run Crafty on a public IP address
Monolithic compose example including SWAG Documentation to be crated - Zed
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.
If you are looking to re-map these ports it's as simple as changing the left most option(external) in the previous examples.
---Engine --- -p external:internal ---Compose--- services: crafty: ports: - "external:internal";
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
Updating to the newest version of crafty or switching branch tag 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.
Update using Docker Engine
To update crafty that was installed using Docker Engine:
- Take a backup of your volume mounts.
- Stop the running container:
docker stop crafty_container
- Remove the existing container:
docker rm crafty_container
- Pull the new image or build from repo. For example, the latest Crafty image:
docker pull registry.gitlab.com/crafty-controller/crafty-4:latest
$ git fetch $ git pull $ docker build . -t crafty
- Create the container once again with the previously specified options
Update using Docker compose
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:
docker-compose pull docker-compose up -d
$ git fetch $ git pull $ docker-compose build $ docker-compose up -d && docker-compose logs -f
Check out the Getting Started page.
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!
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|
NOTE: The above paths change dependant on arch (arm64 / amd64)
I plan on implementing a feature where crafty will auto-detect the local installations of Java give you a drop down instead of having to input the path yourself. This is a future Zed task. but this will do for now.
Diagnose potential problems
- Read container logs:
docker logs crafty_container -f
- 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
docker exec -it crafty_container bash
daemon modein the container and will not accept commands.
When updating from older Crafty Docker images, or transferring files in and out of the volume mounts, you might encounter permission problems.
If this happens just restart the container and the wrapper should correct the permissions on the volume 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,preceded 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.
error during connect: This error may indicate that the docker daemon is not running.: Get "http://%2F%2F.%2Fpipe%2Fdocker_engine/v1.24/containers/json": open //./pipe/docker_engine: The system cannot find the file specified.
How to Setup Forge
- Setting up Forge with Crafty can be a tricky one, as newer versions of forge require an installer.
- What you will need to do is set-up your forge server locally first, zip it up and import it into Crafty.
Here are the steps to get Forge server running:
- STEP 1 Run Forge Installer, select directory like `/forge` to extract to. After doing so zip the directory `/forge` to a archive called `forge.zip` for example.
- STEP 2 Copy this zip file to `<docker dir>/docker/import` and return to the 'Crafty Dashboard'.
STEP 3 Click Create a server, and follow the instructions in zip import. (The Import should be pretty quick.)
|Server Name||Forge Test|
|Select root dir||Select 'forge' or whatever the parent directory of /libraries is|
|Server Executable file||libraries/net/minecraftforge/forge/1.18.2-40.1.68/forge-1.18.2-40.1.68-server.jar|
|Min Memory||4GB (or whatever)|
|Max Memory||4GB (or whatever)|
|Server Port||<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.
java -Xms4000M -Xmx4000M @libraries/net/minecraftforge/forge/1.18.2-40.1.68/unix_args.txt nogui
- 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
Hi there Zedifus here, I tried to be as comprehensive as possible in the documentation. If you require any further help, please reach out to us on discord for non-commercial, and [email protected] 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!