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
Contents |
Crafty Docker Images 🐳
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 installWith 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!
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
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 thepresent working directory(pwd)
where you ran thedocker 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 theDockerfile
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!
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, justcd
to thedocker
directory
- 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:
- 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:
- Pre-built
docker pull registry.gitlab.com/crafty-controller/crafty-4:latest
- Local-build
$ 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:
- 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:
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 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 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.
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.)
Import field | Example |
---|---|
Server Name | Forge Test |
Server path | /crafty/import/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> |
- 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!