mc-manager/README.md

<div align="center">

# ⛏️ MC-Manager

**A full-stack web application for managing Minecraft server instances**

Built with Next.js 16 · React 19 · TypeScript · MongoDB · Docker

</div>

---

## Overview

MC-Manager is a self-hosted Minecraft server management panel that lets you create, configure, monitor, and control multiple Minecraft server instances — all from a modern dark-themed web UI. Each server runs as an isolated Docker container, giving you full control over lifecycle, configuration, backups, plugins, mods, and player management.

## ✨ Features

### Server Management
- **Multi-instance** — Run multiple Minecraft servers simultaneously, each in its own Docker container
- **Server types** — Vanilla, Bukkit (Paper/Spigot/Purpur), Forge, and Fabric
- **Lifecycle control** — Start, stop, restart, and delete server instances with real-time status tracking
- **Auto-start & auto-restart** — Configurable restart policies per server

### Live Console
- **Real-time log streaming** — Tail server stdout/stderr directly in the browser
- **Command execution** — Send commands to the server console from the UI

### Configuration
- **server.properties editor** — Edit Minecraft configuration per instance
- **JVM tuning** — Configure memory allocation (min/max heap) and custom JVM arguments
- **Port management** — Custom host port mappings for game and RCON ports

### Backups
- **Manual backups** — Create on-demand backups of world data
- **Scheduled backups** — Cron-based automated backups with configurable retention
- **Point-in-time restore** — Restore any backup to roll back a server's world

### Extensions
- **Plugins** (Bukkit-type servers) — Upload, install, remove, enable/disable plugin JARs
- **Mods** (Forge/Fabric servers) — Upload, install, remove, enable/disable mod JARs

### Player Management
- **Whitelist** — Add/remove players from the server whitelist
- **Operators** — Grant/revoke operator privileges
- **Bans** — Ban/unban players
- **Online players** — View currently connected players

### Security & Administration
- **Role-based access control** — Granular permissions (`resource:action` format) with wildcard support
- **Dual-token JWT auth** — 1-hour access tokens + 7-day refresh tokens in HTTP-only cookies
- **Mandatory 2FA** — Email-based two-factor authentication on every login
- **Account lockout** — Automatic lockout after 5 failed login attempts (30-minute cooldown)
- **Audit logging** — Every mutation is logged with previous/new values and client IP
- **Input sanitization** — All inputs sanitized server-side; parameterized database queries only

## 🛠️ Tech Stack

