Mirrors/docker-minecraft-server
2
0
Fork 0
mirror of https://github.com/itzg/docker-minecraft-server synced 2024-11-10 06:14:14 +00:00
Code Issues Projects Releases Packages Wiki Activity

Clearer differentiation of mod platforms and types (#2179)

Browse source 
Also, skip version resolution for mod platforms.
This commit is contained in:
Geoff Bourne 2023-06-08 08:52:08 -05:00 committed by GitHub
parent 821428c8b1
commit 3c1a83cc6a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
19 changed files with 353 additions and 308 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/index.md
View file

@ -30,4 +30,4 @@ where, in this case, the standard server port 25565, will be exposed on your hos
**DO NOT** port forward RCON on 25575 without first setting `RCON_PASSWORD` to a secure value. It is highly recommended to only use RCON within the container, such as with `rcon-cli`.
By default, the container will download the latest version of the "vanilla" [Minecraft: Java Edition server](https://www.minecraft.net/en-us/download/server) provided by Mojang. The [`VERSION`](versions/java.md) and the [`TYPE`](server-types/bukkit-spigot.md) can be configured to create many variations of desired Minecraft server.
By default, the container will download the latest version of the "vanilla" [Minecraft: Java Edition server](https://www.minecraft.net/en-us/download/server) provided by Mojang. The [`VERSION`](versions/java.md) and the [`TYPE`](types-and-platforms/) can be configured to create many variations of desired Minecraft server.

65
docs/mods-and-plugins/forge-api.md Normal file
View file

@ -0,0 +1,65 @@
# Forge API
## ForgeAPI usage to use non-version specific projects
!!! warning "Deprecated"
This approach will soon be deprecated in favor of a variation of `AUTO_CURSEFORGE`.
!!! warning
This potentially could lead to unexpected behavior if the Mod receives an update with unexpected behavior.
This is more complicated because you will be pulling/using the latest mod for the release of your game. To get started make sure you have a [CursedForge API Key](https://docs.curseforge.com/#getting-started). Then use the environmental parameters in your docker build.
Please be aware of the following when using these options for your mods:
* Mod Release types: Release, Beta, and Alpha.
* Mod dependencies: Required and Optional
* Mod family: Fabric, Forge, and Bukkit.
Parameters to use the ForgeAPI:
* `MODS_FORGEAPI_KEY` - Required
* `MODS_FORGEAPI_FILE` - Required or use MODS_FORGEAPI_PROJECTIDS (Overrides MODS_FORGEAPI_PROJECTIDS)
* `MODS_FORGEAPI_PROJECTIDS` - Required or use MODS_FORGEAPI_FILE
* `MODS_FORGEAPI_RELEASES` - Default is release, Options: [Release|Beta|Alpha]
* `MODS_FORGEAPI_DOWNLOAD_DEPENDENCIES` - Default is False, attempts to download required mods (releaseType Release) defined in Forge.
* `MODS_FORGEAPI_IGNORE_GAMETYPE` - Default is False, Allows for filtering mods on family type: FORGE, FABRIC, and BUKKIT. (Does not filter for Vanilla or custom)
* `REMOVE_OLD_FORGEAPI_MODS` - Default is False
* `REMOVE_OLD_DATAPACKS_DEPTH` - Default is 1
* `REMOVE_OLD_DATAPACKS_INCLUDE` - Default is *.jar
Example of expected forge api project ids, releases, and key:
```yaml
MODS_FORGEAPI_PROJECTIDS: 306612,256717
MODS_FORGEAPI_RELEASES: Release
MODS_FORGEAPI_KEY: $WRX...
```
Example of expected ForgeAPI file format.
**Field Description**:
* `name` is currently unused, but can be used to document each entry.
* `projectId` id is the id found on the CurseForge website for a particular mod
* `releaseType` Type corresponds to forge's R, B, A icon for each file. Default Release, options are (release|beta|alpha).
* `fileName` is used for version pinning if latest file will not work for you.
```json
[
{
"name": "fabric api",
"projectId": "306612",
"releaseType": "release"
},
{
"name": "fabric voice mod",
"projectId": "416089",
"releaseType": "beta"
},
{
"name": "Biomes o plenty",
"projectId": "220318",
"fileName": "BiomesOPlenty-1.18.1-15.0.0.100-universal.jar",
"releaseType": "release"
}
]
```

46
docs/mods-and-plugins/index.md
View file

@ -1,3 +1,13 @@
# Working with mods and plugins
## Mod platforms
By far the easiest way to work with mod and plugins, especially large numbers of them, is to utilize [one of the supported mod platforms](../types-and-platforms/), such as Modrinth or CurseForge.
## Download automation
On the left, there are sections describing some download automation options.
## Optional plugins, mods, and config attach points
There are optional volume paths that can be attached to supply content to be copied into the data area:
@ -23,42 +33,6 @@ These paths work well if you want to have a common set of modules in a separate
> For more flexibility with mods/plugins preparation, you can declare directories to use in [the `MODS` variable](#zip-file-modpack)
## Auto-downloading SpigotMC/Bukkit/PaperMC plugins with Spiget
The `SPIGET_RESOURCES` variable can be set with a comma-separated list of SpigotMC resource IDs to automatically download [SpigotMC resources/plugins](https://www.spigotmc.org/resources/) using [the spiget API](https://spiget.org/). Resources that are zip files will be expanded into the plugins directory and resources that are simply jar files will be moved there.
> NOTE: the variable is purposely spelled SPIG**E**T with an "E"
The **resource ID** can be located from the numerical part of the URL after the shortname/slug and a dot. For example, the ID is **28140** from
https://www.spigotmc.org/resources/luckperms.28140/
=====
For example, the following will auto-download the [LuckPerms](https://www.spigotmc.org/resources/luckperms.28140/) and [Vault](https://www.spigotmc.org/resources/vault.34315/) plugins:
-e SPIGET_RESOURCES=28140,34315
!!! note
Some plugins, such as EssentialsX (resource ID 9089), do not permit automated downloads via Spiget. Instead you will need to pre-download the desired file and supply it to the container, such as using the `/plugins` mount point, described above.
## Auto-download mods and plugins from Modrinth
[Modrinth](https://modrinth.com/) is an open source modding platform with a clean, easy to use website for finding [Fabric and Forge mods](https://modrinth.com/mods). At startup, the container will automatically locate and download the newest versions of mod/plugin files that correspond to the `TYPE` and `VERSION` in use. Older file versions downloaded previously will automatically be cleaned up.
- **MODRINTH_PROJECTS** : comma separated list of project slugs (short name) or IDs. The project ID can be located in the "Technical information" section. The slug is the part of the page URL that follows `/mod/`:
```
https://modrinth.com/mod/fabric-api
----------
|
+-- project slug
```
Also, specific version/type can be declared using colon symbol and version id/type after the project slug. The version id can be found at 'Metadata' section. Valid version types are `release`, `beta`, `alpha`. For instance:
```
-e MODRINTH_PROJECTS=fabric-api,fabric-api:PbVeub96,fabric-api:beta
```
- **MODRINTH_DOWNLOAD_OPTIONAL_DEPENDENCIES**=true : required dependencies of the project will _always_ be downloaded and optional dependencies can also be downloaded by setting this to `true`
- **MODRINTH_ALLOWED_VERSION_TYPE**=release : the version type is used to determine the newest version to use from each project. The allowed values are `release`, `beta`, `alpha`.
## Zip file modpack
Like the `WORLD` option above, you can specify the URL or path of a "mod pack"

18
docs/mods-and-plugins/modrinth.md Normal file
View file

@ -0,0 +1,18 @@
# Auto-download from Modrinth
[Modrinth](https://modrinth.com/) is an open source modding platform with a clean, easy to use website for finding [Fabric and Forge mods](https://modrinth.com/mods). At startup, the container will automatically locate and download the newest versions of mod/plugin files that correspond to the `TYPE` and `VERSION` in use. Older file versions downloaded previously will automatically be cleaned up.
- **MODRINTH_PROJECTS** : comma separated list of project slugs (short name) or IDs. The project ID can be located in the "Technical information" section. The slug is the part of the page URL that follows `/mod/`:
```
https://modrinth.com/mod/fabric-api
----------
|
+-- project slug
```
Also, specific version/type can be declared using colon symbol and version id/type after the project slug. The version id can be found at 'Metadata' section. Valid version types are `release`, `beta`, `alpha`. For instance:
```
-e MODRINTH_PROJECTS=fabric-api,fabric-api:PbVeub96,fabric-api:beta
```
- **MODRINTH_DOWNLOAD_OPTIONAL_DEPENDENCIES**=true : required dependencies of the project will _always_ be downloaded and optional dependencies can also be downloaded by setting this to `true`
- **MODRINTH_ALLOWED_VERSION_TYPE**=release : the version type is used to determine the newest version to use from each project. The allowed values are `release`, `beta`, `alpha`.

19
docs/mods-and-plugins/spiget.md Normal file
View file

@ -0,0 +1,19 @@
# Auto-download using Spiget
The `SPIGET_RESOURCES` variable can be set with a comma-separated list of SpigotMC resource IDs to automatically download [Spigot/Bukkit/Paper plugins](https://www.spigotmc.org/resources/) using [the spiget API](https://spiget.org/). Resources that are zip files will be expanded into the plugins directory and resources that are simply jar files will be moved there.
!!! important "SPIGET not SPIGOT"
The variable is purposely spelled SPIG**E**T with an "E"
The **resource ID** can be located from the numerical part of the URL after the shortname/slug and a dot. For example, the ID is **28140** from
https://www.spigotmc.org/resources/luckperms.28140/
=====
For example, the following will auto-download the [LuckPerms](https://www.spigotmc.org/resources/luckperms.28140/) and [Vault](https://www.spigotmc.org/resources/vault.34315/) plugins:
-e SPIGET_RESOURCES=28140,34315
!!! note
Some plugins, such as EssentialsX (resource ID 9089), do not permit automated downloads via Spiget. Instead, you will need to pre-download the desired file and supply it to the container, such as using the `/plugins` mount point, described [in the main section](index.md).

14
docs/types-and-platforms/index.md Normal file
View file

@ -0,0 +1,14 @@
# Server Types and Mod Platforms
Server types can be selected by setting the `TYPE` environment variable to one of the types described in these sections.
The default server type is [the official software provided by Mojang](https://www.minecraft.net/en-us/download/server), which can be explicitly selected by setting `TYPE` to "VANILLA".
**From the sections to the left...**
The **mod platforms** take a modpack identifier, file, etc and use that to select and download the appropriate version of a mod loader, such as Forge or Fabric, downloading declared mods/plugins, and apply any additional files. The mod platforms are selected by setting `MOD_PLATFORM`; however, for ease of use and compatibility, the selection can be set in `TYPE`.
The individual **server types** allow for selecting the mod loader / server type and specific versions of those.
!!! important
For all the server types, the `VERSION` environment variable is used to declare the Minecraft version itself, such as 1.19.4. Each server type will have specific variables for qualifying their version in addition to the Minecraft version.

332
docs/mods-and-plugins/curseforge.md → docs/types-and-platforms/mod-platforms/auto-curseforge.md
View file

@ -1,220 +1,112 @@
## Auto CurseForge Management
To manage a CurseForge modpack automatically with upgrade support, pinned or latest version tracking, set `TYPE` to "AUTO_CURSEFORGE". The appropriate mod loader (Forge / Fabric) version will be automatically installed as declared by the modpack. This mode will also take care of cleaning up unused files installed by previous versions of the modpack, but world data is never auto-removed.
### API Key
!!! warning "CurseForge API key usage"
A CurseForge API key is **required** to use this feature. Go to their [developer console](https://console.curseforge.com/), generate an API key, and set the environment variable `CF_API_KEY`.
When entering your API Key in a docker compose file you will need to escape any `$` character with a second `$`.
Example if your key is `$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa`:
```yaml
environment:
CF_API_KEY: '$$11$$22$$33aaaaaaaaaaaaaaaaaaaaaaaaaa'
```
If you use `docker run` you will need to make sure to use single quotes:
```shell
docker run ... -e CF_API_KEY='$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa'
```
To avoid exposing the API key, it is highly recommended to use a `.env` file, which is [loaded automatically by docker compose](https://docs.docker.com/compose/environment-variables/set-environment-variables/#substitute-with-an-env-file). `$`'s in the value still need to escaped with a second `$` and the variable needs to be referenced from the compose file, such as:
```yaml
environment:
CF_API_KEY: ${CF_API_KEY}
```
To use the equivalent with `docker run` you need to specify the `.env` file explicitly:
```
docker run --env-file=.env itzg/minecraft-server
```
!!! note
Be sure to use the appropriate [image tag for the Java version compatible with the modpack](../versions/java.md).
Most modpacks require a good amount of memory, so it best to set `MEMORY` to at least "4G" since the default is only 1 GB.
### Usage
Use one of the following to specify the modpack to install:
Pass a page URL to the modpack or a specific file with `CF_PAGE_URL` such as the modpack page "https://www.curseforge.com/minecraft/modpacks/all-the-mods-8" or a specific file "https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390". For example:
```
-e TYPE=AUTO_CURSEFORGE -e CF_PAGE_URL=https://www.curseforge.com/minecraft/modpacks/all-the-mods-8
```
Instead of a URL, the modpack slug can be provided as `CF_SLUG`. The slug is the short identifier visible in the URL after "/modpacks/", such as
![cf-slug](../img/cf-slug.png)
For example:
```
-e TYPE=AUTO_CURSEFORGE -e CF_SLUG=all-the-mods-8
```
For mod, modpacks, and world files that are not allowed for automated download, the container path `/downloads` can be attached and matching files will be retrieved from there. The subdirectories `mods`, `modpacks`, and `worlds` will also be checked accordingly. To change the source location of downloaded files, set `CF_DOWNLOADS_REPO` to an existing container path. To disable this feature, set `CF_DOWNLOADS_REPO` to an empty string.
If the authors of the modpack have disallowed project distribution, then the desired **client** modpack zip will need to be manually downloaded and made available to the container. The path to that file must be passed to `CF_MODPACK_ZIP`. Similarly, the container path to a modpack manifest JSON can be passed to `CF_MODPACK_MANIFEST`. In either case, the modpack slug or page URL must still be provided.
The latest file will be located and used by default, but if a specific version is desired you can use one of the following options. With any of these options **do not select a server file** -- they lack the required manifest and defeat the ability to consistently automate startup.
- Use `CF_PAGE_URL`, but include the full URL to a specific file
- Set `CF_FILE_ID` to the numerical file ID
- Specify a substring to match the desired filename with `CF_FILENAME_MATCHER`
The following shows where to get the URL to the specific file and also shows where the file ID is located:
![cf-file-id](../img/cf-file-id.png)
The following examples all refer to version 1.0.7 of ATM8:
```
-e CF_PAGE_URL=https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390
```
```
-e CF_SLUG=all-the-mods-8 -e CF_FILE_ID=4248390
```
```
-e CF_SLUG=all-the-mods-8 -e CF_FILENAME_MATCHER=1.0.7
```
### Exlude client mods
Quite often there are mods that need to be excluded, such as ones that did not properly declare as a client mod via the file's game versions. Similarly, there are some mods that are incorrectly tagged as client only. The following describes two options to exclude/include mods:
Mods can be excluded by passing a comma or space delimited list of **project** slugs or IDs via `CF_EXCLUDE_MODS`. Similarly, there are some mods that are incorrectly tagged as client only. For those, pass the **project** slugs or IDs via `CF_FORCE_INCLUDE_MODS`. These lists will be combined with the content of the exclude/include file, if given.
A mod's project ID can be obtained from the right hand side of the project page:
![cf-project-id](../img/cf-project-id.png)
For more complex scenarios, global and per modpack exclusions can be declared in a container-accessible JSON file and referenced with `CF_EXCLUDE_INCLUDE_FILE`. By default, [the file bundled with the image](https://raw.githubusercontent.com/itzg/docker-minecraft-server/master/files/cf-exclude-include.json) will be used, but can be disabled by setting this to an empty string. The schema of this file [is documented here](https://github.com/itzg/mc-image-helper#excludeinclude-file-schema).
If needing to iterate on the options above, set `CF_FORCE_SYNCHRONIZE` to "true" to ensure the exclude/includes are re-evaluated.
!!! important
These options are provided to empower you to get your server up and running quickly. Please help out by reporting an issue with the respective mod project. Ideally mod developers should [use correct registrations for one-sided client mods](https://docs.minecraftforge.net/en/latest/concepts/sides/#writing-one-sided-mods). Understandably, those code changes may be non-trivial, so mod authors can also add "Client" to the game versions when publishing.
### Extra options
Some modpacks come with world/save data via a worlds file and/or the overrides provided with the modpack. Either approach can be selected to set the `LEVEL` to the resulting saves directory by setting `CF_SET_LEVEL_FROM` to either:
- `WORLD_FILE`
- `OVERRIDES`
Other configuration available:
- `CF_PARALLEL_DOWNLOADS` (default is 4): specify how many parallel mod downloads to perform
- `CF_OVERRIDES_SKIP_EXISTING` (default is false): if set, files in the overrides that already exist in the data directory are skipped. **NOTE** world data is always skipped, if present.
## Old approach
Enable this server mode by adding `-e TYPE=CURSEFORGE` to your command-line,
but note the following additional steps needed...
You need to specify a modpack to run, using the `CF_SERVER_MOD` environment
variable. A CurseForge server modpack is available together with its respective
client modpack at <https://www.curseforge.com/minecraft/modpacks> .
Now you can add a `-e CF_SERVER_MOD=name_of_modpack.zip` to your command-line.
docker run -d -v /path/on/host:/data -e TYPE=CURSEFORGE \
-e CF_SERVER_MOD=SkyFactory_4_Server_4.1.0.zip \
-p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
If you want to keep the pre-download modpacks separate from your data directory,
then you can attach another volume at a path of your choosing and reference that.
The following example uses `/modpacks` as the container path as the pre-download area:
docker run -d -v /path/on/host:/data -v /path/to/modpacks:/modpacks \
-e TYPE=CURSEFORGE \
-e CF_SERVER_MOD=/modpacks/SkyFactory_4_Server_4.1.0.zip \
-p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
### Modpack data directory
By default, CurseForge modpacks are expanded into the sub-directory `/data/FeedTheBeast` and executed from there. (The default location was chosen for legacy reasons, when Curse and FTB were maintained together.)
The directory can be changed by setting `CF_BASE_DIR`, such as `-e CF_BASE_DIR=/data`.
### Buggy start scripts
Some modpacks have buggy or overly complex start scripts. You can avoid using the bundled start script and use this image's standard server-starting logic by adding `-e USE_MODPACK_START_SCRIPT=false`.
### Fixing "unable to launch forgemodloader"
If your server's modpack fails to load with an error [like this](https://support.feed-the-beast.com/t/cant-start-crashlanding-server-unable-to-launch-forgemodloader/6028/2):
unable to launch forgemodloader
then you apply a workaround by adding this to the run invocation:
-e FTB_LEGACYJAVAFIXER=true
## ForgeAPI usage to use non-version specific projects
!!! warning "Deprecated"
This approach will soon be deprecated in favor of a variation of `AUTO_CURSEFORGE` mechanism described above.
!!! warning
This potentially could lead to unexpected behavior if the Mod receives an update with unexpected behavior.
This is more complicated because you will be pulling/using the latest mod for the release of your game. To get started make sure you have a [CursedForge API Key](https://docs.curseforge.com/#getting-started). Then use the environmental parameters in your docker build.
Please be aware of the following when using these options for your mods:
* Mod Release types: Release, Beta, and Alpha.
* Mod dependencies: Required and Optional
* Mod family: Fabric, Forge, and Bukkit.
Parameters to use the ForgeAPI:
* `MODS_FORGEAPI_KEY` - Required
* `MODS_FORGEAPI_FILE` - Required or use MODS_FORGEAPI_PROJECTIDS (Overrides MODS_FORGEAPI_PROJECTIDS)
* `MODS_FORGEAPI_PROJECTIDS` - Required or use MODS_FORGEAPI_FILE
* `MODS_FORGEAPI_RELEASES` - Default is release, Options: [Release|Beta|Alpha]
* `MODS_FORGEAPI_DOWNLOAD_DEPENDENCIES` - Default is False, attempts to download required mods (releaseType Release) defined in Forge.
* `MODS_FORGEAPI_IGNORE_GAMETYPE` - Default is False, Allows for filtering mods on family type: FORGE, FABRIC, and BUKKIT. (Does not filter for Vanilla or custom)
* `REMOVE_OLD_FORGEAPI_MODS` - Default is False
* `REMOVE_OLD_DATAPACKS_DEPTH` - Default is 1
* `REMOVE_OLD_DATAPACKS_INCLUDE` - Default is *.jar
Example of expected forge api project ids, releases, and key:
```yaml
MODS_FORGEAPI_PROJECTIDS: 306612,256717
MODS_FORGEAPI_RELEASES: Release
MODS_FORGEAPI_KEY: $WRX...
```
Example of expected ForgeAPI file format.
**Field Description**:
* `name` is currently unused, but can be used to document each entry.
* `projectId` id is the id found on the CurseForge website for a particular mod
* `releaseType` Type corresponds to forge's R, B, A icon for each file. Default Release, options are (release|beta|alpha).
* `fileName` is used for version pinning if latest file will not work for you.
```json
[
{
"name": "fabric api",
"projectId": "306612",
"releaseType": "release"
},
{
"name": "fabric voice mod",
"projectId": "416089",
"releaseType": "beta"
},
{
"name": "Biomes o plenty",
"projectId": "220318",
"fileName": "BiomesOPlenty-1.18.1-15.0.0.100-universal.jar",
"releaseType": "release"
}
]
```
# Auto CurseForge
To manage a CurseForge modpack automatically with upgrade support, pinned or latest version tracking, set `MOD_PLATFORM` or `TYPE` to "AUTO_CURSEFORGE". The appropriate mod loader (Forge / Fabric) version will be automatically installed as declared by the modpack. This mode will also take care of cleaning up unused files installed by previous versions of the modpack, but world data is never auto-removed.
## API Key
!!! warning "CurseForge API key usage"
A CurseForge API key is **required** to use this feature. Go to their [developer console](https://console.curseforge.com/), generate an API key, and set the environment variable `CF_API_KEY`.
When entering your API Key in a docker compose file you will need to escape any `$` character with a second `$`.
Example if your key is `$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa`:
```yaml
environment:
CF_API_KEY: '$$11$$22$$33aaaaaaaaaaaaaaaaaaaaaaaaaa'
```
If you use `docker run` you will need to make sure to use single quotes:
```shell
docker run ... -e CF_API_KEY='$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa'
```
To avoid exposing the API key, it is highly recommended to use a `.env` file, which is [loaded automatically by docker compose](https://docs.docker.com/compose/environment-variables/set-environment-variables/#substitute-with-an-env-file). `$`'s in the value still need to escaped with a second `$` and the variable needs to be referenced from the compose file, such as:
```yaml
environment:
CF_API_KEY: ${CF_API_KEY}
```
To use the equivalent with `docker run` you need to specify the `.env` file explicitly:
```
docker run --env-file=.env itzg/minecraft-server
```
!!! note
Be sure to use the appropriate [image tag for the Java version compatible with the modpack](../versions/java.md).
Most modpacks require a good amount of memory, so it best to set `MEMORY` to at least "4G" since the default is only 1 GB.
## Usage
Use one of the following to specify the modpack to install:
Pass a page URL to the modpack or a specific file with `CF_PAGE_URL` such as the modpack page "https://www.curseforge.com/minecraft/modpacks/all-the-mods-8" or a specific file "https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390". For example:
```
-e TYPE=AUTO_CURSEFORGE -e CF_PAGE_URL=https://www.curseforge.com/minecraft/modpacks/all-the-mods-8
```
Instead of a URL, the modpack slug can be provided as `CF_SLUG`. The slug is the short identifier visible in the URL after "/modpacks/", such as
![cf-slug](../img/cf-slug.png)
For example:
```
-e TYPE=AUTO_CURSEFORGE -e CF_SLUG=all-the-mods-8
```
For mod, modpacks, and world files that are not allowed for automated download, the container path `/downloads` can be attached and matching files will be retrieved from there. The subdirectories `mods`, `modpacks`, and `worlds` will also be checked accordingly. To change the source location of downloaded files, set `CF_DOWNLOADS_REPO` to an existing container path. To disable this feature, set `CF_DOWNLOADS_REPO` to an empty string.
If the authors of the modpack have disallowed project distribution, then the desired **client** modpack zip will need to be manually downloaded and made available to the container. The path to that file must be passed to `CF_MODPACK_ZIP`. Similarly, the container path to a modpack manifest JSON can be passed to `CF_MODPACK_MANIFEST`. In either case, the modpack slug or page URL must still be provided.
The latest file will be located and used by default, but if a specific version is desired you can use one of the following options. With any of these options **do not select a server file** -- they lack the required manifest and defeat the ability to consistently automate startup.
- Use `CF_PAGE_URL`, but include the full URL to a specific file
- Set `CF_FILE_ID` to the numerical file ID
- Specify a substring to match the desired filename with `CF_FILENAME_MATCHER`
The following shows where to get the URL to the specific file and also shows where the file ID is located:
![cf-file-id](../img/cf-file-id.png)
The following examples all refer to version 1.0.7 of ATM8:
```
-e CF_PAGE_URL=https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390
```
```
-e CF_SLUG=all-the-mods-8 -e CF_FILE_ID=4248390
```
```
-e CF_SLUG=all-the-mods-8 -e CF_FILENAME_MATCHER=1.0.7
```
## Exlude client mods
Quite often there are mods that need to be excluded, such as ones that did not properly declare as a client mod via the file's game versions. Similarly, there are some mods that are incorrectly tagged as client only. The following describes two options to exclude/include mods:
Mods can be excluded by passing a comma or space delimited list of **project** slugs or IDs via `CF_EXCLUDE_MODS`. Similarly, there are some mods that are incorrectly tagged as client only. For those, pass the **project** slugs or IDs via `CF_FORCE_INCLUDE_MODS`. These lists will be combined with the content of the exclude/include file, if given.
A mod's project ID can be obtained from the right hand side of the project page:
![cf-project-id](../img/cf-project-id.png)
For more complex scenarios, global and per modpack exclusions can be declared in a container-accessible JSON file and referenced with `CF_EXCLUDE_INCLUDE_FILE`. By default, [the file bundled with the image](https://raw.githubusercontent.com/itzg/docker-minecraft-server/master/files/cf-exclude-include.json) will be used, but can be disabled by setting this to an empty string. The schema of this file [is documented here](https://github.com/itzg/mc-image-helper#excludeinclude-file-schema).
If needing to iterate on the options above, set `CF_FORCE_SYNCHRONIZE` to "true" to ensure the exclude/includes are re-evaluated.
!!! important
These options are provided to empower you to get your server up and running quickly. Please help out by reporting an issue with the respective mod project. Ideally mod developers should [use correct registrations for one-sided client mods](https://docs.minecraftforge.net/en/latest/concepts/sides/#writing-one-sided-mods). Understandably, those code changes may be non-trivial, so mod authors can also add "Client" to the game versions when publishing.
## Extra options
Some modpacks come with world/save data via a worlds file and/or the overrides provided with the modpack. Either approach can be selected to set the `LEVEL` to the resulting saves directory by setting `CF_SET_LEVEL_FROM` to either:
- `WORLD_FILE`
- `OVERRIDES`
Other configuration available:
- `CF_PARALLEL_DOWNLOADS` (default is 4): specify how many parallel mod downloads to perform
- `CF_OVERRIDES_SKIP_EXISTING` (default is false): if set, files in the overrides that already exist in the data directory are skipped. **NOTE** world data is always skipped, if present.

42
docs/types-and-platforms/mod-platforms/curseforge.md Normal file
View file

@ -0,0 +1,42 @@
# Manual CurseForge server packs
Enable this server mode by setting `MOD_PLATFORM` or `TYPE` to "CURSEFORGE" along with the following specific variables.
You need to specify a modpack to run, using the `CF_SERVER_MOD` environment
variable. A CurseForge server modpack is available together with its respective
client modpack at <https://www.curseforge.com/minecraft/modpacks> .
Now you can add a `-e CF_SERVER_MOD=name_of_modpack.zip` to your command-line.
docker run -d -v /path/on/host:/data -e TYPE=CURSEFORGE \
-e CF_SERVER_MOD=SkyFactory_4_Server_4.1.0.zip \
-p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
If you want to keep the pre-download modpacks separate from your data directory,
then you can attach another volume at a path of your choosing and reference that.
The following example uses `/modpacks` as the container path as the pre-download area:
docker run -d -v /path/on/host:/data -v /path/to/modpacks:/modpacks \
-e TYPE=CURSEFORGE \
-e CF_SERVER_MOD=/modpacks/SkyFactory_4_Server_4.1.0.zip \
-p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
### Modpack data directory
By default, CurseForge modpacks are expanded into the sub-directory `/data/FeedTheBeast` and executed from there. (The default location was chosen for legacy reasons, when Curse and FTB were maintained together.)
The directory can be changed by setting `CF_BASE_DIR`, such as `-e CF_BASE_DIR=/data`.
### Buggy start scripts
Some modpacks have buggy or overly complex start scripts. You can avoid using the bundled start script and use this image's standard server-starting logic by adding `-e USE_MODPACK_START_SCRIPT=false`.
### Fixing "unable to launch forgemodloader"
If your server's modpack fails to load with an error [like this](https://support.feed-the-beast.com/t/cant-start-crashlanding-server-unable-to-launch-forgemodloader/6028/2):
unable to launch forgemodloader
then you apply a workaround by adding this to the run invocation:
-e FTB_LEGACYJAVAFIXER=true

9
docs/mods-and-plugins/feed-the-beast.md → docs/types-and-platforms/mod-platforms/ftb.md
View file

@ -1,8 +1,15 @@
# Feed the Beast
!!! note
Requires one of the Ubuntu with Hotspot images listed in [the Java versions section](../versions/java.md).
[Feed the Beast application](https://www.feed-the-beast.com/) modpacks are supported by using `-e TYPE=FTBA` (**note** the "A" at the end of the type). This server type will automatically take care of downloading and installing the modpack and appropriate version of Forge, so the `VERSION` does not need to be specified.
[Feed the Beast application](https://www.feed-the-beast.com/) modpacks are supported by setting `MOD_PLATFORM` or `TYPE` to "FTBA"
!!! note
The "A" at the end of "FTBA" is important. The value "FTB" used to be an alias for "CURSEFORGE".
This mod platform type will automatically take care of downloading and installing the modpack and appropriate version of Forge, so the `VERSION` does not need to be specified.
### Environment Variables:
- `FTB_MODPACK_ID`: **required**, the numerical ID of the modpack to install. The ID can be located by [finding the modpack](https://www.feed-the-beast.com/modpack) and locating the ID in this part of the URL:

4
docs/mods-and-plugins/modrinth-modpacks.md → docs/types-and-platforms/mod-platforms/modrinth-modpacks.md
View file

@ -1,4 +1,6 @@
[Modrinth Modpacks](https://modrinth.com/modpacks) can automatically be installed along with the required mod loader (Forge or Fabric) by setting `TYPE` to "MODRINTH". Upgrading (and downgrading) takes care of cleaning up old files and upgrading (and downgrading) the mod loader.
# Modrinth Modpacks
[Modrinth Modpacks](https://modrinth.com/modpacks) can automatically be installed along with the required mod loader (Forge or Fabric) by setting `MOD_PLATFORM` or `TYPE` to "MODRINTH". Upgrading (and downgrading) takes care of cleaning up old files and upgrading (and downgrading) the mod loader.
The desired modpack project is specified with the `MODRINTH_PROJECT` environment variable and must be one of:

0
docs/server-types/bukkit-spigot.md → docs/types-and-platforms/server-types/bukkit-spigot.md
View file

0
docs/server-types/fabric.md → docs/types-and-platforms/server-types/fabric.md
View file

0
docs/server-types/forge.md → docs/types-and-platforms/server-types/forge.md
View file

0
docs/server-types/hybrids.md → docs/types-and-platforms/server-types/hybrids.md
View file

0
docs/server-types/others.md → docs/types-and-platforms/server-types/others.md
View file

0
docs/server-types/paper.md → docs/types-and-platforms/server-types/paper.md
View file

0
docs/server-types/quilt.md → docs/types-and-platforms/server-types/quilt.md
View file

102
scripts/start-configuration
View file

@ -105,35 +105,37 @@ function fixJavaPath() {
fi
}
function resolveVersion() {
VERSIONS_JSON=https://launchermeta.mojang.com/mc/game/version_manifest.json
case "X$VERSION" in
X|XLATEST|Xlatest)
if ! VANILLA_VERSION=$(get --json-path '$.latest.release' "$VERSIONS_JSON"); then
log "ERROR: version lookup failed: $VANILLA_VERSION"
exit 1
fi
;;
XSNAPSHOT|Xsnapshot)
if ! VANILLA_VERSION=$(get --json-path '$.latest.snapshot' "$VERSIONS_JSON"); then
log "ERROR: version lookup failed: $VANILLA_VERSION"
exit 1
fi
;;
*)
VANILLA_VERSION=$VERSION
;;
esac
export VANILLA_VERSION
MAJOR_VANILLA_VERSION=$(get_major_version "$VANILLA_VERSION")
export MAJOR_VANILLA_VERSION
log "Resolved version given ${VERSION} into ${VANILLA_VERSION} and major version ${MAJOR_VANILLA_VERSION}"
}
if ! fixJavaPath; then
log "ERROR: could not locate path that contains java"
exit 1
fi
export VERSIONS_JSON=https://launchermeta.mojang.com/mc/game/version_manifest.json
case "X$VERSION" in
X|XLATEST|Xlatest)
if ! VANILLA_VERSION=$(get --json-path '$.latest.release' "$VERSIONS_JSON"); then
log "ERROR: version lookup failed: $VANILLA_VERSION"
exit 1
fi
;;
XSNAPSHOT|Xsnapshot)
if ! VANILLA_VERSION=$(get --json-path '$.latest.snapshot' "$VERSIONS_JSON"); then
log "ERROR: version lookup failed: $VANILLA_VERSION"
exit 1
fi
;;
*)
VANILLA_VERSION=$VERSION
;;
esac
export VANILLA_VERSION
MAJOR_VANILLA_VERSION=$(get_major_version "$VANILLA_VERSION")
export MAJOR_VANILLA_VERSION
log "Resolved version given ${VERSION} into ${VANILLA_VERSION} and major version ${MAJOR_VANILLA_VERSION}"
cd /data || exit 1
export ORIGINAL_TYPE=${TYPE^^}
@ -158,14 +160,35 @@ then
"${SCRIPTS:-/}start-rconcmds"
fi
if versionLessThan 1.7; then
echo "
MC_HEALTH_EXTRA_ARGS=(
--use-server-list-ping
)
" > /data/.mc-health.env
: ${MOD_PLATFORM:=}
case "${TYPE^^}" in
AUTO_CURSEFORGE|MODRINTH|CURSEFORGE|FTB|FTBA)
MOD_PLATFORM="$TYPE"
;;
esac
if [[ $MOD_PLATFORM ]]; then
case "${MOD_PLATFORM^^}" in
FTB|CURSEFORGE)
exec "${SCRIPTS:-/}start-deployCF" "$@"
;;
FTBA)
exec "${SCRIPTS:-/}start-deployFTBA" "$@"
;;
AUTO_CURSEFORGE)
exec "${SCRIPTS:-/}start-deployAutoCF" "$@"
;;
MODRINTH)
exec "${SCRIPTS:-/}start-deployModrinth" "$@"
;;
esac
fi
resolveVersion
log "Resolving type given ${TYPE}"
case "${TYPE^^}" in
*BUKKIT|SPIGOT)
@ -193,25 +216,6 @@ case "${TYPE^^}" in
exec "${SCRIPTS:-/}start-deployQuilt" "$@"
;;
FTBA)
evaluateJavaCompatibilityForForge
exec "${SCRIPTS:-/}start-deployFTBA" "$@"
;;
FTB|CURSEFORGE)
evaluateJavaCompatibilityForForge
exec "${SCRIPTS:-/}start-deployCF" "$@"
;;
AUTO_CURSEFORGE)
evaluateJavaCompatibilityForForge
exec "${SCRIPTS:-/}start-deployAutoCF" "$@"
;;
MODRINTH)
exec "${SCRIPTS:-/}start-deployModrinth" "$@"
;;
VANILLA)
exec "${SCRIPTS:-/}start-deployVanilla" "$@"
;;

8
scripts/start-finalExec
View file

@ -220,6 +220,14 @@ function copyFilesForCurseForge() {
cp -f /data/eula.txt "${FTB_DIR}/"
}
if versionLessThan 1.7; then
echo "
MC_HEALTH_EXTRA_ARGS=(
--use-server-list-ping
)
" > /data/.mc-health.env
fi
mcServerRunnerArgs=(
--stop-duration "${STOP_DURATION:-60}s"
--named-pipe "${CONSOLE_IN_NAMED_PIPE:-/tmp/minecraft-console-in}"