Skip to main content
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)
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"
​
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

​
TZ
string
default:"UTC"
Configure timezone to match your locale
docker run -d -it --pull=always \
  -e TZ=Europe/London \
  -p 25565:25565 \
  --name mc itzg/minecraft-server

​
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
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
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

Build docs developers (and LLMs) love

Get started for freeTalk to us