Architecture

Overview

Components

Frontend (Next.js)

• Tech: Next.js 14, React 18, TypeScript, TailwindCSS, shadcn/ui
• Role: Web interface, API calls, real-time updates

Backend (NestJS)

• Tech: NestJS, TypeScript, Passport.js, bcrypt
• Role: REST API, Docker management, authentication

Docker Integration

Backend communicates via /var/run/docker.sock to:

• Create/start/stop containers
• Read logs
• Execute commands (RCON)
• Monitor resources

Data Flow

Creating a Server

Server Container

Each server uses itzg/docker-minecraft-server:

services:
  my-server:
    image: itzg/minecraft-server:latest
    environment:
      EULA: 'TRUE'
      TYPE: 'PAPER'
      VERSION: '1.20.1'
      MEMORY: '2G'
    ports:
      - '25565:25565'
    volumes:
      - ./mc-data:/data

Directory Structure

minepanel/
├── docker-compose.yml
├── .env
├── data/
│   └── minepanel.db      # SQLite database
└── servers/
    ├── server-1/
    │   ├── mc-data/      # World, plugins, mods
    │   │   └── worlds/   # World sources (folders, zip, tar)
    │   └── backups/
    └── server-2/

Security

• Passwords: bcrypt (12 rounds)
• Sessions: JWT in httpOnly cookies
• CORS: Controlled via FRONTEND_URL

Docker Socket

⚠️ Docker socket = root access. Only trusted users should access Minepanel.

Optional: Use Docker Socket Proxy for additional security.

BASE_DIR Explained

When Minepanel (in a container) creates Minecraft containers, volume paths are interpreted from the host:

# Without BASE_DIR (fails)
volumes:
  - ./mc-data:/data  # Docker looks on HOST, not inside Minepanel container

# With BASE_DIR (works)
environment:
  - BASE_DIR=/home/user/minepanel
volumes:
  - /home/user/minepanel/servers/my-server/mc-data:/data

This is the same pattern used by Portainer, Yacht, and other Docker management panels.

Tech Stack

Layer	Technology	Why
Frontend	Next.js	SSR, great DX
Backend	NestJS	TypeScript native, modular
Database	SQLite	Simple, no setup
Containers	Docker	Isolation, portability
MC Images	itzg/minecraft-server	Most popular, well maintained

Related

• Development - Contributing
• Configuration - Settings
• Features - Capabilities