BanManager WebUI

Modern web client designed for self-hosting

Website | Docs | Demo

Overview

• Always connected. Manage punishments from anywhere with seamless logins
• Cross platform. It doesn't matter what OS you use, it just works wherever Node.js runs
• Responsive interface. Manage your community from any device at any time

To learn more about configuration, usage and features of BanManager, take a look at the website or view the demo.

Features

• Appeal punishments
• Ban, unban, mute, and warn players
• Review and manage reports on the go
• Custom roles and flexible permissions
• A single interface for multiple Minecraft servers

Installation (Production)

For deploying BanManager WebUI on your own server, see the full installation guide.

Requirements

• Node.js LTS (v20 or v22)
• MySQL v5+ or MariaDB v10+
• Minecraft server with BanManager & BanManager-WebEnhancer plugins configured to use MySQL or MariaDB

Quick Install

git clone https://github.com/BanManagement/BanManager-WebUI.git
cd BanManager-WebUI
npm ci --production
npm run setup

The setup wizard will guide you through configuring your database connection and creating an admin account.

---

Development

Want to contribute or run a local development environment? This section is for you.

Prerequisites

• Node.js LTS (v20 or v22)
• Docker (for local MySQL database)

Quick Start

# Clone the repository
git clone git@github.com:BanManagement/BanManager-WebUI.git
cd BanManager-WebUI

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Start MySQL and seed the database (first time setup)
npm run dev:setup

# Start the development server
npm run dev

The application will be available at http://localhost:3000

Test Accounts

After seeding, the following accounts are available:

Role	Email	Password
Guest	guest@banmanagement.com	testing
User	user@banmanagement.com	testing
Admin	admin@banmanagement.com	testing

Available Scripts

Script	Description
npm run dev:setup	Start MySQL container and seed the database
npm run dev	Start development server with hot reloading
npm run db:start	Start the MySQL Docker container
npm run db:stop	Stop the MySQL Docker container
npm run seed	Run migrations and seed data (fails if DB exists)
npm run seed:reset	Drop existing database and re-seed
npm run build	Build for production
npm run test	Run linting and tests
npm run lint	Run linting only
npm run cypress	Open Cypress for E2E tests

Environment Configuration

Copy .env.example to .env and adjust as needed. Key variables:

• DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME - Database connection
• ADMIN_USERNAME, ADMIN_PASSWORD - Admin account credentials (also used by Cypress)
• ENCRYPTION_KEY, SESSION_KEY - Security keys (generate unique values for production)

Resetting the Database

To reset the database with fresh seed data:

npm run seed:reset

Running Tests

# Run all tests
npm run test

# Run Cypress E2E tests
npm run cypress

Contributing

If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.

Help / Bug / Feature Request

If you have found a bug please open an issue with as much detail as possible, including relevant logs and screenshots where applicable

Have an idea for a new feature? Feel free to open an issue or join us on Discord to chat

License

Free to use under the MIT

Screenshots

Click to view

Home

Player

Dashboard

Appeal

Report