Install

A full guide for installing, configuring and running BanManager WebUI for use in production.

Prerequisites

The recommended installation requires the following stack:

• BanManager configured to use MySQL or MariaDB
• MySQL or MariaDB (this can be the same database used above but must be accessible)
• Git
• Node.js LTS
• NGINX or equivalent (for SSL)
• A server with at least 1GB memory
• A registered domain name

Initial Setup

There are two parts, the Minecraft plugin which enables web only features and the UI which renders the page and provides a GraphQL API.

BanManager-WebEnhancer

This is a required plugin which enables web only features.

1. Download and add the jar to your compatible server. The source code is also available.
2. Edit BanManager's messages.yml, and add a [pin] token to the ban.player.disallowed & tempban.player.disallowed messages

   ban:
     player:
       disallowed: '&6You have been banned from this server for &4[reason] \nUse [pin] to appeal'
   tempban:
     player:
       disallowed: '&6You have been temporarily banned from this server for &4[reason] \n&6It expires in [expires] \nUse [pin] to appeal'
   

3. Restart the server or enable BanManager-WebEnhancer plugin and execute /bmreload

WebUI

Create a directory on your server for your installation. This can be a different server than your Minecraft server (as long it can connect to the MySQL database). We'll name it banmanager in this example but you can use whatever you like.

mkdir /home/banmanager
cd /home/banmanager

Download

git clone https://github.com/BanManagement/BanManager-WebUI.git

Install

cd /home/banmanager/BanManager-WebUI
npm ci --production

Once dependencies have been downloaded and installed, run the setup command:

npm run setup

Setup Questions

During the installation, the CLI will ask a number of questions to configure the application. Press Enter to use the default value. If you make a mistake during the installation process, simply exit the setup (ctrl + c OR cmd + c) and run it again.

The CLI will generate a .env file containing the necessary environment variables in order for the application to run. This will automatically be used on start up. If you do not wish to use this, simply remove the file and pass in the environment variables yourself when running the process.

Contact Email Address

On setup, tokens are generated to enable push notifications. This is a requirement from vendors in order to contact you if this functionality is abused. This should be an email address that can receive mail.

Database Host

This should be the host of the database used to setup web specific tables such as logins. This can be the same database used by the BanManager Minecraft plugin, but it does not have to be. The setup process will create the tables for you.

Database Port

As above, this will default to 3306

Database User

As above. Ensure this user has permissions to create tables.

Database Password

As above

Database Name

As above

Add BanManager Server

You will be prompted to specify details of your BanManager plugin database connection details. If tables are not found or the connection fails, you will be reprompted the question again.

playerPins table

This is the name of the table which contains login pins. By default this is set to bm_player_pins and is the value within your BanManager config.yml file.

playerReportLogs table

This is the name of the table which contains report log data. By default this is set to bm_report_logs and is the value within your BanManager config.yml file.

serverLogs table

This is the name of the table which contains report log data. By default this is set to bm_server_logs and is the value within your BanManager config.yml file.

Console UUID

BanManager generates a UUID to use when punishing players by the console. This can be found in your console.yml file. This record must exist.

Server Name

Like the legacy UI, you can name servers in order to differentiate between where punishments occurred. This is useful for multi-server setups. This can be whatever you like.

Your Email Address

Set this to an address you wish to use to login with. This does not need to be the same email address as your Mojang account.

Your Password

Set this to a value you wish to use to login with. This should not be the same password as your Mojang account. If you forget this password, you can login using a pin generated in-game via /bmpin command (requires BanManager-WebEnhancer).

Your Minecraft Player UUID

This is required to setup your login and associate your data. If you're not sure what this is, use a lookup tool such as https://mcuuid.net/ to lookup your online UUID.

Run

The following environment variables are required and should have been generated by the previous setup step.

CONTACT_EMAIL
ENCRYPTION_KEY
SESSION_KEY
NOTIFICATION_VAPID_PUBLIC_KEY
NOTIFICATION_VAPID_PRIVATE_KEY
DB_HOST
DB_PORT
DB_USER
DB_PASSWORD
DB_NAME

If you are not using the .env file, you must pass these variables yourself in the next steps.

Next run the systemd command below to run the UI as a service. This will ensure it runs in the background and automatically restarts. You may be prompted to provide a password for sudo access. This is expected and the commands that will be executed will be provided beforehand.

npx bmwebui setup systemd

If you do not have systemd, you can use an alternative such as PM2. Note that this is not covered by the installation guide.

It is highly recommended to use a web server such as NGINX to provide HTTPS support and defend against a number of common web attacks. Certificates for HTTPS can be obtained freely via Let's Encrypt. To help with this, another setup command can be used to configure NGINX via HTTP.

First install NGINX if you haven't already:

sudo apt update && sudo apt install nginx

Next run the setup command:

npx bmwebui setup nginx

NGINX Setup Questions

Domain

This will be how you access the website. You are expected to have registered a domain name and configured the DNS to point to your server. Without this, the WebUI will not function as expected.

Subdirectory

If you want to run the UI on an existing domain rather than a separate domain or subdomain, please provide the path here. A new environment variable of BASE_PATH will be added to your .env file. Please restart the UI (if via systemd above run sudo systemctl restart bmwebui.service) and re-run the npx bmwebui setup nginx command once completed.

Once this is completed, the UI should be available over HTTP. Try it out! Next, we need to secure the site via HTTPS to prevent attackers eavesdropping on pins/passwords that are entered into the UI.

Let's Encrypt Setup

First install CertBot. This is used to manage and rotate certificates.

sudo apt update && sudo apt install certbot

Once installed, run the following command to automatically generate a certificate and update your NGINX configuration. Ensure to replace example.com with the domain you chose in the setup previously.

sudo certbot --nginx -d example.com

That's it! Now head over to your UI domain and login.