minepanel-site.json

{
  "updatedAt": "2026-08-13",
  "meta": {
    "title": "MinePanel - Self-Hosted Minecraft Server Manager",
    "tagline": "Self-hosted Minecraft server management, the right way.",
    "description": "A single <code>docker compose up</code> brings up the entire stack on your own machine. No external services. No cloud lock-in. Full control.",
    "github": "https://github.com/MinePanelProject"
  },
  "features": [
    { "icon": "⚡", "title": "One-Command Deploy", "description": "The full stack - backend, database and MC servers - runs on your hardware with a single command. Zero external dependencies." },
    { "icon": "🐳", "title": "Docker-Native", "description": "Each Minecraft server runs in its own isolated container, controlled through a local Docker socket (rootful by default; rootless via DOCKER_SOCKET)." },
    { "icon": "🔗", "title": "Multi-Backend", "description": "Point the frontend at any number of independent self-hosted backend instances. Cross-origin auth design is under review (see SPEC.md §8.5).", "coming": true, "color": "yellow" },
    { "icon": "🛡️", "title": "Role System", "description": "Three roles: ADMIN, MOD, USER. MODs get granular per-server permissions without full admin access - built-in PBAC." },
    { "icon": "📡", "title": "Real-Time Events", "description": "Host metrics (CPU, RAM, disk) pushed to admins via WebSocket. Live per-server stats, console logs, and player events land in later phases." },
    { "icon": "🔒", "title": "Security First", "description": "JWT via HttpOnly cookies, rate limiting, Helmet security headers, input validation, and Docker socket guardrails." },
    { "icon": "📱", "title": "Mobile App", "description": "KMP app for iOS and Android. Not just for admins - players get their own portal: server status, access requests, push notifications, and profile.", "coming": true, "color": "aqua" },
    { "icon": "👤", "title": "Player Portal", "description": "Unlike other MC panels, MinePanel is built for players too. Browse your servers, request access, view your Minecraft profile and playtime - all in one place.", "coming": true, "color": "yellow" }
  ],
  "techStack": [
    { "label": "TypeScript 5", "type": "lang" },
    { "label": "NestJS v11", "type": "lang" },
    { "label": "Bun 1.3", "type": "lang" },
    { "label": "PostgreSQL 16", "type": "db" },
    { "label": "Drizzle ORM", "type": "db" },
    { "label": "Docker / Dockerode", "type": "infra" },
    { "label": "Caddy (auto-HTTPS)", "type": "infra" },
    { "label": "JWT · HttpOnly Cookies", "type": "auth" },
    { "label": "2FA · TOTP", "type": "auth" },
    { "label": "Socket.IO (WebSocket)", "type": "lang" },
    { "label": "Helmet · Throttler", "type": "auth" },
    { "label": "RCON via docker exec (rcon-cli)", "type": "infra" },
    { "label": "GitHub Actions CI/CD", "type": "infra" }
  ],
  "team": [
    { "name": "Cristian", "username": "okazakee", "role": "Founder / Full-stack", "github": "https://github.com/okazakee" },
    { "name": "Marco", "username": "MarcoBllfr", "role": "Mobile Dev", "github": "https://github.com/okazakee" },
    { "name": "Giulia", "username": "hikarii2", "role": "Designer UI/UX", "github": "https://github.com/hikarii2" }
  ],
  "phases": [
    {
      "id": "1",
      "label": "Phase 1",
      "name": "Foundation — v1.0",
      "status": "completed",
      "description": "The core deployable release. Everything needed to spin up and manage Minecraft servers from a single docker-compose on your own machine.",
      "progress": 100,
      "progressLabel": "100% complete",
      "items": [
        { "text": "JWT auth via HttpOnly cookies", "done": true },
        { "text": "Register & login endpoints", "done": true },
        { "text": "Token refresh & logout", "done": true },
        { "text": "Session management (list & revoke)", "done": true },
        { "text": "Password change", "done": true },
        { "text": "Rate limiting (global 10/min + login/2FA route throttles)", "done": true },
        { "text": "Security hardening (Helmet, validation, DTO constraints)", "done": true },
        { "text": "Health check endpoint", "done": true },
        { "text": "First-run setup wizard (admin creation)", "done": true },
        { "text": "Roles guard (ADMIN / MOD / USER)", "done": true },
        { "text": "Admin approval mode (PENDING status, REQUIRE_ADMIN_APPROVAL)", "done": true },
        { "text": "2FA — TOTP with backup codes", "done": true },
        { "text": "Admin user management (approve, ban, change role, reset password)", "done": true },
        { "text": "Refresh token rotation", "done": true },
        { "text": "mustChangePassword enforcement on temp password login", "done": true },
        { "text": "Last admin protection", "done": true },
        { "text": "Account enumeration prevention", "done": true },
        { "text": "Docker service (socket, container CRUD)", "done": true },
        { "text": "Server lifecycle (create, start, stop, restart, delete)", "done": true },
        { "text": "Graceful shutdown with RCON warning", "done": true },
        { "text": "Resource checks (RAM & disk guardrails)", "done": true },
        { "text": "Startup reconciliation (DB vs Docker state sync)", "done": true },
        { "text": "Concurrent operation protection (Postgres atomic CAS)", "done": true },
        { "text": "Host metrics via WebSocket (CPU, RAM, disk)", "done": true },
        { "text": "Unit + integration tests", "done": true },
        { "text": "CI/CD pipeline (GitHub Actions \u2192 GHCR)", "done": true },
        { "text": "Docker deployment (docker-compose + Caddy auto-HTTPS, migrations on boot)", "done": true }
      ]
    },
    {
      "id": "1.5",
      "label": "Phase 1.5",
      "name": "Access Control & OAuth",
      "status": "wip",
      "description": "Fine-grained access control, social login, Minecraft account linking, and per-server visibility modes.",
      "progress": 50,
      "progressLabel": "50% — authorization spine + Google OAuth complete",
      "items": [
        { "text": "Google OAuth (frontend-initiated token flow)", "done": true },
        { "text": "GitHub OAuth (frontend-initiated token flow)", "done": false },
        { "text": "Minecraft account linking (Microsoft OAuth premium flow)", "done": false },
        { "text": "Offline player UUID linking", "done": false },
        { "text": "Magic link login (passwordless — requires SMTP)", "done": false },
        { "text": "Invite tokens & registration approval modes", "done": false },
        { "text": "Server visibility: OPEN / REQUEST / PRIVATE", "done": true },
        { "text": "Access request & approval workflow", "done": true },
        { "text": "MOD granular permissions (PBAC per server)", "done": true },
        { "text": "PermissionsGuard + @RequiresPermission decorator", "done": true }
      ]
    },
    {
      "id": "2",
      "label": "Phase 2",
      "name": "Developer Platform",
      "status": "planned",
      "description": "Audit log, API key authentication for programmatic access, and outbound webhooks for external integrations.",
      "progress": 0,
      "progressLabel": "0% — starts after Phase 1.5",
      "items": [
        { "text": "Audit log (interceptor, append-only, filterable)", "done": false },
        { "text": "API key auth (mpk_ prefix, hashed, Bearer header)", "done": false },
        { "text": "Outbound webhooks (HMAC-signed, retry policy)", "done": false },
        { "text": "Subscribable events (server.crashed, backup.completed, \u2026)", "done": false },
        { "text": "System event feed (DOCKER / SERVERS / SCHEDULER)", "done": false },
        { "text": "Docker image pull via panel UI", "done": false },
        { "text": "GET /system/stats admin endpoint", "done": false },
        { "text": "Frontend \u2014 minepanel-pwa repo kickoff", "done": false }
      ]
    },
    {
      "id": "3",
      "label": "Phase 3",
      "name": "Operations & Management",
      "status": "planned",
      "description": "The full operations suite — everything you'd expect from a mature server panel, all running locally on your hardware.",
      "progress": 0,
      "progressLabel": "0% — starts after Phase 2",
      "items": [
        { "text": "WebSocket real-time (logs, player events, server stats)", "done": false },
        { "text": "RCON service + connection pool", "done": false },
        { "text": "Server console (send commands via RCON / docker exec)", "done": false },
        { "text": "Backup system (manual + restore + streaming download)", "done": false },
        { "text": "Retention policy (auto-delete oldest backups)", "done": false },
        { "text": "Scheduled tasks (AUTO_BACKUP, AUTO_RESTART — cron)", "done": false },
        { "text": "In-panel notifications (crash, high RAM, low disk)", "done": false },
        { "text": "Discord webhook notifications per server", "done": false },
        { "text": "Plugin marketplace (Modrinth + Hangar APIs)", "done": false },
        { "text": "Plugin install, update, enable/disable", "done": false },
        { "text": "Plugin config file editor", "done": false },
        { "text": "File manager (browse, edit, upload, download)", "done": false },
        { "text": "Path-traversal protection", "done": false },
        { "text": "Player management (whitelist, bans, ops, kick)", "done": false },
        { "text": "Timed bans with auto-expiry via RCON pardon", "done": false },
        { "text": "UUID resolution (Mojang API + offline UUID.v3)", "done": false },
        { "text": "Admin permissions dashboard (PBAC UI)", "done": false }
      ]
    },
    {
      "id": "4",
      "label": "Phase 4",
      "name": "Server Wizard & Presets",
      "status": "future",
      "description": "Polished server creation flow — Quick Start presets, advanced mode, and a mod picker for Forge/Fabric servers. The RPG \"class selection\" of server creation.",
      "items": [
        { "text": "Quick Start presets (Survival SMP, Creative, Minigame, \u2026)", "done": false },
        { "text": "Advanced creation mode (all fields exposed)", "done": false },
        { "text": "Mod picker (Modrinth + CurseForge for Forge/Fabric)", "done": false },
        { "text": "Mod-loader compatibility validation", "done": false },
        { "text": "Pre-install mods before first server start", "done": false },
        { "text": "ServerMod tracking in DB", "done": false }
      ]
    },
    {
      "id": "5",
      "label": "Phase 5",
      "name": "Networking & Bedrock",
      "status": "future",
      "description": "Network multiple servers through a Velocity proxy with auto-generated config, and add support for Bedrock Edition players via GeyserMC or standalone bedrock servers.",
      "items": [
        { "text": "Velocity proxy (auto-generated velocity.toml)", "done": false },
        { "text": "Backend server registration in proxy", "done": false },
        { "text": "Modern forwarding auto-patch for Paper/Purpur", "done": false },
        { "text": "Proxy start/stop/log events via WebSocket", "done": false },
        { "text": "GeyserMC plugin support (Bedrock via plugin)", "done": false },
        { "text": "Standalone Bedrock server (itzg/minecraft-bedrock-server)", "done": false }
      ]
    }
  ]
}