Configuration

Carbon Panel can be configured via a YAML config file, environment variables, or both. Environment variables take precedence over the config file.

For Minecraft server-specific configuration (server.properties, JVM flags, mod loader settings, etc.), see the itzg/minecraft-server docs.

Config file

Carbon Panel looks for config.yaml in these locations (in order):

Path passed via -config flag
Current working directory (./)
./config/
/etc/carbon-panel/

If no config file is found, defaults are used.

Environment variables

Every config option can be set via an environment variable with the CARBONPANEL_ prefix. Nested keys are separated by underscores:

server:
  port: "8080"

is equivalent to:

CARBONPANEL_SERVER_PORT="8080"

All options

# 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/.


# Carbon Panel Configuration File
# This file contains all configuration options for Carbon Panel
#
# These can all be set via env, like we do in our docker compose example(s). For example:
#
# server:
#   port: "8080"
#
# - is the same as -
#
# CARBONPANEL_SERVER_PORT="8080"

# Server configuration for the Carbon Panel application itself
server:
  port: "8080"
  host: "0.0.0.0"
  read_timeout: 15
  write_timeout: 15
  idle_timeout: 60
  user_agent: "CarbonPanel/1.0 (github.com/athNdev/carbon-panel)"
  # Trust X-Forwarded-Host for the WebSocket origin check only behind a proxy you control.
  trust_proxy: false
  # Extra browser origins allowed to open the console. Empty keeps same-host only.
  # allowed_origins: ["https://panel.example.com"]

# Database configuration
database:
  path: "./data/carbon-panel.db"
  max_connections: 25
  max_idle_conns: 5
  conn_max_lifetime: 300
  # Daily VACUUM INTO snapshot under storage.data_dir/backups. "off" disables it.
  # Snapshots are crash-consistent (VACUUM INTO) and integrity-checked before use.
  # Restore: stop the panel, then run
  #   carbon-panel -config config.yaml -restore-panel-backup <snapshot-file>
  # The restore verifies the snapshot and purges stale WAL sidecars; the previous
  # database is kept as <db>.pre-restore. See docs/runbook-panel-db-restore.md.
  # There is no automatic restore. This is not Litestream.
  panel_backup: daily
  panel_backup_keep: 7

# Docker configuration
docker:
  host: "unix:///var/run/docker.sock"
  version: ""
  network_name: "carbon-panel-network"
  registry_url: ""
  sync_interval: 5  # Seconds between docker state sync
  # Can be configure like labels: {"your.label.key": "your_label_value", "other.label.key": "other_label_value"}
  # or
  # labels:
  #   your.label.key: "your_label_value"
  #   other.label.key: "other_label_value"
  labels: '{ }'
  # Remove containers created by this installation but unknown to the database at
  # startup. Disabled by default: they are reported and left running (quarantined),
  # and containers from another installation are never touched.
  reconcile_purge_orphans: false

# Storage configuration
storage:
  data_dir: "./data"
  backup_dir: "./backups"
  temp_dir: "./tmp"
  max_upload_size: 524288000  # 500MB in bytes
  # Caps the container writable layer with the daemon storage-opt size option.
  # It applies only when a container root filesystem is writable (an image that
  # writes outside /data). It never bounds the world: /data is a bind mount and
  # is measured, not quota-limited. Leave 0 for no cap.
  container_writable_mb: 0
  # S3-compatible offsite backup upload (MINE-138). Credentials can also come
  # from env: CARBONPANEL_STORAGE_S3_ACCESS_KEY / CARBONPANEL_STORAGE_S3_SECRET_KEY.
  s3:
    enabled: false
    endpoint: ""  # e.g. https://s3.amazonaws.com or http://minio:9000 (empty = AWS)
    region: "us-east-1"
    bucket: ""
    prefix: "carbon-panel-backups"
    access_key: ""
    secret_key: ""
    force_path_style: false  # needed for MinIO / path-style endpoints
    delete_local_copy: false  # remove local archive after successful upload

