Miscellaneous Options - Docker Minecraft Server

This page covers various additional configuration options that don’t fit into other categories but are useful for customizing your Minecraft server.

Custom Server JAR

Run a custom server JAR file instead of downloading a standard server type.

TYPE

string

Must be set to CUSTOM to use a custom server JAR

CUSTOM_SERVER

string

URL or container path to the custom server JAR file

Example

environment:
  TYPE: CUSTOM
  CUSTOM_SERVER: https://example.com/my-server.jar

If it’s a URL, the JAR will only be downloaded if it doesn’t already exist in /data. To upgrade or re-download, stop the container, remove the file, and restart.

Force Server Re-download

Force re-download of the server file for certain server types.

FORCE_REDOWNLOAD

boolean

default:"false"

Force re-download of server file. Works with: VANILLA, FORGE, BUKKIT, SPIGOT, PAPER, CURSEFORGE, SPONGEVANILLA

Example with Paper

docker run -d --pull=always \
    -v /path/on/host:/data \
    -e TYPE=PAPER \
    -e FORCE_REDOWNLOAD=true \
    -p 25565:25565 -e EULA=TRUE \
    --name mc itzg/minecraft-server

Interactive and Color Console

When RCON is enabled (default) and TTY is enabled on the container, some server types output colorized logs and provide a fully interactive console.

To access the interactive console, use docker attach (not exec). When finished, use Control-P, Control-Q to detach without stopping the container.

If this behavior interferes with log content:

In compose: set the service’s tty parameter to false
With docker run: remove the -t argument

Logging Configuration

The image can use a templated log4j2 configuration based on PaperMC’s logging setup, automatically applied for versions that don’t require Log4j security patches.

GENERATE_LOG4J2_CONFIG

boolean

default:"false"

Enable templated log4j2 configuration with rolling logs and advanced features

This configures server logging only. To diagnose container startup, set DEBUG=true.

Log Level

LOG_LEVEL

string

default:"info"

Root logger level. Values: trace, debug, info, warn, error

docker run -d -e LOG_LEVEL=debug ...

Rolling Log Configuration

ROLLING_LOG_FILE_PATTERN

string

default:"logs/%d{yyyy-MM-dd}-%i.log.gz"

Pattern for rolled log file names

ROLLING_LOG_MAX_FILES

number

default:"1000"

Maximum number of archived log files to keep

Log Message Formats

Customize log output using Log4j2 Pattern Layout syntax:

LOG_CONSOLE_FORMAT

string

default:"[%d{HH:mm:ss}] [%t/%level]: %msg%n"

Format for console output (visible in docker logs)

LOG_FILE_FORMAT

string

default:"[%d{HH:mm:ss}] [%t/%level]: %msg%n"

Format for file logs (written to logs/latest.log)

LOG_TERMINAL_FORMAT

string

default:"[%d{HH:mm:ss} %level]: %msg%n"

Format for interactive terminal console (used with docker attach)

Simple Timestamp Customization
Advanced Customization

environment:
  LOG_CONSOLE_FORMAT: "[%d{yyyy-MM-dd HH:mm:ss.SSS}] [%t/%level]: %msg%n"
  LOG_FILE_FORMAT: "[%d{yyyy-MM-dd HH:mm:ss.SSS}] [%t/%level]: %msg%n"

environment:
  LOG_LEVEL: debug
  LOG_CONSOLE_FORMAT: "%d{ISO8601} %-5level [%t] %logger{36} - %msg%n"
  LOG_FILE_FORMAT: "%d{ISO8601} %-5level [%t] %logger{36} - %msg%n"
  ROLLING_LOG_MAX_FILES: 50

ENABLE_ROLLING_LOGS

boolean

default:"false"

Legacy option for backward compatibility. Rolling logs are now enabled by default through templated configuration.

The templated log4j2 configuration may interfere with interactive/color consoles.

HTTP Proxy

Configure HTTP/HTTPS proxy for server connections.

PROXY

string

Proxy host:port

PROXY_HOST

string

Proxy host (separate from port)

PROXY_PORT

string

Proxy port (separate from host)

PROXY_NON_PROXY_HOSTS

string

Pipe-delimited list of hosts to exclude from proxying

See the example compose file for a Squid proxy reference.

Timezone Configuration

string

default:"UTC"

Configure timezone to match your locale

Environment Variable
Volume Mount

docker run -d -it --pull=always \
  -e TZ=Europe/London \
  -p 25565:25565 \
  --name mc itzg/minecraft-server

docker run -d -it --pull=always \
  -v /etc/timezone:/etc/timezone:ro \
  -p 25565:25565 \
  --name mc itzg/minecraft-server

Not supported on Windows

Download Extra Configs

Download additional configuration files for plugins or mods.

DOWNLOAD_EXTRA_CONFIGS

string

Newline or comma-separated list of path<url pairs to download configuration files

Multi-line Format
Single Line Format

environment:
  DOWNLOAD_EXTRA_CONFIGS: |
    plugins/WorldEdit<https://raw.githubusercontent.com/EngineHub/WorldEdit/refs/heads/version/7.3.x/worldedit-bukkit/src/main/resources/defaults/config.yml
    plugins/EssentialsX<https://raw.githubusercontent.com/EssentialsX/Essentials/refs/heads/2.x/Essentials/src/main/resources/config.yml

