Minecraft Paper Fabric

Hybrid Minecraft Server combining both Paper and Fabric using Velocity Proxy. It supports BlueMaps using one web UI for both servers and supports multi-paper worlds using the Multiverse Plugin.

Overview

MC-Paper-Fabric is a Docker-based setup that currently supports Minecraft versions between 1.21.8 and 1.16.5 that enables a hybrid Minecraft server environment, integrating:

• Paper Server: For high-performance player optimised worlds, features plugin support. Good for things like player Hubs or vanilla Minecraft worlds.
• Fabric Server: For lightweight modding capabilities.
• Velocity Proxy: To route players between the two servers while only needing to connect to one.
• BlueMaps: A web-based map interface which combines the BlueMaps instances from both Paper and Fabric. Meaning players will only need to visit one web interface to access both server UIs.
• RCON: Allows for easy server management for both Paper and Fabric servers without the need to be on the Minecraft server directly.

This configuration allows players to connect through a single proxy and enjoy both plugin and mod functionalities.

Features

• Dual Server Integration: Run both Paper and Fabric servers concurrently.

• Velocity Proxy: Directs player connections to the appropriate backend server.

• BlueMaps: Provides a unified, modern map interface for both servers.

• Automated Backups: Regular backups of server data to prevent data loss.

• Dockerized Deployment: Simplifies setup and management using Docker and Docker Compose.

• RCON: Allows for easy server management using standard Minecraft commands outside the Minecraft client.

Versions:

V3.2 currently works for versions between 1.21.8 - 1.16.5 this may work with other versions of Minecraft assuming plugins and mods are changed accordingly. However, they have not been tested.

To change to a different version, you must:

Run the init_setup.sh script with the -u flag as shown below

$ init_setup.sh -u

This will let you enter your new Minecraft version and will change all jars & configurations for you :)

Repository Structure

MC-Paper-Fabric/
|- .setup_config/       # Contains all jar links for mods and plugins
|- MCFABRIC-data/       # Fabric server configs and files
|- MCPAPER-data/        # Paper server configs and files
|- MCPROXY-data/        # Velocity proxy config files
|- MCPF-backups/        # Backup storage dir
|- backup/              # Backup scripts and Dockerfile
|- restore/             # Restore script and Docker compose file
|- configs/             # Default configs
|- mods/                # Fabric mods go here
|- plugins/             # Paper plugins go here
|- BlueMaps  /          # BlueMaps shared configuration (render files will go here)
|- docker-compose.yml   # Docker compose file
|- world-list.txt       # List of worlds to include in backups -> FABRIC WORLD MUST BE LAST
|- rcon-cli.sh          # Allows and admin to issue commands to either Minecraft servers
|- init_setup.sh        # Setup/ update script to download mod and plugin jars automatically

Prerequisites

• Docker

• Docker Compose

• yq

Setup Instructions

1. Clone the Repository

git clone https://github.com/Restfulbee37/MC-Paper-Fabric.git
cd MC-Paper-Fabric

2. If you already have custom worlds you want to import

   • Note: MC-paper-fabric cannot predict the names of your worlds and therefore you will have to setup BlueMaps yourself based on the steps below, this also applies the same if you are using Multiverse for Paper.
   • To set up this server with your own paper and fabric worlds you must place your worlds in the respective fabric and paper directories in custom-worlds as directories. See example below:

   custom-worlds/
   |- fabric/
   |   |- fabric-world1/
   |   |   |- fabric world files here
   |- paper/
   |   |- paper-world1/
   |   |   |- paper world files here
   |   |- paper-world2/
   |   |   |- paper world files here

   • This will auto move these directories to the correct directories during the setup phase and populate the world-list.txt for you.
   • You would then follow step 3 and beyond as normal however, you will add the -m flag when running the inital setup script as shown in the example below:

   $ ./init_setup.sh -s -m

   • If you do not have any worlds you would like to put in you can skip this step and move onto step 3.

3. Install your Version

   • Run the script at the root of this directory init_setup.sh -s and follow the configuration options within the script. This will install the correct core mods and plugins for your chosen Minecraft version as well as set that Minecraft version in the docker-compose file. The script will also ask you to set your difficulty and your gamemode as well as Ops for the server.
   • NOTE: There are some sudo commands in this script to do the permission settings at the end (see step 6) if you would prefer to do this manually please follow step 6 otherwise you can ignore step 6.

