This article has been requested for deletion.

Reason: BE ADVISED! THIS DOCUMENTATION IS NO LONGER ACTIVE OR UPDATED. PLEASE SEE UP TO DATE DOCUMENTATION AT our new doc site

Requester: Not Supplied

Crafty Docker Images 🐳

This article has been requested for deletion.

Reason: BE ADVISED! THIS DOCUMENTATION IS NO LONGER ACTIVE OR UPDATED. PLEASE SEE UP TO DATE DOCUMENTATION AT our new doc site

Requester: Not Supplied

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:

• 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)

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!

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
• Using Docker Compose

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 run command 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 Dockerfile is 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!

1. Install Docker Compose

2. Create a docker-compose.yml

   # 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 cd to the docker directory

3. 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:

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:

• Pre-built

  docker pull registry.gitlab.com/crafty-controller/crafty-4:latest
  

• Local-build

  $ git fetch
  $ git pull
  $ docker build . -t crafty
  

5. 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:

• Pre-built

  docker-compose pull
  docker-compose up -d
  

• Local-build

  $ git fetch
  $ git pull
  $ docker-compose build
  $ docker-compose up -d && docker-compose logs -f
  

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:

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:

  docker exec -it crafty_container bash
  

  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 mode in the container and will not accept commands.

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

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

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:

• 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.)
  

• 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

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 $@)

• 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!