diff --git a/docs/types-and-platforms/mod-platforms/auto-curseforge.md b/docs/types-and-platforms/mod-platforms/auto-curseforge.md index f61a5ed9077..35f80eb71c3 100644 --- a/docs/types-and-platforms/mod-platforms/auto-curseforge.md +++ b/docs/types-and-platforms/mod-platforms/auto-curseforge.md @@ -7,33 +7,33 @@ To manage a CurseForge modpack automatically with upgrade support, pinned or lat !!! 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 `$`. Refer to [this compose file reference section](https://docs.docker.com/compose/compose-file/compose-file-v3/#variable-substitution) for more information. - + Example if your key is `$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa`: ```yaml title="compose.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). You **do not** need to escape `$`'s with a second `$` in the `.env` file **as long as the key is wrapped in single quotes**. - + + 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). You **do not** need to escape `$`'s with a second `$` in the `.env` file **as long as the key is wrapped in single quotes**. + ```title=".env" CF_API_KEY='$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa' ``` - + The variable should to be referenced from the compose file, such as: - + ```yaml title="compose.yaml" environment: CF_API_KEY: ${CF_API_KEY} ``` - + The .env file should be placed in the same directory as your compose file like so: ``` @@ -42,12 +42,12 @@ To manage a CurseForge modpack automatically with upgrade support, pinned or lat ├── compose.yaml ├── data/ ``` - + To use the equivalent with `docker run` you need to specify the `.env` file explicitly: ```shell docker run --env-file=.env itzg/minecraft-server ``` - + Alternately you can use [docker secrets](https://docs.docker.com/compose/how-tos/use-secrets/) with a `CF_API_KEY_FILE` environment variable: ```yaml title="compose.yaml" service: @@ -55,7 +55,7 @@ To manage a CurseForge modpack automatically with upgrade support, pinned or lat CF_API_KEY_FILE: /run/secrets/cf_api_key secrets: - cf_api_key - + secrets: cf_api_key: file: cf_api_key.secret @@ -64,14 +64,14 @@ To manage a CurseForge modpack automatically with upgrade support, pinned or lat !!! 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". +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". !!! example "Using CF_PAGE_URL" @@ -83,7 +83,7 @@ Pass a page URL to the modpack or a specific file with `CF_PAGE_URL` such as the CF_API_KEY: ${CF_API_KEY} CF_PAGE_URL: https://www.curseforge.com/minecraft/modpacks/all-the-mods-8 ``` - + ```title="Using docker run" docker run -e CF_API_KEY=${CF_API_KEY} -e TYPE=AUTO_CURSEFORGE -e CF_PAGE_URL=https://www.curseforge.com/minecraft/modpacks/all-the-mods-8 ``` @@ -102,7 +102,7 @@ Instead of a URL, the modpack slug can be provided as `CF_SLUG`. The slug is the CF_API_KEY: ${CF_API_KEY} CF_SLUG: all-the-mods-8 ``` - + ```title="Using docker run" docker run -e CF_API_KEY=${CF_API_KEY} -e TYPE=AUTO_CURSEFORGE -e CF_SLUG=all-the-mods-8 ``` @@ -137,6 +137,30 @@ The following examples all refer to version 1.0.7 of ATM8: Pinning modpack version also pins the mod loader (to the version specified by the modpack). Mod loader version cannot be pinned independently of the modpack. +### Custom modloader versions + +By default, AUTO_CURSEFORGE will use the exact modloader version declared by the modpack. However, you can override the modloader version by setting the following environment variable: + +- `CF_MOD_LOADER_VERSION`: Override the mod loader version (e.g., `0.16.14`) + +!!! example "Override mod loader version" + + ```yaml + environment: + MODPACK_PLATFORM: AUTO_CURSEFORGE + CF_API_KEY: ${CF_API_KEY} + CF_SLUG: all-the-mods-8 + CF_MOD_LOADER_VERSION: "0.16.14" + ``` + + ```title="Using docker run" + docker run -e CF_MOD_LOADER_VERSION=0.16.14 -e CF_SLUG=my-fabric-pack ... + ``` + +!!! warning "Compatibility" + + Using a custom modloader version that differs significantly from what the modpack was designed for may cause compatibility issues. Use this feature carefully and test thoroughly. + ## Manual Downloads 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. @@ -148,12 +172,12 @@ For mod, modpacks, and world files that are not allowed for automated download, !!! example Assuming Docker compose is being used: - + 1. Create a directory next to the `compose.yaml` file. The name doesn't matter, but "downloads" is the common convention 2. From the "Mods Need Download" output, visit the download page of each, click on the file download and save that file into the directory created in the previous step 3. Add a host directory mount to the volumes section where the container path **must be** `/downloads`. The snippet below shows how that will look 4. Re-run `docker compose up -d` to apply the changes - + ```yaml volumes: ./downloads:/downloads @@ -182,7 +206,7 @@ If you wish to use an unpublished modpack zip, set the container path to the fil ``` where an exported manifest file should look like: - + ```json { "minecraft": { @@ -222,7 +246,7 @@ Mods can be excluded by passing a comma or space delimited list of **project** s !!! note `CF_FORCE_INCLUDE_MODS` will not download additional mods. - + For additional mods, refer to [the `CURSEFORGE_FILES` variable](../../mods-and-plugins/curseforge-files.md). A mod's project ID can be obtained from the right hand side of the project page: @@ -238,7 +262,7 @@ If needing to iterate on the options above, set `CF_FORCE_SYNCHRONIZE` to "true" !!! tip "Embedded comments" Comments can be embedded in the list using the `#` character. - + ```yaml CF_EXCLUDE_MODS: | # Exclude client-side mods not published correctly @@ -248,7 +272,7 @@ If needing to iterate on the options above, set `CF_FORCE_SYNCHRONIZE` to "true" ## Excluding Overrides Files -Modpack zip files typically include an `overrides` subdirectory that may contain config files, world data, and extra mod files. All of those files will be extracted into the `/data` path of the container. If any of those files, such as incompatible mods, need to be excluded from extraction, then the `CF_OVERRIDES_EXCLUSIONS` variable can be set with a comma or newline delimited list of ant-style paths ([see below](#ant-style-paths)) to exclude, relative to the overrides (or `/data`) directory. +Modpack zip files typically include an `overrides` subdirectory that may contain config files, world data, and extra mod files. All of those files will be extracted into the `/data` path of the container. If any of those files, such as incompatible mods, need to be excluded from extraction, then the `CF_OVERRIDES_EXCLUSIONS` variable can be set with a comma or newline delimited list of ant-style paths ([see below](#ant-style-paths)) to exclude, relative to the overrides (or `/data`) directory. ### Ant-style paths @@ -261,15 +285,15 @@ Ant-style paths can include the following globbing/wildcard symbols: | `?` | Matches one character | !!! example - + The following compose `environment` entries show how to exclude Iris and Sodium mods from the overrides - + ```yaml CF_OVERRIDES_EXCLUSIONS: mods/iris*.jar,mods/sodium*.jar ``` - + or using newline delimiter, which improves maintainability - + ```yaml CF_OVERRIDES_EXCLUSIONS: | mods/iris*.jar diff --git a/docs/variables.md b/docs/variables.md index 1e2e67095b7..53889a84acf 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -747,7 +747,7 @@ alternatively, you can mount: /etc/localtime:/etc/localtime:ro A path to a file inside of container that contains YOUR CurseForge (Eternal) API Key. ✅ - + CF_PAGE_URL Pass a page URL to the modpack or a specific file @@ -818,6 +818,12 @@ alternatively, you can mount: /etc/localtime:/etc/localtime:ro false ⬜️ + + CF_MOD_LOADER_VERSION + Override the mod loader version declared by the modpack + + ⬜️ + diff --git a/examples/auto-curseforge/fabric-custom-loader/docker-compose.yml b/examples/auto-curseforge/fabric-custom-loader/docker-compose.yml new file mode 100644 index 00000000000..a0a5a0dc191 --- /dev/null +++ b/examples/auto-curseforge/fabric-custom-loader/docker-compose.yml @@ -0,0 +1,22 @@ +services: + mc: + image: itzg/minecraft-server + environment: + EULA: "TRUE" + MODPACK_PLATFORM: AUTO_CURSEFORGE + # Allocate API key from https://console.curseforge.com/ + CF_API_KEY: ${CF_API_KEY} + # Example of overriding modloader version for a Fabric modpack + # Refer to https://docker-minecraft-server.readthedocs.io/en/latest/types-and-platforms/mod-platforms/auto-curseforge/#api-key + CF_SLUG: "cobblemon-fabric" + # Override the mod loader version from the modpack + CF_MOD_LOADER_VERSION: "0.16.14" + MEMORY: "4G" + ports: + - "25565:25565" + volumes: + - ./data:/data + stdin_open: true + tty: true + +# See https://docker-minecraft-server.readthedocs.io/en/latest/types-and-platforms/mod-platforms/auto-curseforge/#custom-modloader-versions diff --git a/scripts/start-deployAutoCF b/scripts/start-deployAutoCF index 57f3508803e..4154a656ab3 100644 --- a/scripts/start-deployAutoCF +++ b/scripts/start-deployAutoCF @@ -22,6 +22,7 @@ set -eu : "${CF_MODPACK_MANIFEST:=}" : "${CF_API_CACHE_DEFAULT_TTL:=}" # as ISO-8601 duration, such as P2D or PT12H : "${CF_API_KEY_FILE:=}" # Path to file containing CurseForge API key +: "${CF_MOD_LOADER_VERSION:=}" # Override mod loader version resultsFile=/data/.install-curseforge.env @@ -66,6 +67,7 @@ setArg --exclude-mods CF_EXCLUDE_MODS setArg --force-include-mods CF_FORCE_INCLUDE_MODS setArg --exclude-include-file CF_EXCLUDE_INCLUDE_FILE setArg --downloads-repo CF_DOWNLOADS_REPO +setArg --mod-loader-version CF_MOD_LOADER_VERSION if ! mc-image-helper install-curseforge "${args[@]}"; then logError "Failed to auto-install CurseForge modpack"