Getting Started

Prerequisites

DiscoPanel manages Minecraft servers as Docker containers, so Docker is required regardless of how you deploy DiscoPanel itself.

• Docker Engine (with Docker Compose for that method)

Docker Compose

The recommended way to run DiscoPanel. Create a docker-compose.yml or use the one from the repo:

docker-compose.yml

services:
  discopanel:
    image: nickheyer/discopanel:latest
    container_name: discopanel
    restart: unless-stopped

    # Option 1 (RECOMENDED FOR SIMPLICITY): Use host network mode
    network_mode: host

    # Option 2 (MORE COMPLICATED, ONLY USE IF YOU NEEDED): Use bridge mode with port mapping (default)
    #
    # NOTE: Only specify minecraft server ports (25565 ... etc) for proxied minecraft servers using a hostname.
    #       Discopanel will automatically expose ports needed on the managed minecraft server instances. In other
    #       words, only the discopanel web port is needed + proxy port(s).
    # ports:
    #   - "8080:8080"         # DiscoPanel web interface
    #   - "25565:25565"       # Minecraft port/proxy-port
    #   - "25565-25665:25565-25665/tcp" # Additional ports/proxy-ports if needed
    #   - "25565-25665:25565-25665/udp" # Also map UDP for some Minecraft features

    volumes:
      # Docker socket for managing containers
      # NOTE FOR FEDORA/RHEL/CENTOS/ETC.: SE Linux requires :z to be added as a suffix to volume mounts. EX: - /var/run/docker.sock:/var/run/docker.sock:z
      - /var/run/docker.sock:/var/run/docker.sock

      # IMPORTANT: This is where your server(s) data will be stored on the host.
      # You can set this to any path you'd like, but the path must exist AND you must use the same
      # absolute paths below for the below env vars (in the environment section at the bottom). Example:
      # DISCOPANEL_DATA_DIR=/app/data
      # DISCOPANEL_HOST_DATA_PATH=/opt/discopanel/data
      # (See environment)
      - /opt/discopanel/data:/app/data
      - /opt/discopanel/backups:/app/backups
      - /tmp/discopanel:/app/tmp

      # Configuration file, uncomment if you are using a config file (optional, see config.example.yaml for all available options).
      #- ./config.yaml:/app/config.yaml:ro
    environment:
      - DISCOPANEL_DATA_DIR=/app/data

      # IMPORTANT: THIS MUST BE SET TO THE SAME PATH AS THE SERVER DATA PATH IN "volumes" above
      - DISCOPANEL_HOST_DATA_PATH=/opt/discopanel/data
      - TZ=UTC

      # ── Authentication ──────────────────────────
      # Local auth (username/password) is on by default.
      # You create your first admin account on first login.
      #
      # Want to let new users sign up on their own?
      # - DISCOPANEL_AUTH_LOCAL_ALLOW_REGISTRATION=true
      #
      # Want single sign-on (OIDC) with Keycloak, Authelia, etc?
      # See the oidc/ folder for examples.

    # DONT FORGET THIS
    extra_hosts:
      - "host.docker.internal:host-gateway"

Spin up your service:

docker compose up -d

Volume paths

DiscoPanel creates Docker bind mounts for each managed Minecraft server. When DiscoPanel runs inside a container, it needs to know both the container-internal path and the corresponding host path to set up those mounts correctly.

Variable	Purpose	Example
DISCOPANEL_HOST_DATA_PATH	The host path that DISCOPANEL_DATA_DIR is mounted from	/opt/discopanel/data
DISCOPANEL_DATA_DIR	Where DiscoPanel reads/writes data inside the container — you can usually leave this as the default	/app/data

These must correspond to the same volume entry. If your compose file maps /srv/minecraft/data:/app/data, then set DISCOPANEL_HOST_DATA_PATH=/srv/minecraft/data.

SELinux

On Fedora, RHEL, CentOS, etc., append :z to volume mounts:

- /var/run/docker.sock:/var/run/docker.sock:z

Once running, open http://<your-host>:8080 and create your admin account.

---

Proxmox LXC

The Proxmox VE Community Scripts project maintains a DiscoPanel helper script that creates a Debian 13 LXC container with everything pre-installed (Docker, Go, Node.js, DiscoPanel built from source) and managed as a systemd service.

From your Proxmox host shell:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/discopanel.sh)"

The interactive wizard lets you adjust the default container resources. Set these based on what you expect your servers to need.

Sizing guidance

CPU — A single Minecraft server (vanilla or modded) rarely exceeds 400% (4 cores). While up to 4 cores per server is recommended for optimal performance, you can start with the default of 4 and increase as needed.

RAM — Vanilla servers may only need a few GB, but heavily modded servers average 10 GB+ per instance, especially with multiple players. You can safely allocate most of your available RAM — Proxmox doesn’t strictly reserve it, so other LXCs and the host OS can still use whatever DiscoPanel isn’t actively consuming.

Disk — Entirely depends on what you plan to run and for how long. 40–80 GB is a reasonable starting point and can be expanded later.

Paths

Since DiscoPanel runs directly on the host here (not inside a Docker container), file paths are straightforward — DISCOPANEL_DATA_DIR and DISCOPANEL_HOST_DATA_PATH should be the same value. The default ./data relative to /opt/discopanel works out of the box.

Once complete, DiscoPanel is accessible at http://<container-ip>:8080.

---

Prebuilt Binaries

Grab a release from the releases page. Packages are available for each platform:

discopanel-darwin-amd64.tar.gz
discopanel-darwin-arm64.tar.gz
discopanel-linux-amd64.tar.gz
discopanel-linux-arm64.tar.gz
discopanel-windows-amd64.exe.zip

Note

Darwin is the platform name for macOS. Only Linux is fully supported and tested — Windows installations may have issues.

Extract and skip ahead to Running.

---

Building from Source

If you’d rather build it yourself instead of using a prebuilt binary:

Requirements

• Go 1.24+
• Node.js 22+
• Docker (used to run buf for protobuf code generation)
• Make

Build steps

# Clone the repo
git clone https://github.com/nickheyer/discopanel.git
cd discopanel

# Generate protobuf code (Go + TypeScript) via Docker buf
make gen

# Install frontend dependencies and build
cd web/discopanel && npm install && npm run build && cd ../..

# Build the Go binary with embedded frontend
go build -o discopanel cmd/discopanel/main.go

The //go:embed directives bake the frontend build into the binary so it serves the UI without a separate web server.

---

Running

# Using default config (./config.yaml if it exists, otherwise defaults)
./discopanel

# Or point to a specific config file
./discopanel -config /path/to/config.yaml

All config options can also be set via environment variables with the DISCOPANEL_ prefix. For example, server.port becomes DISCOPANEL_SERVER_PORT. Environment variables take precedence over the config file.

Host path mapping

When running the binary directly on a host (not in a Docker container), do not set DISCOPANEL_DATA_DIR or DISCOPANEL_HOST_DATA_PATH — those are only for container path translation.

To change where DiscoPanel stores its database and server data, set DISCOPANEL_STORAGE_DATA_DIR or configure it in your config file:

storage:
  data_dir: /your/path  # Default: ./data (relative to working directory)

For all available configuration options, see Configuration.