updated README.md

2026-02-10 17:40:30 -08:00 · 2026-02-07 12:23:26 -08:00 · 2026-02-07 12:23:26 -08:00 · fda510ca3e
commit fda510ca3e
parent 79b41409e5
1 changed files with 241 additions and 20 deletions
--- a/README.md
+++ b/README.md
@ -1,36 +1,257 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+<div align="center">

-## Getting Started
+# ⛏️ MC-Manager

-First, run the development server:
+**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
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open [http://localhost:3000](http://localhost:3000) and log in with your admin credentials.

-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+## 📁 Project Structure

-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+```
+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
+```

-## Learn More
+## 🔐 Permissions

-To learn more about Next.js, take a look at the following resources:
+Permissions follow a `resource:action` format. The Admin role receives `*:*` (full access).

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+| 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` |

-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+## 🐳 Docker Architecture

-## Deploy on Vercel
+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).

-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+**Volume layout per server:**

-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+```
+/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.