Auto-download from Modrinth

Modrinth is an open source modding platform with a clean, easy to use website for finding Fabric, Forge, etc mods and Paper, etc plugins, and datapacks. 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.

Usage

To use this feature, set the environment variable MODRINTH_PROJECTS to a comma or newline separated list of projects.

Each project entry can be any of the following combinations where a colon (:) is used to separate the different parts:

         Project
         Project : Version
         Project : Release Type
Prefix : Project
Prefix : Project : Version
Prefix : Project : Release Type
@ Listing File

Where:

Project is the project slug or ID, see below
Version is the version ID (such as "Oa9ZDzZq") or number (such as "2.21.2"). When omitted, the latest release version will be selected. Using version ID will override Minecraft and loader compatibility checks.
Release Type is release, beta, or alpha indicating the latest version to select.
Prefix is datapack, fabric, forge, or paper
- The datapack prefix is optional when running a vanilla server
- The fabric, forge, and paper prefixes allow for installing mods/plugins that differ from server's TYPE. Using Sinytra Connector is an example of this, where Fabric mods can be loaded into a NeoForge server.
Listing file is a container path to a file containing a list of projects

!!! tip "Project ID"

The project ID can be copied to the clipboard from the project page menu:

![Modrinth copy project ID](../img/modrinth-copy-project-id.png)

!!! tip "Project Slug"

The project slug is the part of the URL that follows `/mod/`, `/plugin/`, or `/datapack/`. For example, this one is "essentialsx".

![](../img/modrinth-plugin-project-slug.png)

!!! tip "Version number and ID"

The version number and ID are located in the metadata panel on a version specific page, such as <https://modrinth.com/plugin/essentialsx/version/2.21.2>

![Version ID](../img/modrinth-version-id.drawio.png)

Examples

Description	Example projects entry
Select latest version	`fabric-api`
Select specific version	`fabric-api:bQZpGIz0` `fabric-api:0.119.2+1.21.4`
Select latest beta version	`fabric-api:beta`
Latest version using project ID	`P7dR8mSH`
Latest version of datapack	`datapack:terralith`
Specific version of datapack	`datapack:terralith:2.5.5`
Mod loader override	`fabric:fabric-api` `fabric:fabric-api:bQZpGIz0`
Projects Listing File	`@/path/to/modrinth-mods.txt`

Notes

!!! info "More about listing files"

Each line in the listing file is processed as one of the references above; however, blank lines and comments that start with `#` are ignored.

Make sure to place the listing file in a mounted directory/volume or declare an appropriate mount for it.

For example, `MODRINTH_PROJECTS` can be set to "@/extras/modrinth-mods.txt", assuming "/extras" has been added to `volumes` section, where the container file `/extras/modrinth-mods.txt` contains

```text
# This comment is ignored
fabric-api

# This and previous blank line are ignore
cloth-config
datapack:terralith
```

!!! note "Auto-removal"

Entries that are removed from the `MODRINTH_PROJECTS` list will be automatically removed from the `mods` or `plugins` directory. This is useful for removing mods/plugins that are no longer needed. An empty `MODRINTH_PROJECTS` list will remove all mods/plugins.

!!! note "Disable processing"

To temporarily disable processing of the `MODRINTH_PROJECTS` list, then comment out the `MODRINTH_PROJECTS` environment variable.

Optional projects

Projects that are not critical for the server to function can be marked as optional by appending a ? to the project slug or ID. When a compatible version cannot be found for an optional project, the server logs a warning and continues startup instead of failing.

This is particularly useful for server-side mods that tend to lag behind on Minecraft updates, such as map renderers (Pl3xmap, BlueMap), performance mods (Lithium, C2ME), or admin tools (Spark, LuckPerms).

      MODRINTH_PROJECTS: |
        fabric-api
        lithium
        pl3xmap?
        bluemap?:beta

The ? marker can be combined with all existing format options:

Format	Example
Slug only	`pl3xmap?`
With version	`pl3xmap?:Oa9ZDzZq`
With release type	`pl3xmap?:beta`
With loader prefix	`fabric:pl3xmap?`
Full combination	`fabric:pl3xmap?:beta`
In listing files	`pl3xmap?` (one per line)

When combined with VERSION_FROM_MODRINTH_PROJECTS, optional projects are excluded from the version calculation. This means an optional mod that hasn't been updated yet will never block a Minecraft version upgrade.

!!! example "Automatic upgrades without optional-mod breakage"

```yaml
    MODRINTH_PROJECTS: |
      fabric-api
      lithium
      pl3xmap?
    VERSION_FROM_MODRINTH_PROJECTS: true
```

If a new Minecraft version is released and `fabric-api` + `lithium` support it but `pl3xmap` does not:

1. The resolved `VERSION` is set to the new version (pl3xmap is not considered)
2. `fabric-api` and `lithium` are installed normally
3. `pl3xmap` is skipped with a warning in the logs
4. On a future restart, once pl3xmap publishes a compatible build, it is picked up automatically

!!! note

Optional projects marked with `?` in listing files (`@/path/to/file.txt`) are supported ; the `?` is parsed from each line the same way as inline entries.

Version from Projects

When the environment variable VERSION_FROM_MODRINTH_PROJECTS is set to "true" the Minecraft VERSION will be automatically determined by looking at the most recent version of Minecraft that is supported by all the projects provided in MODRINTH_PROJECTS.

!!! example

Given the environment variables

```yaml
    MODRINTH_PROJECTS: |
      viaversion
      viabackwards
      griefprevention
      discordsrv
    VERSION_FROM_MODRINTH_PROJECTS: true
```

Let's say all are supported on Minecraft up to 1.21.8 except griefprevention, which is only supported up to 1.21.7. In that case, `VERSION` will be automatically set to 1.21.7.

Extra options

MODRINTH_DOWNLOAD_DEPENDENCIES: Can be set to none (the default), required, or optional to download required and/or optional dependencies.
MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE: The version type is used to determine the newest version to use from each project. The allowed values are release (default), beta, alpha. Setting to beta will pick up both release and beta versions. Setting to alpha will pick up release, beta, and alpha versions.
MODRINTH_LOADER: When using a custom server, set this to specify which loader type will be requested during lookups

7.9 KiB Raw Blame History