Docker Setup Documentation

Contents

Crafty Docker Images 🐳

/File/en/Content.png

Warning
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: Link to Windows Article section regarding portable install

With 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:

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)

Prerequisites

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 root.

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.

Installation

The Crafty Docker images can be run in multiple ways:

Using Docker Engine

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!

  1. Install Docker Compose

  2. Create a docker-compose.yml

    # Make your compose file
    $ vim docker-compose.yml
    
  1. Make sure you are in the same directory as docker-compose.yml and start Crafty:
    docker-compose up -d && docker-compose logs -f
    

Configuration

Use tagged versions of Crafty

The provided image supports both arm64 and amd64 out the box, if you have issues though you can build it yourself with the compose file in docker/.

The image is located at: registry.gitlab.com/crafty-controller/crafty-4:latest

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:

Port Requirement
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: network_mode: host
You must keep in mind in the security implications of this as binding to the host does give dbus access!

Update

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:

  1. Take a backup of your volume mounts.
  2. Stop the running container:
    docker stop crafty_container
    
  3. Remove the existing container:
    docker rm crafty_container
    
  4. Pull the new image or build from repo. For example, the latest Crafty image:
  1. Create the container once again with the previously specified options

Update using Docker compose

To update Crafty that was installed using Docker Compose:

  1. Take a backup of your volume mounts.
  2. Download the newest/build release and update your Crafty instance:

Post-Install

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
Pre-1.16.5 Java 8 /usr/lib/jvm/java-8-openjdk-amd64/bin/java
1.16.5 vanilla/Forge Java 11 /usr/lib/jvm/java-11-openjdk-amd64/bin/java
1.17 Java 16 /usr/lib/jvm/java-16-openjdk-amd64/bin/java
1.18 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

Permission problems

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

/File/en/Notice.png
Java 18 or 17 is packaged with our image, you will need to select the correct version to run Forge 1.18 or 1.19

Here are the steps to get Forge server running:

Import field Example
Server Name Forge Test
Server path /crafty/imports/forge.zip
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>
Your Server Execution Command will look something like this:
	java -Xms4000M -Xmx4000M @libraries/net/minecraftforge/forge/1.18.2-40.1.68/unix_args.txt nogui
/File/en/Content.png
Warning - DO NOT just copy the above, your forge server will be different. LOOK at your .bat/.sh provided by the installer and extrapolate the information to resemble the above. (No need to include %* or [email protected])

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!