Skip to main content
Variable interpolation allows you to use runtime environment variables in your server configuration files, perfect for handling deployment-specific settings like database credentials or dynamic server names.

​
Overview

When you have mods or plugins requiring configuration information only available at deploy-time (like database connections or runtime server names), you can use variable interpolation to inject environment variables into your configuration files.

​
Configuration File Interpolation

​
Basic Usage

​
REPLACE_ENV_IN_PLACE
boolean
default:"true"
Replace variables in all files inside /data with matching environment variables
​
REPLACE_ENV_DURING_SYNC
boolean
default:"false"
Replace variables in files synced from /plugins, /mods, and /config directories
​
REPLACE_ENV_VARIABLE_PREFIX
string
default:"CFG_"
Prefix required for environment variables to be replaced. Set to empty string to allow any variable name.

​
Variable Syntax

Variables use curly bracket syntax with a dollar sign prefix: 
${CFG_YOUR_VARIABLE}
This is the same syntax used in many scripting languages and Docker Compose files.

​
Supported File Types

Variable replacement works with these file extensions:
  • .yml
  • .yaml
  • .txt
  • .cfg
  • .conf
  • .properties

​
Example Configuration

database.yml
database:
  host: ${CFG_DB_HOST}
  name: ${CFG_DB_NAME}
  password: ${CFG_DB_PASSWORD}

​
Using Secrets as Files

For sensitive values like passwords, declare placeholders in config files and use environment variables with the _FILE suffix pointing to mounted secrets.
​
{VARIABLE_NAME}_FILE
string
Environment variable pointing to a file containing the actual value. The variable name should match the placeholder but with _FILE suffix.

​
Example with Docker Secrets

[client]
password = ${CFG_DB_PASSWORD}

​
Exclusions

​
Exclude Specific Files

​
REPLACE_ENV_VARIABLES_EXCLUDES
string
Comma or space-separated list of filenames (without path) to exclude from variable replacement
environment:
  REPLACE_ENV_VARIABLES_EXCLUDES: "protected.yml,sensitive.conf"

​
Exclude Paths

​
REPLACE_ENV_VARIABLES_EXCLUDE_PATHS
string
Space-separated list of paths to exclude from variable replacement. Exclusions are recursive.
environment:
  REPLACE_ENV_VARIABLES_EXCLUDE_PATHS: "/data/plugins/Essentials/userdata /data/plugins/MyPlugin"

​
Server Properties Placeholders

When declaring server properties via environment variables, you can use special placeholders that are processed when server.properties is updated.
Placeholders in server properties use DOS-style %VAR% syntax to avoid being processed by Docker or the shell.

​
Placeholder Types

Environment Variables:
  • %VAR% - Replaced with value of environment variable VAR
  • %env:VAR% - Explicit environment variable syntax
Date Formatting:

​
Available Variables

Any declared or resolved environment variable may be referenced:
  • VERSION - Resolved Minecraft version
  • TYPE - Server type
  • DECLARED_VERSION - Originally declared version (e.g., “LATEST” or “SNAPSHOT”)
  • MODPACK_NAME - Available with Modrinth and Auto CurseForge modpacks
  • MODPACK_VERSION - Available with Modrinth and Auto CurseForge modpacks

​
Examples

environment:
  MOTD: Running %MODPACK_NAME% version %env:MODPACK_VERSION%
Placeholders are not supported when manually managing server.properties (when OVERRIDE_SERVER_PROPERTIES=false).

​
Patching Existing Files

JSON path-based patches can be applied to existing files for more complex modifications.
​
PATCH_DEFINITIONS
string
Path to a directory containing patch definition JSON files or a patch set JSON file. See mc-image-helper documentation for format details.
The file and value fields in patch definitions support ${...} variable placeholders. Use REPLACE_ENV_VARIABLE_PREFIX to restrict allowed variables (defaults to “CFG_”).

​
Patch Set Example

patch-set.json
{
  "patches": [
    {
      "file": "/data/paper.yml",
      "ops": [
        {
          "$set": {
            "path": "$.verbose",
            "value": true
          }
        },
        {
          "$set": {
            "path": "$.settings['velocity-support'].enabled",
            "value": "${CFG_VELOCITY_ENABLED}",
            "value-type": "bool"
          }
        },
        {
          "$put": {
            "path": "$.settings",
            "key": "my-test-setting",
            "value": "testing"
          }
        }
      ]
    }
  ]
}

​
Supported Formats

Patch definitions support:
  • JSON
  • JSON5
  • YAML
  • TOML (output is not pretty-printed)

​
Complete Example

compose.yaml
services:
  minecraft:
    image: itzg/minecraft-server
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      VERSION: "1.20.4"
      
      # Enable variable replacement
      REPLACE_ENV_VARIABLES: "TRUE"
      REPLACE_ENV_DURING_SYNC: "true"
      ENV_VARIABLE_PREFIX: "CFG_"
      
      # Database configuration
      CFG_DB_HOST: "mysql.example.com"
      CFG_DB_NAME: "minecraft"
      CFG_DB_PASSWORD_FILE: "/run/secrets/db_password"
      
      # Server properties with placeholders
      MOTD: |
        Welcome to %TYPE% %VERSION%
        Server started %date:yyyy-MM-dd%
      
      # Exclusions
      REPLACE_ENV_VARIABLES_EXCLUDE_PATHS: "/data/plugins/Essentials/userdata"
      
    volumes:
      - ./data:/data
      - ./patches:/patches
    secrets:
      - db_password

secrets:
  db_password:
    file: ./db_password.txt

​
Best Practices

Use the _FILE suffix pattern with Docker Secrets for sensitive values like passwords and API keys.
Set REPLACE_ENV_VARIABLE_PREFIX to limit which environment variables can be replaced, preventing accidental substitution.
Be careful with REPLACE_ENV_VARIABLES_EXCLUDE_PATHS - exclusions are recursive and will affect all files in the specified directories.

Build docs developers (and LLMs) love

Get started for freeTalk to us