diff --git a/README.md b/README.md index e215bc4..e23b5d1 100644 --- 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). +
-## 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 + +
+ +--- + +## 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.