Installation Guide

This guide covers different installation methods for Minepanel, from simple to advanced setups.

Installation Methods

Choose the method that best fits your needs:

Quick Install - Recommended for most users
From Source - Clone the repository
Split Services - Separate frontend/backend for reverse proxies
Development Setup - For contributors and developers

Quick Install

The fastest way to get started. Perfect for trying out Minepanel or running on a local network.

Cross-Platform

This configuration works on all operating systems (Linux, macOS, Windows). Variables with :- syntax provide sensible defaults that work everywhere.

Step 1: Create docker-compose.yml

yaml

services:
  minepanel:
    image: ketbom/minepanel:latest
    ports:
      - "${BACKEND_PORT:-8091}:8091"
      - "${FRONTEND_PORT:-3000}:3000"
    environment:
      # Backend Configuration
      - SERVERS_DIR=/app/servers
      - FRONTEND_URL=${FRONTEND_URL:-http://localhost:3000}
      - JWT_SECRET=${JWT_SECRET} # Generate with: openssl rand -base64 32
      - CLIENT_PASSWORD=${CLIENT_PASSWORD:-admin}
      - CLIENT_USERNAME=${CLIENT_USERNAME:-admin}

      # Frontend Configuration
      - NEXT_PUBLIC_FILEBROWSER_URL=${NEXT_PUBLIC_FILEBROWSER_URL:-http://localhost:8080}
      - NEXT_PUBLIC_BACKEND_URL=${NEXT_PUBLIC_BACKEND_URL:-http://localhost:8091}
      - NEXT_PUBLIC_DEFAULT_LANGUAGE=${NEXT_PUBLIC_DEFAULT_LANGUAGE:-en}
    volumes:
      - ${SERVERS_DIR:-./servers}:/app/servers
      - /var/run/docker.sock:/var/run/docker.sock
      - ${DATA_DIR:-./data}:/app/data
    restart: always

  filebrowser:
    image: hurlenko/filebrowser
    ports:
      - "${FILEBROWSER_PORT:-8080}:8080"
    volumes:
      - ${SERVERS_DIR:-./servers}:/data
      - ${FILEBROWSER_DIR:-./filebrowser-data}:/config
    environment:
      - FB_BASEURL=/
    restart: always

Step 2: Launch

bash

# Create required directories
mkdir -p servers filebrowser-data data

# Generate JWT secret
export JWT_SECRET=$(openssl rand -base64 32)

# Start services
docker compose up -d

Environment Variables

Use a .env file to customize directories, ports, and other settings without modifying docker-compose.yml:

bash

# .env file
JWT_SECRET=your_generated_secret
SERVERS_DIR=./servers
DATA_DIR=./data
FILEBROWSER_DIR=./filebrowser-data

See Configuration Guide for all available variables.

Install from Source

Clone the repository for the latest development version or to modify the code.

bash

# Clone repository
git clone https://github.com/Ketbome/minepanel.git
cd minepanel

# Create required directories
mkdir -p servers filebrowser-data data

# Generate JWT secret (optional, can use .env)
export JWT_SECRET=$(openssl rand -base64 32)

# Start services
docker compose up -d

Update to Latest

bash

cd minepanel
git pull origin main
docker compose pull
docker compose up -d

Split Services Installation

Use this method if you want to:

Use a reverse proxy (nginx-proxy, Traefik, Caddy)
Have separate domains for frontend/backend
Add SSL certificates with Let's Encrypt
Scale services independently

Using docker-compose.split.yml

bash

git clone https://github.com/Ketbome/minepanel.git
cd minepanel

# Create required directories
mkdir -p servers filebrowser-data data

# Generate JWT secret
export JWT_SECRET=$(openssl rand -base64 32)

# Start services
docker compose -f docker-compose.split.yml up -d

This exposes:

Backend: Port 9090
Frontend: Port 3000
Filebrowser: Port 8080

With nginx-proxy + Let's Encrypt

Perfect for production deployments with SSL certificates.

Step 1: Setup nginx-proxy

First, set up nginx-proxy with Let's Encrypt companion:

yaml

# nginx-proxy/docker-compose.yml
version: "3"

services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - ./certs:/etc/nginx/certs
      - ./vhost:/etc/nginx/vhost.d
      - ./html:/usr/share/nginx/html
    restart: always

  letsencrypt:
    image: nginxproxy/acme-companion
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./certs:/etc/nginx/certs
      - ./vhost:/etc/nginx/vhost.d
      - ./html:/usr/share/nginx/html
      - ./acme:/etc/acme.sh
    environment:
      - DEFAULT_EMAIL=your-email@example.com
    restart: always

networks:
  default:
    name: nginx-proxy
    external: false

bash

cd nginx-proxy
docker compose up -d

Step 2: Configure Minepanel

Modify docker-compose.split.yml:

yaml

networks:
  default:
    name: nginx-proxy
    external: true

services:
  frontend:
    image: ketbom/minepanel-frontend:latest
    expose:
      - 3000
    environment:
      - VIRTUAL_HOST=minepanel.yourdomain.com
      - VIRTUAL_PORT=3000
      - LETSENCRYPT_HOST=minepanel.yourdomain.com
      - LETSENCRYPT_EMAIL=your-email@example.com
      - NEXT_PUBLIC_BACKEND_URL=https://api.yourdomain.com
      - NEXT_PUBLIC_FILEBROWSER_URL=https://files.yourdomain.com
      - NEXT_PUBLIC_DEFAULT_LANGUAGE=en
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: always

  backend:
    image: ketbom/minepanel-backend:latest
    expose:
      - 8091
    environment:
      - VIRTUAL_HOST=api.yourdomain.com
      - VIRTUAL_PORT=8091
      - LETSENCRYPT_HOST=api.yourdomain.com
      - LETSENCRYPT_EMAIL=your-email@example.com
      - SERVERS_DIR=/app/servers
      - FRONTEND_URL=https://minepanel.yourdomain.com
      - CLIENT_PASSWORD=admin
      - CLIENT_USERNAME=admin
      - DEFAULT_LANGUAGE=en
      - JWT_SECRET=
    volumes:
      - ./servers:/app/servers
      - /var/run/docker.sock:/var/run/docker.sock
    restart: always

  filebrowser:
    image: hurlenko/filebrowser
    expose:
      - 8080
    environment:
      - VIRTUAL_HOST=files.yourdomain.com
      - VIRTUAL_PORT=8080
      - LETSENCRYPT_HOST=files.yourdomain.com
      - LETSENCRYPT_EMAIL=your-email@example.com
      - FB_BASEURL=/
    volumes:
      - ./servers:/data
      - ./filebrowser-data:/config
    restart: always

DNS Configuration

Make sure your domains point to your server's IP address before starting:

minepanel.yourdomain.com → Your server IP
api.yourdomain.com → Your server IP
files.yourdomain.com → Your server IP

bash

docker compose -f docker-compose.split.yml up -d

Development Setup

For contributors or those who want to modify the code.

Prerequisites

Node.js 18+ and npm
Docker and Docker Compose
Git

Setup

bash

# Clone repository
git clone https://github.com/Ketbome/minepanel.git
cd minepanel

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

Run in Development Mode

Terminal 1 - Backend:

bash

cd backend
npm run start:dev

Terminal 2 - Frontend:

bash

cd frontend
npm run dev

Terminal 3 - Filebrowser (optional):

bash

docker run -d \
  --name filebrowser \
  -p 8080:8080 \
  -v $(pwd)/servers:/data \
  hurlenko/filebrowser

Now you can access:

Build Custom Docker Image

bash

# Build single-arch image
docker build -t minepanel:custom .

# Test your custom build
docker compose up -d

Build Multi-Architecture

For publishing to Docker Hub (requires buildx):

bash

# Create and use buildx builder
docker buildx create --name multiplatform --use --bootstrap

# Build and push for multiple architectures
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t username/minepanel:latest \
  --push .

Platform-Specific Notes

Linux

Make sure your user is in the docker group:

bash

sudo usermod -aG docker $USER
# Log out and back in

macOS

Install Docker Desktop for Mac. Everything works out of the box.

Windows

Install WSL2
Install Docker Desktop for Windows
Enable WSL2 integration in Docker Desktop settings
Run commands inside WSL2 (Ubuntu terminal)

Better Performance

Use WSL2 file system for better performance: /home/username/minepanel instead of /mnt/c/Users/...

Raspberry Pi / ARM

Minepanel fully supports ARM64 architecture. Use the same installation commands - Docker automatically pulls the correct ARM image.

Performance Note

On Raspberry Pi 4 (4GB+), you can run 2-3 small Minecraft servers. Allocate 1-2GB RAM per server.

Custom Directories

To use custom directories on any platform, set environment variables:

bash

# Create .env file
SERVERS_DIR=/custom/path/servers
DATA_DIR=/custom/path/data
FILEBROWSER_DIR=/custom/path/filebrowser

See the Configuration Guide for more details.

Uninstalling

To completely remove Minepanel:

bash

# Stop all containers
docker compose down

# Remove all data (WARNING: This deletes everything!)
rm -rf servers/ filebrowser-data/ data/

# Remove Docker images
docker rmi ketbom/minepanel:latest
docker rmi hurlenko/filebrowser

To keep your server data but stop the panel:

bash

# Just stop containers
docker compose down

# Start again later
docker compose up -d

Installation Guide ​

Installation Methods ​

Quick Install ​

Step 1: Create docker-compose.yml ​

Step 2: Launch ​

Install from Source ​

Update to Latest ​

Split Services Installation ​

Using docker-compose.split.yml ​

With nginx-proxy + Let's Encrypt ​

Step 1: Setup nginx-proxy ​

Step 2: Configure Minepanel ​

Development Setup ​

Prerequisites ​

Setup ​

Run in Development Mode ​

Build Custom Docker Image ​

Build Multi-Architecture ​

Platform-Specific Notes ​

Linux ​

macOS ​

Windows ​

Raspberry Pi / ARM ​

Custom Directories ​

Uninstalling ​

Next Steps ​

Installation Guide

Installation Methods

Quick Install

Step 1: Create docker-compose.yml

Step 2: Launch

Install from Source

Update to Latest

Split Services Installation

Using docker-compose.split.yml

With nginx-proxy + Let's Encrypt

Step 1: Setup nginx-proxy

Step 2: Configure Minepanel

Development Setup

Prerequisites

Setup

Run in Development Mode

Build Custom Docker Image

Build Multi-Architecture

Platform-Specific Notes

Linux

macOS

Windows

Raspberry Pi / ARM

Custom Directories

Uninstalling

Next Steps