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.
CurseForge API key usage
A CurseForge API key is required to use this feature. Go to their developer console, generate an API key, and set the environment variable
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 for more information.
Example if your key is
docker runyou will need to make sure to use single quotes:
To avoid exposing the API key, it is highly recommended to use a
.env file, which is loaded automatically by docker compose.
$'s in the value still need to escaped with a second
$ and the variable needs to be referenced from the compose file, such as:
To use the equivalent with
docker run you need to specify the
.env file explicitly:
Be sure to use the appropriate image tag for the Java version compatible with the modpack.
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.
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:
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
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.
CF_PAGE_URL, but include the full URL to a specific file
CF_FILE_IDto the numerical file ID
- Specify a substring to match the desired filename with
The following shows where to get the URL to the specific file and also shows where the file ID is located:
The following examples all refer to version 1.0.7 of ATM8:
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
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.
Mods need download report
A file called
MODS_NEED_DOWNLOAD.txt will be created in the
/data directory that lists the mods that need to be manually downloaded and where to get them.
Assuming Docker compose is being used:
- Create a directory next to the
docker-compose.ymlfile. The name doesn't matter, but "downloads" is the common convention
- 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
- Add a host directory mount to the volumes section where the container path must be
/downloads. The snippet below shows how that will look
docker composwe up -dto apply the changes
If you wish to use a unpublished modpack zip, set the container path to the file in
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.
Exclude 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:
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 will be used, but can be disabled by setting this to an empty string. The schema of this file is documented here.
If needing to iterate on the options above, set
CF_FORCE_SYNCHRONIZE to "true" to ensure the exclude/includes are re-evaluated.
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. Understandably, those code changes may be non-trivial, so mod authors can also add "Client" to the game versions when publishing.
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) to exclude, relative to the overrides (or
Ant-style paths can include the following globbing/wildcard symbols:
||Matches zero, one, or many characters except a slash|
||Matches zero, one, or many characters including slashes|
||Matches one character|
The following compose
environment entries show how to exclude Iris and Sodium mods from the overrides
or using newline delimiter, which improves maintainability
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:
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.