environment:
  DOWNLOAD_EXTRA_CONFIGS: "plugins/WorldEdit<https://example.com/worldedit.yml,config<https://example.com/another.yml"

Files are downloaded to /data/ relative paths. Example: plugins/WorldEdit saves as /data/plugins/WorldEdit/config.yml.

Downloaded files can be further processed using environment variable replacement or patch definitions.

Init Log Timestamps

LOG_TIMESTAMP

boolean

default:"false"

Include timestamps in init logs (before Minecraft server starts)

Without timestamps

[init] Starting the Minecraft server...

With timestamps

[init] 2022-02-05 16:58:33+00:00 Starting the Minecraft server...

Setup Only Mode

SETUP_ONLY

boolean

default:"false"

Setup server files and stop before launching the server process. Useful for host-attached data directories.

Example

environment:
  SETUP_ONLY: "true"

Console Options

CONSOLE

boolean

default:"true"

Some older Spigot versions (pre-1.14) require --noconsole when detaching stdin. Set to false for those versions.

GUI

boolean

default:"true"

Explicitly disable GUI interface. Some older servers get confused and think GUI is enabled.

Example

environment:
  CONSOLE: "false"  # For pre-1.14 Spigot
  GUI: "false"      # Explicitly disable GUI

Health Monitoring

Configure health check monitoring for the Minecraft server.

SERVER_HOST

string

default:"localhost"

Host address of the Minecraft server for health monitoring

SERVER_PORT

number

default:"25565"

Port number for health monitoring

Example

environment:
  SERVER_HOST: minecraft.example.com
  SERVER_PORT: 25565

Server Shutdown Options

STOP_DURATION

number

default:"60"

How long (in seconds) to wait for graceful shutdown after sending stop command

STOP_SERVER_ANNOUNCE_DELAY

number

Seconds to delay after shutdown announcement to allow players to finish activities

The Docker stop grace period must be longer than announce delay. Increase using the -t option on docker compose down or set stop_grace_period in compose.

Example

services:
  mc:
    image: itzg/minecraft-server
    environment:
      STOP_SERVER_ANNOUNCE_DELAY: 30
    stop_grace_period: 2m

Bypass announce delay with SIGUSR1 signal:

docker stop --signal SIGUSR1 mc
# or
docker compose kill --signal SIGUSR1

Performance Optimization Flags

Flare Profiling

USE_FLARE_FLAGS

boolean

default:"false"

Enable JVM flags for Flare profiling suite. Built into Pufferfish/Purpur, available as plugin for others.

docker run -d -e USE_FLARE_FLAGS=true ...

SIMD Operations

USE_SIMD_FLAGS

boolean

default:"false"

Enable optimized SIMD operations. Supported by Pufferfish and Purpur.

docker run -d -e USE_SIMD_FLAGS=true ...

Debug Mode

DEBUG

boolean

default:"false"

Enable debug output for container startup diagnostics

environment:
  DEBUG: "true"

Complete Example

compose.yaml

services:
  mc:
    image: itzg/minecraft-server:latest
    tty: true
    stdin_open: true
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      VERSION: "1.20.4"
      
      # Logging
      GENERATE_LOG4J2_CONFIG: "true"
      LOG_LEVEL: info
      LOG_TIMESTAMP: "true"
      ROLLING_LOG_MAX_FILES: 30
      
      # Timezone
      TZ: America/New_York
      
      # Performance
      USE_FLARE_FLAGS: "true"
      USE_SIMD_FLAGS: "true"
      
      # Shutdown
      STOP_SERVER_ANNOUNCE_DELAY: 30
      STOP_DURATION: 90
      
      # Download configs
      DOWNLOAD_EXTRA_CONFIGS: |
        plugins/WorldEdit<https://raw.githubusercontent.com/EngineHub/WorldEdit/refs/heads/version/7.3.x/worldedit-bukkit/src/main/resources/defaults/config.yml
      
    ports:
      - "25565:25565"
    volumes:
      - ./data:/data
    stop_grace_period: 2m

Documentation Index

​Custom Server JAR

​Force Server Re-download

​Interactive and Color Console

​Logging Configuration

​Log Level

​Rolling Log Configuration

​Log Message Formats

​HTTP Proxy

​Timezone Configuration

​Download Extra Configs

​Init Log Timestamps

​Setup Only Mode

​Console Options

​Health Monitoring

​Server Shutdown Options

​Performance Optimization Flags

​Flare Profiling

​SIMD Operations

​Debug Mode

​Complete Example

Custom Server JAR

Force Server Re-download

Interactive and Color Console

Logging Configuration

Log Level

Rolling Log Configuration

Log Message Formats

HTTP Proxy

Timezone Configuration

Download Extra Configs

Init Log Timestamps

Setup Only Mode

Console Options

Health Monitoring

Server Shutdown Options

Performance Optimization Flags

Flare Profiling

SIMD Operations

Debug Mode

Complete Example