Docker Compose

Prerequisites

Carbon Panel manages Minecraft servers as Docker containers, so Docker is required.

Docker Engine with Docker Compose

Compose file

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

# SPDX-License-Identifier: MIT AND MPL-2.0
# This file includes DiscoPanel material under the MIT License,
# Copyright (c) 2025 Nicholas W. Heyer. The MIT license text is in LICENSE
# and still applies to that inherited material.
# Maintainer changes are licensed under the Mozilla Public License, v. 2.0.
# If a copy of the MPL was not distributed with this file, You can obtain
# one at https://mozilla.org/MPL/2.0/.


services:
  carbon-panel:
    image: carbon-panel:latest
    container_name: carbon-panel
    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: In bridge mode, Carbon Panel automatically attaches itself to the managed Docker network
    #       (carbon-panel-network) at startup so it can reach the minecraft server containers it creates.
    #
    # NOTE: Only specify minecraft server ports (25565 ... etc) for proxied minecraft servers using a hostname.
    #       Carbon Panel will automatically expose ports needed on the managed minecraft server instances. In other
    #       words, only the carbon-panel web port is needed + proxy port(s).
    # ports:
    #   - "8080:8080"         # Carbon Panel 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.
      # Set the left-hand side to any absolute path you want to keep. The panel
      # reads this mapping from its own container, so there is no matching
      # environment variable to keep in sync. Startup refuses to run if the data
      # directory is not mounted or not writable, instead of writing worlds into
      # the container's own filesystem.
      - /opt/carbon-panel/data:/app/data
      - /opt/carbon-panel/backups:/app/backups
      - /tmp/carbon-panel:/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:
      - 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?
      # - CARBONPANEL_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

Carbon Panel creates a Docker bind mount for each managed Minecraft server, and the Docker daemon interprets those paths on the host, not inside the panel’s container.

There is nothing to configure for this. At startup the panel reads the mount table of its own container and works out the host path behind /app/data. Your compose file is the only place that mapping exists:

volumes:
  - /srv/minecraft/data:/app/data

With that entry, a server directory the panel sees at /app/data/servers/x is requested from the daemon as /srv/minecraft/data/servers/x.

Startup validates the mapping before anything writes to it. It stops with a message naming the directory when:

no volume is mounted at the data directory (worlds would land in the container’s own filesystem and disappear on recreate),
the volume is mounted read-only,
the data directory is a tmpfs,
the container user cannot write to it (no write permission on the mount dir),
a CARBONPANEL_HOST_DATA_PATH override is set to a relative path (mount path should be absolute).

CARBONPANEL_HOST_DATA_PATH and CARBONPANEL_DATA_DIR are no longer needed. Both are still read for backwards compatibility when the panel cannot read its own mount table (for example behind a Docker socket proxy that forbids container reads), and setting CARBONPANEL_HOST_DATA_PATH is reported in the log as deprecated.

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

For all available configuration options, see Configuration.