Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/itzg/mc-image-helper
This tool does the complicated bits for the itzg/minecraft-server image
https://github.com/itzg/mc-image-helper
cli docker minecraft-server
Last synced: 17 days ago
JSON representation
This tool does the complicated bits for the itzg/minecraft-server image
- Host: GitHub
- URL: https://github.com/itzg/mc-image-helper
- Owner: itzg
- License: mit
- Created: 2021-09-09T23:09:45.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2024-10-15T23:30:16.000Z (28 days ago)
- Last Synced: 2024-10-17T10:13:52.481Z (27 days ago)
- Topics: cli, docker, minecraft-server
- Language: Java
- Homepage:
- Size: 1.49 MB
- Stars: 56
- Watchers: 2
- Forks: 26
- Open Issues: 44
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://github.com/itzg/mc-image-helper/releases/latest)
[](https://github.com/itzg/mc-image-helper/actions/workflows/test.yml)
This tool does the complicated bits for the [itzg/minecraft-server](https://github.com/itzg/docker-minecraft-server) and [itzg/bungeecord](https://github.com/itzg/docker-bungeecord/) Docker images.
## Usage
> **NOTE** The following documentation may not always be up-to-date. Please be sure to use `-h` or `--help` after 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=]
[--max-depth=N] [-t=] [--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= 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= Valid values: file, directory
```
### get
```
Usage: mc-image-helper get [-hsz] [--exists] [--log-progress-each]
[--output-filename] [--skip-existing]
[--accept=] [--json-path=]
[-o=FILE|DIR] [--prune-depth=]
[--uris-file=] [--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=
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=
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=
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=
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=] [--filename-matcher=STR] [--modpack-page-url=URL]
[--output-directory=DIR] [--parallel-downloads=]
[--results-file=FILE] [--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=
--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=
Default: 4
--results-file=FILE A key=value file suitable for scripted environment
variables. Currently includes
SERVER: the entry point jar or script
--slug= The short-URL identifier
Commands:
schemas Output relevant JSON schemas
```
#### Exclude/Include File Schema
```json
{
"$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=]
--minecraft-version=
[--output-directory=DIR]
[--results-file=]
--forge-version=
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=
--output-directory=DIR
--results-file=
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=] [--default-version-type=TYPE]
[--game-version=] [--loader=]
[--output-directory=DIR] --project=
[--results-file=FILE] [--version-id=]
[[--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=
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=
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= Valid values: fabric, forge where default is any
loader
--output-directory=DIR
--project=
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=
Version ID (not name) from the file's metadata
```
### interpolate
```
Usage: mc-image-helper interpolate [-h] ([--replace-env-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=
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=
[--classifier=] -g=
[--output-directory=]
[--packaging=]
[-r=] [-v=]
Downloads a maven artifact from a Maven repository
-a, -m, --module, --artifact=
--classifier=
-g, --group=
-h, --help
--output-directory=
--packaging=
--print-filename
-r, --maven-repo=
--skip-existing
--skip-up-to-date
-v, --version=
```
### mcopy
```
Usage: mc-image-helper mcopy [-hz] [--file-is-listing] [--skip-existing]
[--glob=GLOB] [--scope=] --to=
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=
If managed cleanup is required, this is the
identifier used for qualifying manifest filename in
destination
--skip-existing
--to, --output-directory=
-z, --skip-up-to-date
```
### patch
Supports the file formats:
- JSON
- JSON5
- Yaml
- TOML, but processed output is not pretty
```
Usage: mc-image-helper patch [-h] [--patch-env-prefix=] 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=
Only placeholder variables with this prefix will be
processed
Default: CFG_
```
[See below](#patch-schemas) for a description of [PatchSet](#patchset) and [PatchDefinition](#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=]
[--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= 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=] [--replace-env-excludes=FILENAME[,
FILENAME...]]... [--replace-env-exclude-paths=PATH[,PATH...]]...
--replace-env-file-suffixes=PATH[,PATH...]
[--replace-env-file-suffixes=PATH[,PATH...]]...)
Synchronizes the contents of one directory to another with conditional variable
interpolation.
source directory
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=
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](#patchdefinition)
Example
```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"
}
}
]
}
]
}
```
### PatchDefinition
- `file` : Path to the file to patch
- `file-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](#patchoperation)
Example:
```json
{
"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](#put) operation.
- `$set`
- `path` : The [JSON path](https://github.com/json-path/JsonPath#readme) to the field to set
- `value` : 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](#valuetype)
Example:
```json
{
"$set": {
"path": "$.verbose",
"value": true
}
}
```
#### `$put`
The `$put` operation can add or update a field with the given key within an object.
- `$put`
- `path` : The [JSON path](https://github.com/json-path/JsonPath#readme) to the object containing key to set
- `key` : The key to set
- `value` : 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](#valuetype)
Example:
```json
{
"$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 `true` or `false`
- auto : where the text value is attempted to be converted into one of the above