Installation

Singleplayer Install

This guide is for users who have little or no server administration experience and are trying to set things up for singleplayer use. This guide omits a lot of important information for multiplayer setups and includes a lot of unnecessary information on how to do every step on the install process. This is intended to make it as easy as possible for novices to get started. If you’re an IT administrator trying to setup a multiplayer server, please navigate to the Advanced Install guide. I’m sure you’ll find it to be both more detailed and more concise.

Windows Install

To get EBPP running on Windows, you will first need to install Docker Desktop which includes the Docker Engine and command line interface. Docker Desktop gives you an easy visual interface for managing your EBPP instance. It is technically not necessary, but will minimize the amount of time you need to spend in the command line interface. Instructions for how to do this can be found on this page. Please read through this documentation carefully. You will need to meet the minimum requirements for Docker to run and you will need to enable virtualization features on Windows. If you cannot get Docker running and don’t have server administration experience then I would recommend that you have your company or educational institution set up a server for your to use instead.

Once you have finished installing and launching Docker Desktop, you will need to build the EBPP image. Open your command prompt by hitting the Windows key and typing “cmd” into the search bar. This should open up your command prompt. Once there type in the following command:

docker build github.com/ElectricBlocks/ebpp -t ebpp

This will launch the build process. Once the command is finished executing, open up Docker Desktop and click on the “Images” tab on the left hand side of the navigation bar. If the build completed successfully, you should see a screen that looks something like this:

Docker Desktop Images
Docker Desktop Images

Locate the EBPP image and move your mouse to the far right hand side of the row to display the options and run button:

Docker Desktop Run Image
Docker Desktop Run Image

Click run and a popup window will appear for you to create a new container:

Docker Desktop New Container
Docker Desktop New Container

Click the “Optional Settings” dropdown to expand the menu. At minimum, you need to enter the host port (should usually be 1127). You can give the container an optional name if you would like. If not, a name will be randomly generated for the container. No other values should be set:

Docker Desktop New Container Settings
Docker Desktop New Container Settings

Click Run and a new container will be generated and you will be brought to the “Containers / Apps” panel. The EBPP container should appear in the list and should automatically start:

Docker Desktop Containers
Docker Desktop Containers

To verify that EBPP is working, you can click on the container name to be brought to the logs for this container. The output should say something like:

No arguments passed. Using defaults.
* Serving Flask app "ebpp" (lazy loading)
* Environment: production
WARNING: This is a development server. Do not use it in a production deployment.
Use a production WSGI server instead.
* Debug mode: off
* Running on http://0.0.0.0:1127/ (Press CTRL+C to quit)

At this point, EBPP should be installed and running! You can now launch your modded Minecraft game on the same computer and should be able to connect.

Mac Install

Installation on a Mac is essentially the same as the Windows install except that you must use Docker Desktop for Mac. A guide for how to do this can be found on this page. Once you have Docker Desktop for Mac installed, follow essentially the same steps except you will need to run the build command in your Terminal instead of in the command prompt.

Linux Install

Unfortunately there is no Docker Desktop for Linux that is available. I’d recommend just using the advanced install guide for this process. You’re on Linux so you’re used to figuring stuff out on your own anyways. Good luck.

Advanced Install

This guide covers installation for advanced users. If you’re trying to setup EBPP for multiplayer servers then you’re in the right place.

When installing this software you have two options. The first option uses docker to automate the process. This option is easier to do. I would pretty highly recommend using Docker over a bare metal installation. The second option is the manual installation.

Docker Method

First make sure you have docker installed on your computer/server. Then build with this command:

docker build github.com/ElectricBlocks/ebpp -t ebpp

Once the docker image is finished building, you can run with the command:

docker run -d -p 1127:1127 ebpp

Manual Method

To install manually, you will need to have Python 3.8+, pip, and Git.

git clone https://github.com/ElectricBlocks/ebpp.git
cd ebpp
pip install -r requirements.txt

Once the python packages are installed, you can run with the command:

python ebpp.py

Advanced Information

Configuration

EBPP uses environment variables for configuration. The easiest way to load these variables is to create a .env file in the EBPP directory. The environment file will not overwrite any environment variables and you may set them anyway you like. The option to use a .env file is provided for convenience. The file should contain the contents:

EBPP_HOST=0.0.0.0
EBPP_PORT=1127

These defaults should work fine, but you should change these to best fit your particular setup. Once you have configured and launched EBPP, you can test to ensure it is working and accessible by visiting http://[EBPP_HOST]:[EBPP_PORT]. The API endpoint is http://[EBPP_HOST]:[EBPP_PORT]/api.

Security Considerations

EBPP is NOT designed for public facing scenarios and doesn’t have any built-in security features. For this reason, we highly recommend that you install EBPP inside of a Docker container or some other virtualized environment. EBPP executes code based on packet input and so we it is highly probable that there is a remote code execution vulnerability somewhere in there. We have never been security audited nor are we likely to be any time soon.

The default configuration binds to 0.0.0.0 which accepts requests from any address regardless of source. This is the easiest to use, but also insecure. If you are running a Minecraft server, we recommend that you bind EBPP to the loopback address or an isolated Docker network address to ensure that EBPP is only accessible by the Minecraft server itself. We cannot make any kind of guarantees about the security of this software, especially if you don’t take measures to isolate it from network access. If you are running EBPP on the same virtual machine as the Minecraft server, you must run EBPP as a different user that doesn’t have file permissions to read or write from anything non-essential. The user will need read access to your normal system files and should not have write access to anything.

If you install EBPP on a separate server than the one hosting the Minecraft server we recommend that you configure EBPP to only be accessible by LAN IP. Making EBPP only available through an institutional VPN is probably a good idea. We also recommend setting up strict firewall rules to ensure that communication only occurs between EBPP and your various Minecraft servers.

If you do choose to run EBPP in a public facing setting, you will need to take several measures to protect your security and performance. First of all, EBPP should be run in a virtual machine or other resource limited container. That virtual machine should be in a DMZ that doesn’t have access to any other I/O or network resources. EBPP doesn’t have any built in authentication, encryption, or scaling mechanisms. To deal with this, you should setup a standalone WSGI container such as Gunicorn or uWSGI which is only accessible through a reverse proxy like Apache, Nginx, or Caddy. You may want to also utilize some sort of rate limiting or even an intrusion detection system like Fail2ban. While EBPP can be easily setup to utilize SSL through a reverse proxy, the Electric Blocks mod is not currently designed to support this. While a MITM attack seems unlikely, it is possible that confidential information could be leaked since no encryption is in use. If this is a concern, do not setup EBPP in a public facing setting.