4. Add Mods and Plugins

   • Place your Fabric mods in the mods/ directory.
   • Place your Paper plugins in the plugins/ directory.

5. Configure Servers

   • Update world-list.txt with the names of the worlds you wish to backup. NOTE: Your Fabric world MUST be the bottom of this list for this to work, see example in the file.

6. Configure BlueMaps

   • If you keep everything as default, it should work out of the box, BlueMaps will render automatically on server start.

   If you change the world names:

   • For the Paper world: Navigate to BlueMaps/config/maps and change the header "world" in each of the 'MCPAPER' configs to reflect your new world name.
   • For the Fabric world: Navigate to MCFABRIC-data/config/bluemap/maps and change the header "world" in the three fabric world config files to reflect your new world name.

   If you have multiple Paper worlds using something like Multiverse:

   1. Make sure these worlds are initialized i.e. you should have three seperate world files one for the overworld, one for the nether and one for the end. Paper will automatically do this when you create the new world.
   2. Clone the current MCPAPER config files located in BlueMaps/config/maps (these cloned files will be used for your second world).
   3. Change the name of these config files (these can be to whatever you want).
   4. Inside each cloned config file change the header "world" to reflect the directory name of your second world and change the header "name" to whatever you like (this will be what shows up in your BlueMaps UI).
   5. To have more than 2 Paper worlds, repeat steps 1-4 for each world.

7. Permissions

   • Linux systems must set the file permissions for all volume directories to 1080: chown -R 1080:1080 .

8. Start the Services

   docker compose up -d

   This command will pull and build relevant Docker images and start the Velocity proxy, Paper server, Fabric server and the backup system.

9. Navigate between servers

   • To navigate between servers within Minecraft you would type in the commands shown below:

   /server paper
   /server fabric

BlueMaps

BlueMap is a program that reads your Minecraft world files and generates not only a map, but also 3D-models of the whole surface. With the web-app you then can look at those in your browser and basically view the world as if you were ingame.
In this setup:

• Utilises BlueMaps on both servers to get live player updates for players in all servers.
• Merges both instances into one UI to make it easier to navigate for a user (similar to the legacy implementation using LiveAtlas with Dynmap).
• Live updates world changes and allows for a spectator style view.

For more information on configuring multiple servers with BlueMaps, refer to the BlueMaps Wiki.

RCON CLI

RCON is an easy way to manage your Minecraft servers from the command line without the need to be directly logged into the Minecraft server.
All commands in RCON are the same as you would get if you were on the server with OP privileges.

A script has been written called rcon-cli.sh that will take an admin to the console of the requested server where they can issue commands as they would on the actual Minecraft server.

$ ./rcon-cli.sh -h
Usage: ./rcon-cli.sh [OPTION]

Options:
  -f, --fabric       Attaches to Fabric server RCON
  -p, --paper        Attaches to Paper server RCON
  -h, --help         Show this help message

An example usage would look like this:

$ ./rcon-cli.sh -p
Attaching to Paper RCON, type 'exit' to quit
> say Hello this is a demonstration of RCON!

> gamemode survival Restfulbee37
Set Restfulbee37 game mode to Survival Mode
> give Restfulbee37 minecraft:diamond_sword
Gave 1 [Diamond Sword] to Restfulbee37
> exit
RCON exited, welcome back!
$

Backup and Restore System

An automated backup and restore system utilizing RCON and implemented in Docker:

• Backups: Regular backups are created and stored in the MCPF-backups/ directory. The backup process includes:
  • Flushing world data to disk.
  • Archiving specified worlds listed in world-list.txt.
  • Archiving plugin configurations and other world configs.
  • Storing backups with timestamps for easy retrieval and restoration.
• Restore: Restores can be conducted with:

cd restore
docker compose up

It will provide labelled error codes if any occur or give Exit code: 0 if successful.

The backup and restore scripts are located in the backup/ and restore/ directories, respectively.

Credits

• itzg/docker-minecraft-server for the Docker images used for the Paper and Fabric servers.
• PaperMC for the Paper Server.
• FabricMC for the Fabric Server.
• Velocity for the Minecraft proxy.
• BlueMaps for the BlueMaps interactive world UI.

Legacy Credits

• Dynmap for the real-time map rendering.
• LiveAtlas for the Dynmap web-based interface.

License

This project is licensed under the MIT License. See the LICENSE file for details.