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.
- 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
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
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:
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: bridgeCopy 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 -dNote: 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.
# 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 -d1. Clone the repository
git clone https://github.com/ArtRuntime/Obsidian-Panel.git
cd Obsidian-Panel2. Create .env file
Create a .env file in the project root with your configuration (or copy from .env.example):
cp .env.example .envRequired 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-openjdkNote: If using an external MongoDB, replace
MONGO_URIwith your connection string (e.g.,mongodb://username:password@host:27017) and remove or stop themongoservice indocker-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
- Open http://localhost:5000
- First registered user becomes Admin
To stop:
docker compose downTo view logs:
docker compose logs -f obsidian-panelTo 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:
- Detect your existing installation
- Download the latest
alexbhai/obsidian-panelimage - Recreate the container while keeping your server data safe in persistent volumes
For Docker Compose users:
docker-compose pull
docker-compose up -dBackend (Node.js)
cd backend
npm install
npm run devFrontend (React)
cd frontend
npm install
npm run devFrontend dev server runs on http://localhost:5173
Backend dev server runs on http://localhost:5000
- 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.propertieswith a random unprivileged port, cryptographically random password, andbroadcast-rcon-to-ops=falseso 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

- 10+ Server Software Distributions: Native installer and version resolvers for NeoForge, Paper, Vanilla, Forge, Purpur, Fabric, Pufferfish, Quilt, Folia, and Arclight.

- 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
- 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

- Server Settings: Manage server RAM allocation, Java version selection, and storage providers

- Environment Configuration: Support for custom Java paths via
JAVA_X_HOMEenvironment variables - Hot Reload: Configuration updates apply without requiring container rebuilds
- 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

- Chunked Uploads: Support for large file uploads
- 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

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

- Unified Plugin Store: Search and install from Modrinth, Hangar (Paper), and Spiget (Spigot)
- One-Click Installation: Automatic plugin download and placement

- Updater UI: Dashboard notifications for panel updates

- Role-Based Access Control (RBAC): Create sub-admin accounts with granular permissions
- Permissions:
- 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

- 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
- 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
- Build Tool: Vite
- Framework: React 18+
- Styling: Tailwind CSS
- Icons: Lucide React
- Editor: Monaco Editor
- Routing: React Router 6
- Containerization: Docker multi-stage builds (Node.js Alpine)
- Java: OpenJDK 8, 17, 21, and 25 support
- Database: MongoDB
| 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 |
- 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
- 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
- Port Conflicts: Ensure your selected Web UI port is available
- MongoDB: Verify connection string and network accessibility
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:latestpodman 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:latestThe 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 updatesconsole_log- Live log streamingstats- Real-time CPU, RAM, disk, and network stats
MIT License - feel free to use for personal or commercial projects.