| Layer | Technology |
|---|---|
| **Framework** | [Next.js](https://nextjs.org) 16 (App Router) |
| **UI** | [React](https://react.dev) 19, [TypeScript](https://www.typescriptlang.org) 5 |
| **Styling** | [Tailwind CSS](https://tailwindcss.com) 4 |
| **Database** | [MongoDB](https://www.mongodb.com) via [Mongoose](https://mongoosejs.com) 9 |
| **Containers** | [Docker](https://www.docker.com) via [dockerode](https://github.com/apocas/dockerode) |
| **Auth** | JWT ([jsonwebtoken](https://github.com/auth0/node-jsonwebtoken)), [bcryptjs](https://github.com/dcodeIO/bcrypt.js) |
| **Email** | Microsoft Graph API + SMTP ([nodemailer](https://nodemailer.com)) fallback |
| **Scheduling** | [node-cron](https://github.com/node-cron/node-cron) |
| **Icons** | [Lucide React](https://lucide.dev) |

## 📋 Prerequisites

- **Node.js** 20+
- **MongoDB** 6+ (local or Atlas)
- **Docker Engine** with the Docker socket accessible (`/var/run/docker.sock`)
- **Docker image:** `itzg/minecraft-server` (pulled automatically, or specify a custom image per server)

## 🚀 Getting Started

### 1. Clone the repository

```bash
git clone https://github.com/your-org/mc-manager.git
cd mc-manager
```

### 2. Install dependencies

```bash
npm install
```

### 3. Configure environment variables

Create a `.env.local` file in the project root:

```env
# Database
MONGODB_URI=mongodb://localhost:27017/mc-manager

# Authentication
JWT_SECRET=your-secure-jwt-secret-here
JWT_REFRESH_SECRET=your-secure-refresh-secret-here
TWO_FACTOR_SECRET=your-secure-2fa-secret-here
NODE_ENV=development

# Docker
MC_SERVERS_PATH=/opt/mc-servers
DOCKER_SOCKET=/var/run/docker.sock

# Email — Microsoft Graph API (primary)
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
EMAIL_FROM=noreply@yourdomain.com

# Email — SMTP fallback
SMTP_HOST=smtp.yourdomain.com
SMTP_PORT=587
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password

# CORS (production)
ALLOWED_ORIGINS=https://your-domain.com
```

### 4. Prepare the server data directory

```bash
sudo mkdir -p /opt/mc-servers
sudo chown $USER:$USER /opt/mc-servers
```

### 5. Seed the database

Run the seed script to create default roles and the initial admin user:

```bash
npm run seed
```

You will be prompted to enter an email and password for the admin account.

### 6. Start the development server

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) and log in with your admin credentials.

## 📁 Project Structure

```
src/
├── app/                        # Next.js App Router
│   ├── (app)/                  # Authenticated app pages
│   │   ├── dashboard/          # Dashboard overview
│   │   ├── servers/            # Server list & detail pages
│   │   │   └── [id]/           # Per-server views
│   │   │       ├── backups/    #   Backup management
│   │   │       ├── configuration/ # server.properties & JVM config
│   │   │       ├── console/    #   Live console
│   │   │       ├── files/      #   File browser
│   │   │       ├── logs/       #   Log viewer
│   │   │       ├── mods/       #   Mod management (Forge/Fabric)
│   │   │       ├── players/    #   Player management
│   │   │       └── plugins/    #   Plugin management (Bukkit)
│   │   ├── users/              # User management
│   │   ├── roles/              # Role & permission management
│   │   └── audit/              # Audit log viewer
│   ├── api/                    # API routes (REST)
│   └── login/                  # Login page
├── components/                 # Shared UI components
│   ├── templates/              # Reusable CRUD templates
│   └── ui/                     # Base UI primitives
├── contexts/                   # React context providers
├── hooks/                      # Custom React hooks
├── lib/                        # Server-side utilities
│   ├── auth.ts                 # JWT, 2FA, sessions, permissions
│   ├── mongodb.ts              # Cached Mongoose connection
│   ├── models.ts               # Mongoose schemas & models
│   ├── docker.ts               # Docker client & container ops
│   ├── backup-scheduler.ts     # Cron-based backup scheduling
│   ├── audit.ts                # Audit log helpers
│   ├── input-validation.ts     # Sanitization & validation
│   ├── date-utils.ts           # Date formatting utilities
│   ├── email.ts                # Email dispatch (Graph + SMTP)
│   └── email-graph.ts          # Microsoft Graph API email client
└── types/                      # TypeScript interfaces
```

## 🔐 Permissions

Permissions follow a `resource:action` format. The Admin role receives `*:*` (full access).

| Resource | Actions |
|---|---|
| `servers` | `view`, `create`, `edit`, `delete`, `start`, `stop`, `restart`, `console` |
| `backups` | `view`, `create`, `restore`, `delete` |
| `plugins` | `view`, `install`, `remove`, `toggle` |
| `mods` | `view`, `install`, `remove`, `toggle` |
| `players` | `view`, `whitelist`, `op`, `ban` |
| `users` | `view`, `create`, `edit`, `delete` |
| `roles` | `view`, `create`, `edit`, `delete` |
| `audit` | `view` |

## 🐳 Docker Architecture

Each Minecraft server runs as an isolated Docker container using the [`itzg/minecraft-server`](https://docker-minecraft-server.readthedocs.io/) image (or a custom image).

**Volume layout per server:**

```
/opt/mc-servers/{serverId}/
├── server.properties       # Minecraft configuration
├── world/                  # World data (backed up)
├── plugins/                # Bukkit-type servers only
├── mods/                   # Forge/Fabric servers only
├── logs/                   # Server logs
└── backups/                # Backup archives
```

**Container naming convention:** `mc-{serverId}`

## 🎮 Server Types

| Type | Examples | Plugins | Mods |
|---|---|:---:|:---:|
| **Vanilla** | Official Mojang server | ✗ | ✗ |
| **Bukkit** | Paper, Spigot, Purpur | ✓ | ✗ |
| **Forge** | Forge mod loader | ✗ | ✓ |
| **Fabric** | Fabric mod loader | ✗ | ✓ |

## 📦 Scripts

| Command | Description |
|---|---|
| `npm run dev` | Start development server (port 3000) |
| `npm run build` | Create production build |
| `npm run start` | Start production server |
| `npm run lint` | Run ESLint |
| `npm run seed` | Seed database with default roles and admin user |

## 🔒 Security Highlights

- **Server-side authority** — All permission checks are enforced server-side; client-side checks are UI hints only
- **HTTP-only cookies** — Tokens are never exposed to JavaScript
- **Input sanitization** — All user input is sanitized via `sanitizeObject()` before processing
- **Parameterized queries** — No string concatenation in database queries
- **CORS enforcement** — Origin validation in production
- **Security headers** — `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, strict `Referrer-Policy`, and restrictive `Permissions-Policy`
- **Comprehensive audit trail** — Every create, update, and delete is logged with user info, client IP, and value diffs

## License

This project is private and not licensed for redistribution.