feat: make it easier to run locally (#1684)

Author: confuser

.env.example

@@ -0,0 +1,36 @@
+# BanManager WebUI - Environment Configuration
+# Copy this file to .env and update values as needed
+
+# Server display name (shown in footer)
+SERVER_FOOTER_NAME=BanManagement
+
+# Contact email for push notification registration
+CONTACT_EMAIL=youremail@example.com
+
+# Database connection (defaults match docker-compose.yml)
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=password
+DB_NAME=bm_local_dev
+DB_CONNECTION_LIMIT=5
+
+# Security keys (generate unique values for production)
+# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+ENCRYPTION_KEY=b097b390a68441cc3bb151dd0171f25c3aabc688c50eeb26dc5e13254b333911
+SESSION_KEY=a73545a5f08d2906e39a4438014200303f9269f3ade9227525ffb141294f1b62
+
+# Push notification VAPID keys (generate with: npx web-push generate-vapid-keys)
+NOTIFICATION_VAPID_PUBLIC_KEY=
+NOTIFICATION_VAPID_PRIVATE_KEY=
+
+# Admin user credentials (used by seed script and Cypress tests)
+ADMIN_USERNAME=admin@banmanagement.com
+ADMIN_PASSWORD=testing
+
+# Server configuration
+PORT=3000
+LOG_LEVEL=info
+
+# Set to 'production' for production builds
+NODE_ENV=development

.naverc

@@ -0,0 +1 @@
+22

README.md

@@ -37,60 +37,160 @@
 </p>
 
 ## 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](https://banmanagement.com/) or view [the demo](https://demo.banmanagement.com).
 
 ## 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
 
-## Requirements
-- The latest [Node.js](https://nodejs.org/) LTS version (even numbered)
+## Installation (Production)
+
+For deploying BanManager WebUI on your own server, see the **[full installation guide](https://banmanagement.com/docs/webui/install)**.
+
+### Requirements
+
+- [Node.js](https://nodejs.org/) LTS (v20 or v22)
 - MySQL v5+ or MariaDB v10+
 - Minecraft server with [BanManager](https://github.com/BanManagement/BanManager) & [BanManager-WebEnhancer](https://ci.frostcast.net/job/BanManager-WebEnhancer/) plugins configured to [use MySQL or MariaDB](https://banmanagement.com/docs/banmanager/install#setup-shared-database-optional)
 
-## Installation
-See [setup instructions](https://banmanagement.com/docs/webui/install)
+### Quick Install
 
-## Development
+```bash
+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](https://nodejs.org/) LTS (v20 or v22)
+- [Docker](https://www.docker.com/) (for local MySQL database)
+
+### Quick Start
+
+```bash
+# Clone the repository
 git clone git@github.com:BanManagement/BanManager-WebUI.git
+cd BanManager-WebUI
+
+# Install dependencies
 npm install
-npm run setup
+
+# 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:
+
+```bash
+npm run seed:reset
+```
+
+### Running Tests
+
+```bash
+# 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](https://github.com/BanManagement/BanManager-WebUI/issues/new) 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](https://github.com/BanManagement/BanManager-WebUI/issues/new) or [join us on Discord](https://discord.gg/59bsgZB) to chat
 
 ## License
+
 Free to use under the [MIT](LICENSE)
 
 ## Screenshots
+
 Click to view
 
 ### Home
+
 [![Home](https://github.com/BanManagement/BanManager-WebUI/blob/assets/welcome.png?raw=true)](welcome.png)
 
 ### Player
+
 [![Player](https://github.com/BanManagement/BanManager-WebUI/blob/assets/player.png?raw=true)](player.png)
 
 ### Dashboard
+
 [![Dashboard](https://github.com/BanManagement/BanManager-WebUI/blob/assets/dashboard.png?raw=true)](dashboard.png)
 
 ### Appeal
+
 [![Appeal](https://github.com/BanManagement/BanManager-WebUI/blob/assets/appeal.png?raw=true)](appeal.png)
 
 ### Report
+
 [![Report](https://github.com/BanManagement/BanManager-WebUI/blob/assets/report.png?raw=true)](report.png)

docker-compose.yml

@@ -0,0 +1,25 @@
+services:
+  mysql:
+    image: mysql:8.0
+    container_name: banmanager-mysql
+    restart: unless-stopped
+    environment:
+      MYSQL_ROOT_PASSWORD: password
+      MYSQL_DATABASE: bm_local_dev
+    ports:
+      - "3306:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-ppassword"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    command:
+      - --character-set-server=utf8mb4
+      - --collation-server=utf8mb4_unicode_ci
+      - --default-authentication-plugin=mysql_native_password
+
+volumes:
+  mysql_data: