Skip to content

About

The Most Light weight and easy to use self hosted minecraft management panel focus to manage a single server

Topics

Resources

Stars

7 stars

Watchers

0 watching

Forks

Repository files navigation

Obsidian Panel

Docker Hub Docker Pulls Docker Image Version

Obsidian Panel is a modern, high-performance Minecraft Server Management Panel built with Node.js and React. Designed to manage a single server with maximum efficiency and elegance, it provides a powerful web interface to control your Minecraft server, manage files, schedule backups, edit server properties, and monitor performance in real-time.

Obsidian Panel Interface

Installation

Prerequisites

  • Docker or Podman (installed and running)
  • MongoDB (running locally or remote connection URL)
  • RAM: Minimum 2GB (4GB+ recommended)
  • OS: Linux (Ubuntu/Debian/Alpine recommended)
  • Disk: 5GB+ for server files and backups

Method 1: Automated Install Script (Recommended)

The easiest way to install Obsidian Panel with a single command:

bash <(curl -s https://raw.githubusercontent.com/ArtRuntime/Obsidian-Panel/master/install.sh)

What it does:

  • Checks Docker or Podman installation and starts the service if needed
  • Prompts for MongoDB URI (required)
  • Prompts for Web UI Port (default: 5000)
  • Builds/Pulls container image with Java 8, 17, 21, and 25 pre-installed
  • Exposes Web UI port, Minecraft Java (25565), Bedrock (19132), and Voice Chat (24454) with option for extra ports
  • Creates and starts the container with proper volume mappings (obsidian-data)

Access the panel:

  • Open http://localhost:5000 or http://YOUR_SERVER_IP:5000 (or your custom Web UI port)
  • First registered user becomes Admin

Method 2: Docker Compose (Direct Copy & Deploy)

You can directly copy the docker-compose.yml below to deploy Obsidian Panel using the official image on Docker Hub (alexbhai/obsidian-panel) and its attached MongoDB database in Portainer, CasaOS, Dockge, Coolify, or any terminal without needing to clone the repository or build from source:

docker-compose.yml

services:
  # MongoDB Database Service
  mongo:
    image: mongo:7.0
    container_name: obsidian-mongo
    restart: unless-stopped
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db
    networks:
      - obsidian-network

  # Obsidian Panel (Serves Web UI + API on port 5000)
  obsidian-panel:
    image: alexbhai/obsidian-panel:latest
    container_name: obsidian-panel
    depends_on:
      - mongo
    ports:
      - "5000:5000"         # Web Panel (UI + API + WebSocket)
      - "25565:25565"       # Minecraft Java Edition
      - "25565:25565/udp"
      - "19132:19132"       # Minecraft Bedrock Edition
      - "19132:19132/udp"
      - "24454:24454"       # Voice Chat / Extra UDP port
      - "24454:24454/udp"
    environment:
      # Database
      - MONGO_URI=${MONGO_URI:-mongodb://mongo:27017}
      - MONGO_DB_NAME=${MONGO_DB_NAME:-obsidian_panel}
      - SESSION_SECRET=${SESSION_SECRET:-change_me_in_production}

      # Server Configuration
      - PORT=5000
      - MC_SERVER_BASE_PATH=${MC_SERVER_BASE_PATH:-/minecraft_server}
      - TEMP_BACKUP_PATH=${TEMP_BACKUP_PATH:-/tmp/obsidian_backups}
    volumes:
      - minecraft_data:/minecraft_server
      - backup_temp:/tmp/obsidian_backups
    restart: unless-stopped
    networks:
      - obsidian-network

# Named volumes for data persistence
volumes:
  mongo_data:
    driver: local
  minecraft_data:
    driver: local
  backup_temp:
    driver: local

# Network for service communication
networks:
  obsidian-network:
    driver: bridge

One-Command Terminal Deployment

Copy and paste this single command into your terminal to generate docker-compose.yml and spin up the panel immediately:

cat << 'EOF' > docker-compose.yml
services:
  mongo:
    image: mongo:7.0
    container_name: obsidian-mongo
    restart: unless-stopped
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db
    networks:
      - obsidian-network

  obsidian-panel:
    image: alexbhai/obsidian-panel:latest
    container_name: obsidian-panel
    depends_on:
      - mongo
    ports:
      - "5000:5000"
      - "25565:25565"
      - "25565:25565/udp"
      - "19132:19132"
      - "19132:19132/udp"
      - "24454:24454"
      - "24454:24454/udp"
    environment:
      - MONGO_URI=mongodb://mongo:27017
      - MONGO_DB_NAME=obsidian_panel
      - SESSION_SECRET=change_me_in_production
      - PORT=5000
      - MC_SERVER_BASE_PATH=/minecraft_server
      - TEMP_BACKUP_PATH=/tmp/obsidian_backups
    volumes:
      - minecraft_data:/minecraft_server
      - backup_temp:/tmp/obsidian_backups
    restart: unless-stopped
    networks:
      - obsidian-network

volumes:
  mongo_data:
    driver: local
  minecraft_data:
    driver: local
  backup_temp:
    driver: local

networks:
  obsidian-network:
    driver: bridge
EOF

docker compose up -d

Note: The official pre-built image (alexbhai/obsidian-panel:latest) includes Java 8, 17, 21, and 25 pre-installed and connects to the attached MongoDB 7 service automatically.

Alternative: Download docker-compose.yml via curl

# 1. Download docker-compose.yml
curl -O https://raw.githubusercontent.com/ArtRuntime/Obsidian-Panel/master/docker-compose.yml

# 2. (Optional) Create .env file with custom secret & settings
cat <<EOF > .env
PORT=5000
SESSION_SECRET=$(openssl rand -hex 32)
EOF

# 3. Pull image and start services
docker compose up -d

Manual Clone & Custom Setup

1. Clone the repository

git clone https://github.com/ArtRuntime/Obsidian-Panel.git
cd Obsidian-Panel

2. Create .env file

Create a .env file in the project root with your configuration (or copy from .env.example):

cp .env.example .env

Required variables:

# Database (Required)
MONGO_URI=mongodb://mongo:27017
MONGO_DB_NAME=obsidian_panel

# Server Configuration
PORT=5000
MC_SERVER_BASE_PATH=/minecraft_server
TEMP_BACKUP_PATH=/tmp/obsidian_backups
SESSION_SECRET=change_this_to_a_secure_random_string

# Optional: Custom Java paths
# JAVA_8_HOME=/usr/lib/jvm/java-1.8-openjdk
# JAVA_17_HOME=/usr/lib/jvm/java-17-openjdk
# JAVA_21_HOME=/usr/lib/jvm/java-21-openjdk
# JAVA_25_HOME=/usr/lib/jvm/java-25-openjdk

Note: If using an external MongoDB, replace MONGO_URI with your connection string (e.g., mongodb://username:password@host:27017) and remove or stop the mongo service in docker-compose.yml.

3. Start with Docker Compose

docker compose up -d

(If building from source locally instead of pulling the pre-built image, uncomment the build: block under obsidian-panel in docker-compose.yml)

4. Access the panel

To stop:

docker compose down

To view logs:

docker compose logs -f obsidian-panel

Updating the Panel

To update to the latest version, run the installation script again:

bash <(curl -s https://raw.githubusercontent.com/ArtRuntime/Obsidian-Panel/master/install.sh)

The script will:

  1. Detect your existing installation
  2. Download the latest alexbhai/obsidian-panel image
  3. Recreate the container while keeping your server data safe in persistent volumes

For Docker Compose users:

docker-compose pull
docker-compose up -d

Development Setup

Backend (Node.js)

cd backend
npm install
npm run dev

Frontend (React)

cd frontend
npm install
npm run dev

Frontend dev server runs on http://localhost:5173
Backend dev server runs on http://localhost:5000

Features

Server Management

  • Sleep Mode & Join-to-Start: Inspired by lazymc, automatically shuts down idle servers when 0 players are online to save CPU and RAM. When asleep, a lightweight TCP listener serves a configurable Sleeping MOTD on port 25565. When a player connects, it gracefully wakes the server up, displays a configurable Starting MOTD to pinging clients, and notifies the waking player with a customizable message.
  • Silent Minecraft RCON Integration: Automatically configures server.properties with a random unprivileged port, cryptographically random password, and broadcast-rcon-to-ops=false so RCON queries never spam your console or log history. Live player lists and player counts sync seamlessly to the panel.
  • Live Console: Real-time log streaming via Socket.IO with 5000-line history buffer
    Server Console
  • 10+ Server Software Distributions: Native installer and version resolvers for NeoForge, Paper, Vanilla, Forge, Purpur, Fabric, Pufferfish, Quilt, Folia, and Arclight.
    Multi-Version Support
  • Smart Java Detection: Automatic discovery of Java 8, 17, 21, and 25 installations with version verification
  • Power Controls: Start, Stop, Restart, Put to Sleep, and Force Kill with status tracking

Game Settings Editor

  • Visual properties editor: Dynamic tabs for Core, Network, World, Performance, Players & Security, Resource Pack, and Advanced rules
  • Server Icon Manager: Upload any image to automatically convert and apply a 64x64 PNG server-icon.png
    Game Settings

Configuration

  • Server Settings: Manage server RAM allocation, Java version selection, and storage providers
    Server Settings
  • Environment Configuration: Support for custom Java paths via JAVA_X_HOME environment variables
  • Hot Reload: Configuration updates apply without requiring container rebuilds

Server Templates

  • Template System: Deploy pre-configured Minecraft server templates and world setups
    Server Templates

File Manager

  • Full-featured File Browser: Upload, download, edit, and delete files with drag-and-drop support
  • Built-in Code Editor: Monaco editor for direct file editing
  • Archive Extraction & Password Support: Support for ZIP, TAR, 7Z, and RAR with password decryption
  • Remote cURL Downloader: Download direct files into server directory with custom headers, automatic filename detection, and file collision auto-incrementing
    File Manager
    Drag and Drop
    Editor UI
    Remote File Downloader
  • Chunked Uploads: Support for large file uploads

Backup System

  • Cloud Storage Integration: Built-in support for Buzzheavier and GoFile providers
  • Automated Scheduling: Cron-based backup scheduler (minutely, hourly, daily, custom expressions)
  • One-Click Restore: Restore from any backup with safeguards
  • Encrypted Archives: Password-protected backup compression
    Backup System
    Backup Note Feature

Task Scheduler

  • Automated Tasks: Schedule commands, server restarts, and automatic backups with cron syntax or preset intervals
    Task Scheduler

Plugin Management

  • Unified Plugin Store: Search and install from Modrinth, Hangar (Paper), and Spiget (Spigot)
  • One-Click Installation: Automatic plugin download and placement
    Plugin Store
    Plugin Store Installation
  • Updater UI: Dashboard notifications for panel updates
    Updater UI

User Management

  • Role-Based Access Control (RBAC): Create sub-admin accounts with granular permissions
  • Permissions:
    • Files: View, Edit, Upload/Create, Delete
    • Backups: Create, Restore, Delete, Settings
    • Power: Start/Stop/Restart
    • Console: Command Execution
      User Management

User Experience

  • Responsive Design: Mobile and desktop friendly layout with collapsible navigation
  • Obsidian Dark Theme: Glassmorphism design with clean input controls
  • Real-time Statistics: WebSocket-powered CPU, RAM, storage, and network bandwidth monitoring
    Profile Settings

Security

  • Rate Limiting: Protection with configurable IP limits
  • Authentication: Bcrypt password hashing with session tokens
  • Path Validation: Strict directory traversal prevention
  • Session Management: MongoDB-backed sessions with secure cookies

Tech Stack

Backend (Node.js)

  • Runtime: Node.js 20+
  • Framework: Express.js
  • Database: MongoDB (Mongoose ODM)
  • Real-time: Socket.IO
  • Security: Helmet, Rate Limit, Bcrypt, CORS
  • Process Tools: Child Process, ImageMagick, p7zip/7zip, cURL

Frontend (React)

  • Build Tool: Vite
  • Framework: React 18+
  • Styling: Tailwind CSS
  • Icons: Lucide React
  • Editor: Monaco Editor
  • Routing: React Router 6

Infrastructure

  • Containerization: Docker multi-stage builds (Node.js Alpine)
  • Java: OpenJDK 8, 17, 21, and 25 support
  • Database: MongoDB

Configuration

Environment Variables

Variable Default Description
PORT 5000 Web UI and backend server port
MONGO_URI mongodb://localhost:27017 MongoDB connection string
MONGO_DB_NAME obsidian_panel Database name
SESSION_SECRET secret Secret key for session signing
MC_SERVER_BASE_PATH /minecraft_server Minecraft server files location
TEMP_BACKUP_PATH /tmp/obsidian_backups Temporary backup storage
JAVA_8_HOME Auto-detected Override Java 8 location
JAVA_17_HOME Auto-detected Override Java 17 location
JAVA_21_HOME Auto-detected Override Java 21 location
JAVA_25_HOME Auto-detected Override Java 25 location

Troubleshooting

Server Won't Start

  • Check Java: Ensure correct Java version is selected for your server jar
  • Verify Logs: Check live console for startup crash tracebacks
  • Backend Logs: Run docker logs obsidian-panel

Archive Extraction Issues

  • Password Error: Ensure password is provided if archive is encrypted
  • Binary Check: Container includes 7z/7za/unzip tools for ZIP, 7Z, RAR, and TAR archives

Connection Issues

  • Port Conflicts: Ensure your selected Web UI port is available
  • MongoDB: Verify connection string and network accessibility

Container Deployment

Docker Run

docker run -d \
  --name obsidian-panel \
  --restart unless-stopped \
  -p 5000:5000/tcp \
  -p 25565:25565/tcp -p 25565:25565/udp \
  -p 19132:19132/tcp -p 19132:19132/udp \
  -p 24454:24454/tcp -p 24454:24454/udp \
  -e MONGO_URI="mongodb://your-mongo-host:27017" \
  -e MONGO_DB_NAME="obsidian-panel" \
  -e PORT="5000" \
  -e SESSION_SECRET="your_secure_random_secret_key" \
  -v obsidian-data:/minecraft_server:rw \
  docker.io/alexbhai/obsidian-panel:latest

Podman Run

podman run -d \
  --name obsidian-panel \
  --restart unless-stopped \
  -p 5000:5000/tcp \
  -p 25565:25565/tcp -p 25565:25565/udp \
  -p 19132:19132/tcp -p 19132:19132/udp \
  -p 24454:24454/tcp -p 24454:24454/udp \
  -e MONGO_URI="mongodb://your-mongo-host:27017" \
  -e MONGO_DB_NAME="obsidian-panel" \
  -e PORT="5000" \
  -e SESSION_SECRET="your_secure_random_secret_key" \
  -v obsidian-data:/minecraft_server:rw \
  docker.io/alexbhai/obsidian-panel:latest

API Documentation

The backend provides RESTful API endpoints:

  • Authentication: /api/auth (login, register, logout)
  • Server Control: /api/control (start, stop, restart, kill, public-ip)
  • File Management: /api/control/files/* (list, read, write, upload, extract, remote-download, server-icon)
  • Backups: /api/backups (create, restore, delete, configure)
  • Plugins: /api/plugins (search, install)
  • Users: /api/users (CRUD operations)

WebSocket events:

  • status - Server status updates
  • console_log - Live log streaming
  • stats - Real-time CPU, RAM, disk, and network stats

License

MIT License - feel free to use for personal or commercial projects.

About

The Most Light weight and easy to use self hosted minecraft management panel focus to manage a single server

Topics

Resources

Stars

7 stars

Watchers

0 watching

Forks

Sponsor this project

Contributors

Languages