# Authentication configuration
auth:
  session_timeout: 86400  # default: 24 hours
  anonymous_access: false  # Allow unauthenticated access
  jwt_secret: ""  # Leave empty to auto-generate

  # Local authentication (login via carbon-panel web ui)
  local:
    enabled: true  # Enable local
    allow_registration: false  # Allow new users to register themselves via login

  # OIDC authentication (login via OIDC-compliant provider, ie: keycloak, authelia, authentik, etc.)
  oidc:
    enabled: false
    issuer_uri: ""  # OIDC Provider url (ie: http://authelia.local:9091, http://localhost:8180/realms/carbon-panel, etc.)
    client_id: ""  # Client ID registered with your OIDC (like "carbon-panel")
    client_secret: ""  # Client secret registered with your OIDC
    redirect_url: ""  # Where OIDC sends users after login (ie: "http://localhost:8080/api/v1/auth/oidc/callback")
    scopes: ["openid", "profile", "email"]
    role_claim: "groups"  # The token claim that contains the user's groups (usually "groups")
    role_mapping: {}  # Mapping to groups if they arent the same name as carbon-panel's (ie: {"my-admins": "admin", "my-users": "user"})
    skip_tls_verify: false  # Skip TLS certificate verification (for self-signed certs)

# Upload configuration
upload:
  session_ttl: 240  # Upload session time-to-live in minutes (default: 4 hours)
  default_chunk_size: 5242880  # 5MB default chunk size (client can override)
  max_chunk_size: 10485760  # 10MB max chunk size (server enforced)
  max_upload_size: 0  # Max total upload size in bytes (0 = unlimited)

# Module configuration
module:
  enabled: true
  port_range_min: 8100
  port_range_max: 8199

# Proxy configuration - ENABLE THIS FOR MINECRAFT ROUTING
proxy:
  enabled: true
  base_url: "mc.example.com" # Your domain for Minecraft servers
  listen_port: 25565 # Primary port to listen on (can also use 443)
  listen_ports: [25565] # Multiple ports to listen on (listen_port will be added if not present)
  port_range_min: 25565
  port_range_max: 25665
  # Handshake NextState=3 (Transfer) is treated as login. Velocity defaults
  # accepts-transfers to false; Carbon defaults to true so a transferred
  # player still reaches the hostname route. Set false to disconnect them.
  accepts_transfers: true
  # Minimum gap between handshakes from one IP on the Gate listen port.
  # Status and login share the budget. 0 disables. Play sessions stay up.
  login_ratelimit_ms: 3000

# Example usage:
# With proxy enabled and base_url set to "mc.example.com":
# - Server named "survival" → Connect via: survival.mc.example.com:25565
# - Server named "creative" → Connect via: creative.mc.example.com:25565
# - Server named "modded" → Connect via: modded.mc.example.com:25565
#
# All servers use the same port (25565) and are routed based on hostname!
#
# DNS Setup Required:
# Add a wildcard DNS record: *.mc.example.com → Your server's IP
# Or add individual A records for each server subdomain


