This tool does the complicated bits for the itzg/minecraft-server and itzg/bungeecord Docker images.
Usage
NOTE The following documentation may not always be up-to-date. Please be sure to use
-hor--helpafter any subcommand to view the current usage.
Usage: mc-image-helper [-hs] [--debug] [COMMAND]
--debug Enable debug output. Can also set environment variable
DEBUG_HELPER
-h, --help Show this usage and exit
-s, --silent Don't output logs even if there's an error
Commands:
asciify Converts UTF-8 on stdin to ASCII by escaping Unicode
characters
assert Provides assertion operators for verifying container
setup
compare-versions Used for shell scripting, exits with success(0) when
comparison is satisfied or 1 when not
find Specialized replacement for GNU's find
get Download a file
hash Outputs an MD5 hash of the standard input
install-forge Downloads and installs a requested version of Forge
interpolate Interpolates existing files in one or more directories
java-release Outputs the Java release number, such as 8, 11, 17
maven-download Downloads a maven artifact from a Maven repository
modrinth Automates downloading of modrinth resources
patch Patches one or more existing files using JSON path
based operations
sync Synchronizes the contents of one directory to another.
sync-and-interpolate Synchronizes the contents of one directory to another
with conditional variable interpolation.
yaml-path Extracts a path from a YAML file using json-path syntax
vanillatweaks Downloads Vanilla Tweaks resource packs, data packs, or
crafting tweaks given a share code or pack file
find
Usage: mc-image-helper find [-hq] [--delete] [--fail-no-matches]
[--only-shallowest] [--output-count-only]
[--stop-on-first] [--format=<format>]
[--max-depth=N] [-t=<type>] [--exclude-name=glob[,
glob...]]... [--name=glob[,glob...]]... startDir...
Specialized replacement for GNU's find
startDir... One or more starting directories
--delete Deletes the matched entries. When searching for
directories, each directory and its contents will
be recursively deleted.
--exclude-name=glob[,glob...]
One or more glob patterns to exclude by looking at
name part of the path. If a pattern matches a
directory's name, then its entire subtree is
excluded.
--fail-no-matches
--format=<format> Applies a format when printing each matched entry.
Supports the following directives
%% a literal %
%h leading directory of the entry
%P path of the entry relative to the starting point
-h, --help
--max-depth=N Unlimited depth if zero or negative
--name=glob[,glob...] One or more glob patterns to match name part of the
path
--only-shallowest
--output-count-only
-q, --quiet
--stop-on-first
-t, --type=<type> Valid values: file, directory
get
Usage: mc-image-helper get [-hsz] [--exists] [--log-progress-each]
[--output-filename] [--skip-existing]
[--accept=<acceptHeader>] [--json-path=<jsonPath>]
[-o=FILE|DIR] [--prune-depth=<pruneDepth>]
[--uris-file=<urisFile>] [--prune-others=GLOB[,
GLOB...]]... [URI[,URI...]...]
Download a file
[URI[,URI...]...] The URI of the resource to retrieve. When the
output is a directory, more than one URI can be
requested.
--accept=<acceptHeader>
Specifies the accept header to use with the request
--exists Test if the given URIs are retrievable
-h, --help Show this usage and exit
--json-path=<jsonPath>
Extract and output a JsonPath from the response
--log-progress-each Output a log as each URI is being retrieved
-o, --output=FILE|DIR Specifies the name of a file or directory to write
the downloaded content. If a directory is
provided, the filename will be derived from the
content disposition or the URI's path. If not
provided, then content will be output to standard
out.
--output-filename Output the resulting filename
--prune-depth=<pruneDepth>
When using prune-others, this specifies how deep to
search for files to prune
--prune-others=GLOB[,GLOB...]
When set and using an output directory, files that
match the given glob patterns will be pruned if
not part of the download set. For example *.jar
-s, --silent Don't output logs even if there's an error
--skip-existing Do not retrieve if the output file already exists
--uris-file=<urisFile>
A file that contains a URL per line
-z, --skip-up-to-date Skips re-downloading a file that is up to date
install-curseforge
Usage: mc-image-helper install-curseforge [-h] [--force-synchronize]
[--file-id=<fileId>] [--filename-matcher=STR] [--modpack-page-url=URL]
[--output-directory=DIR] [--parallel-downloads=<parallelDownloads>]
[--results-file=FILE] [--slug=<slug>] [--exclude-include-file=FILE |
[[--exclude-mods=PROJECT_ID|SLUG[,| PROJECT_ID|SLUG...]]...
[--force-include-mods=PROJECT_ID|SLUG[,| PROJECT_ID|SLUG...]]...]]
[COMMAND]
--exclude-include-file=FILE
A JSON file that contains global and per modpack
exclude/include declarations. See README for
schema.
--exclude-mods=PROJECT_ID|SLUG[,| PROJECT_ID|SLUG...]
For mods that need to be excluded from server
deployments, such as those that don't label as
client
--file-id=<fileId>
--filename-matcher=STR
Substring to select specific modpack filename
--force-include-mods=PROJECT_ID|SLUG[,| PROJECT_ID|SLUG...]
Some mods incorrectly declare client-only support,
but still need to be included in a server deploy
--force-synchronize
-h, --help
--modpack-page-url=URL
URL of a modpack page such as https://www.
curseforge.
com/minecraft/modpacks/all-the-mods-8or a file
page https://www.curseforge.
com/minecraft/modpacks/all-the-mods-8/files/424839
0
--output-directory=DIR
--parallel-downloads=<parallelDownloads>
Default: 4
--results-file=FILE A key=value file suitable for scripted environment
variables. Currently includes
SERVER: the entry point jar or script
--slug=<slug> The short-URL identifier
Commands:
schemas Output relevant JSON schemas
Exclude/Include File Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Mods Exclude/Include File Content",
"type": "object",
"additionalProperties": false,
"properties": {
"globalExcludes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Mods by slug|id to exclude for all modpacks"
},
"globalForceIncludes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Mods by slug|id to force include for all modpacks"
},
"modpacks": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/ExcludeIncludes"
},
"description": "Specific exclude/includes by modpack slug"
}
},
"definitions": {
"ExcludeIncludes": {
"type": "object",
"additionalProperties": false,
"properties": {
"excludes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Mods by slug|id to exclude for this modpack"
},
"forceIncludes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Mods by slug|id to force include for this modpack"
}
}
}
}
}install-fabric-loader
Usage: mc-image-helper install-fabric-loader [-h] [--output-directory=DIR]
[--results-file=FILE] (--from-local-file=FILE | --from-url=URL |
[--minecraft-version=VERSION [--installer-version=VERSION]
[--loader-version=VERSION]])
Provides a few ways to obtain a Fabric loader with simple cleanup of previous
loader instances
--from-local-file=FILE
--from-url=URL
-h, --help
--installer-version=VERSION
By default the latest installer version is used
--loader-version=VERSION
By default the latest launcher version is used
--minecraft-version=VERSION
--output-directory=DIR
--results-file=FILE A key=value file suitable for scripted environment
variables. Currently includes
SERVER: the entry point jar or script
install-forge
Usage: mc-image-helper install-forge [-hV] [--forge-version=<forgeVersion>]
--minecraft-version=<minecraftVersion>
[--output-directory=DIR]
[--results-file=<resultsFile>]
--forge-version=<forgeVersion>
A specific Forge version or to auto-resolve the version
provide 'latest' or 'recommended'. Default value is
recommended
-h, --help Show this help message and exit.
--minecraft-version=<minecraftVersion>
--output-directory=DIR
--results-file=<resultsFile>
A key=value file suitable for scripted environment variables.
Currently includes
SERVER: the entry point jar or script
install-modrinth-modpack
Usage: mc-image-helper install-modrinth-modpack [-hV]
[--force-modloader-reinstall] [--force-synchronize]
[--api-base-url=<baseUrl>] [--default-version-type=TYPE]
[--game-version=<gameVersion>] [--loader=<loader>]
[--output-directory=DIR] --project=<modpackProject>
[--results-file=FILE] [--version-id=<versionId>]
[[--tls-handshake-timeout=DURATION] [--http-response-timeout=DURATION]
[--connection-pool-max-idle-timeout=DURATION]]
Supports installation of Modrinth modpacks along with the associated mod loader
--api-base-url=<baseUrl>
Default: https://api.modrinth.com/v2
--connection-pool-max-idle-timeout=DURATION
--default-version-type=TYPE
Valid values: release, beta, alpha
Default: release
--force-modloader-reinstall
--force-synchronize
--game-version=<gameVersion>
Applicable Minecraft version where default is any
version
-h, --help Show this help message and exit.
--http-response-timeout=DURATION
The response timeout to apply to HTTP operations.
Parsed from ISO-8601 format. Default: PT30S
--loader=<loader> Valid values: fabric, forge where default is any
loader
--output-directory=DIR
--project=<modpackProject>
One of
- Project ID or slug
- Project page URL
- Project file URL
--results-file=FILE A key=value file suitable for scripted environment
variables. Currently includes
SERVER: the entry point jar or script
--tls-handshake-timeout=DURATION
Default: PT30S
-V, --version Print version information and exit.
--version-id=<versionId>
Version ID (not name) from the file's metadata
interpolate
Usage: mc-image-helper interpolate [-h] ([--replace-env-prefix=<prefix>]
[--replace-env-excludes=FILENAME[,
FILENAME...]]...
[--replace-env-exclude-paths=PATH[,
PATH...]]... --replace-env-file-suffixes=PATH
[,PATH...] [--replace-env-file-suffixes=PATH
[,PATH...]]...) [DIRECTORY...]
Interpolates existing files in one or more directories
[DIRECTORY...]
-h, --help Show this usage and exit
--replace-env-exclude-paths=PATH[,PATH...]
Destination paths that will be excluded from processing
--replace-env-excludes=FILENAME[,FILENAME...]
Filenames (without path) that should be excluded from
processing.
--replace-env-file-suffixes=PATH[,PATH...]
Filename suffixes (without dot) that should be
processed. For example: txt,json,yaml
--replace-env-prefix=<prefix>
Only placeholder variables with this prefix will be
processed.
Default: CFG_
maven-download
Usage: mc-image-helper maven-download [-h] [--print-filename] [--skip-existing]
[--skip-up-to-date] -a=<artifact>
[--classifier=<classifier>] -g=<group>
[--output-directory=<outputDirectory>]
[--packaging=<packaging>]
[-r=<mavenRepo>] [-v=<version>]
Downloads a maven artifact from a Maven repository
-a, -m, --module, --artifact=<artifact>
--classifier=<classifier>
-g, --group=<group>
-h, --help
--output-directory=<outputDirectory>
--packaging=<packaging>
--print-filename
-r, --maven-repo=<mavenRepo>
--skip-existing
--skip-up-to-date
-v, --version=<version>
mcopy
Usage: mc-image-helper mcopy [-hz] [--file-is-listing] [--skip-existing]
[--glob=GLOB] [--scope=<manifestId>] --to=<dest>
SRC[,SRC...]...
Multi-source file copy operation with with managed cleanup. Supports
auto-detected sourcing from file list, directories, and URLs
SRC[,SRC...]... Any mix of source file, directory, or URL that can be
optionally comma-separated.
--file-is-listing Source files or URLs are processed as a line
delimited list of sources.
For remote listing files, the contents must all be
file URLs.
--glob=GLOB When a source is a directory, this filename glob will
be applied to select files.
-h, --help
--scope, --manifest-id=<manifestId>
If managed cleanup is required, this is the
identifier used for qualifying manifest filename in
destination
--skip-existing
--to, --output-directory=<dest>
-z, --skip-up-to-date
patch
Usage: mc-image-helper patch [-h] [--patch-env-prefix=<envPrefix>] FILE_OR_DIR
FILE_OR_DIR Path to a PatchSet json file or directory containing
PatchDefinition json files
-h, --help Show this usage and exit
--patch-env-prefix=<envPrefix>
Only placeholder variables with this prefix will be
processed
Default: CFG_
See below for a description of PatchSet and PatchDefinition JSON schemas.
install-quilt
Usage: mc-image-helper install-quilt [-h] [--force-reinstall]
[--loader-version=VERSION]
[--minecraft-version=VERSION]
[--output-directory=DIR]
[--repo-url=<repoUrl>]
[--results-file=FILE] [--installer-url=URL
| --installer-version=VERSION]
[[--tls-handshake-timeout=DURATION]
[--connection-pool-max-idle-timeout=DURATIO
N] [--http-response-timeout=DURATION]]
Installs Quilt mod loader
--connection-pool-max-idle-timeout=DURATION
--force-reinstall
-h, --help
--http-response-timeout=DURATION
The response timeout to apply to HTTP operations.
Parsed from ISO-8601 format. Default: PT30S
--installer-url=URL
--installer-version=VERSION
Default uses latest
--loader-version=VERSION
Default uses latest
--minecraft-version=VERSION
'latest', 'snapshot', or specific version
--output-directory=DIR
--repo-url=<repoUrl> Default: https://maven.quiltmc.
org/repository/release
--results-file=FILE A key=value file suitable for scripted environment
variables. Currently includes
SERVER: the entry point jar or script
--tls-handshake-timeout=DURATION
Default: PT30S
sync-and-interpolate
Usage: mc-image-helper sync-and-interpolate [-h] [--skip-newer-in-destination]
([--replace-env-prefix=<prefix>] [--replace-env-excludes=FILENAME[,
FILENAME...]]... [--replace-env-exclude-paths=PATH[,PATH...]]...
--replace-env-file-suffixes=PATH[,PATH...]
[--replace-env-file-suffixes=PATH[,PATH...]]...) <src> <dest>
Synchronizes the contents of one directory to another with conditional variable
interpolation.
<src> source directory
<dest> destination directory
-h, --help Show this usage and exit
--replace-env-exclude-paths=PATH[,PATH...]
Destination paths that will be excluded from processing
--replace-env-excludes=FILENAME[,FILENAME...]
Filenames (without path) that should be excluded from processing.
--replace-env-file-suffixes=PATH[,PATH...]
Filename suffixes (without dot) that should be processed. For
example: txt,json,yaml
--replace-env-prefix=<prefix>
Only placeholder variables with this prefix will be processed.
Default: CFG_
--skip-newer-in-destination
Skip any files that exist in the destination and have a newer
modification time than the source.
Patch Schemas
PatchSet
patches: array of PatchDefinition
Example
{
"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"
}
}
]
}
]
}PatchDefinition
file: Path to the file to patchfile-format: optional If non-null, declares a specifically supported format name: json, yaml. Otherwise, the file format is detected by the file's suffix.ops: array of PatchOperation
Example:
{
"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"
}
}
]
}PatchOperation
Each patch operation object contains a single key that one is one of the following sections and then an object within each. For example { "$set" : { ... } }.
$set
The $set operation can set an existing field to a new value. If a new field needs to be added, use the $put operation.
$set
Example:
{
"$set": {
"path": "$.verbose",
"value": true
}
}$put
The $put operation can add or update a field with the given key within an object.
$putpath: The JSON path to the object containing key to setkey: The key to setvalue: The value to set. If the given value is a string, variable placeholders of the form${...}will be replaced from the environment variables and the resulting string can be converted by setting value-type.value-type: optional see below
Example:
{
"$put": {
"path": "$.settings",
"key": "my-test-setting",
"value": "testing"
}
}ValueType
One of the following identifiers or can be prefixed with list of to indicate a list of the identified type:
- int : integer/whole value
- float : numerical value with an optional decimal part
- bool : boolean value of
trueorfalse - auto : where the text value is attempted to be converted into one of the above