# Minecraft server global configuration defaults
minecraft:
  reset_global: false
  global_config: # Specifying any of these settings will override the global config default when it is first made, or existing if `reset_global` is `true`
    # JVM Configuration
    uid: 1000
    gid: 1000
    memory: "1G"
    initMemory: "1G"
    maxMemory: "1G"
    tz: "UTC"
    enableRollingLogs: false
    enableJmx: false
    jmxHost: ""
    useAikarFlags: false
    useMeowiceFlags: false
    useMeowiceGraalvmFlags: true
    jvmOpts: ""
    jvmXxOpts: ""
    jvmDdOpts: ""
    extraArgs: ""
    logTimestamp: false

    # Server Configuration
    type: "VANILLA"
    eula: "TRUE"
    version: "LATEST"
    motd: ""
    difficulty: "easy"
    icon: ""
    overrideIcon: false
    maxPlayers: 20
    maxWorldSize: 0
    allowNether: true
    announcePlayerAchievements: true
    enableCommandBlock: false
    forceGamemode: false
    generateStructures: true
    hardcore: false
    snooperEnabled: true
    maxBuildHeight: 256
    spawnAnimals: true
    spawnMonsters: true
    spawnNpcs: true
    spawnProtection: 0
    viewDistance: 0
    seed: ""
    mode: "survival"
    pvp: true
    levelType: "minecraft:default"
    generatorSettings: ""
    level: "world"
    onlineMode: true
    allowFlight: false
    serverName: ""
    serverPort: 0
    playerIdleTimeout: 0
    syncChunkWrites: false
    enableStatus: false
    entityBroadcastRangePercentage: 0
    functionPermissionLevel: 0
    networkCompressionThreshold: 0
    opPermissionLevel: 0
    preventProxyConnections: false
    useNativeTransport: false
    simulationDistance: 0
    execDirectly: false
    stopServerAnnounceDelay: 0
    proxy: ""
    console: true
    gui: true
    stopDuration: 60
    setupOnly: false
    useFlareFlags: false
    useSimdFlags: false

    # Custom Resource Pack
    resourcePack: ""
    resourcePackSha1: ""
    resourcePackEnforce: false

    # Whitelist
    enableWhitelist: false
    whitelist: ""
    whitelistFile: ""
    overrideWhitelist: false

    # RCON
    enableRcon: true
    rconPassword: ""  # MUST be changed for security
    rconPort: 25575
    broadcastRconToOps: false
    rconCmdsStartup: ""
    rconCmdsOnConnect: ""
    rconCmdsFirstConnect: ""
    rconCmdsOnDisconnect: ""
    rconCmdsLastDisconnect: ""

    # Forge Configuration
    forgeVersion: ""
    forgeInstaller: ""
    forgeInstallerUrl: ""

    # CurseForge Configuration
    cfApiKey: ""
    cfApiKeyFile: ""
    cfPageUrl: ""
    cfSlug: ""
    cfFileId: ""
    cfModpackZip: ""
    cfFilenameMatcher: ""
    cfExcludeIncludeFile: ""
    cfExcludeMods: ""
    cfForceIncludeMods: ""
    cfForceSynchronize: false
    cfSetLevelFrom: ""
    cfParallelDownloads: 4
    cfOverridesSkipExisting: false
    cfForceReinstallModloader: false

    # Modrinth Configuration
    modrinthModpack: ""
    modrinthModpackVersionType: "release"
    modrinthVersion: ""
    modrinthLoader: ""
    modrinthIgnoreMissingFiles: ""
    modrinthExcludeFiles: ""
    modrinthForceIncludeFiles: ""
    modrinthForceSynchronize: false
    modrinthDefaultExcludeIncludes: ""
    modrinthOverridesExclusions: ""
    modrinthProjects: ""
    modrinthDownloadDependencies: "none"
    modrinthProjectsDefaultVersionType: "release"
    versionFromModrinthProjects: false

    # Custom Server Configuration
    customServer: ""
    customJarExec: ""

    # Query Protocol Configuration
    enableQuery: false
    queryPort: 25565

    # Advanced Server Properties
    serverPropertiesEscapeUnicode: false
    acceptsTransfers: false
    broadcastConsoleToOps: true
    bugReportLink: ""
    enforceSecureProfile: true
    hideOnlinePlayers: false
    logIps: true
    maxChainedNeighborUpdates: 1000000
    pauseWhenEmptySeconds: 0
    rateLimit: 0
    regionFileCompression: "deflate"
    resourcePackId: ""
    resourcePackPrompt: ""
    statusHeartbeatInterval: 0
    customServerProperties: ""

    # Ops / Admins
    userApiProvider: "playerdb"
    ops: ""
    opsFile: ""
    existingOpsFile: "SYNC_FILE_MERGE_LIST"

    # Additional Whitelist Options
    existingWhitelistFile: "SYNC_FILE_MERGE_LIST"
    enforceWhitelist: false

# Logging configuration
logging:
  enabled: true
  file_path: "./data/carbon-panel.log"
  max_size: 10
  max_backups: 5
  max_age: 30
  compress: true