Skip to main content

​
Modpack Platforms

The easiest way to work with mods and plugins, especially large numbers of them, is to utilize modpacks with one of the supported modpack platforms:

​
Download Automation

This image provides several automated download options for mods and plugins:
  • Modrinth - Auto-download from Modrinth’s open source platform
  • CurseForge - Auto-download from CurseForge
  • Spiget - Auto-download SpigotMC plugins
  • Packwiz - Use packwiz modpack definitions
  • Generic Packs - Install from zip/tgz archives

​
Mods vs Plugins

Understanding the difference between mods and plugins is important: Mods are used by server types that run client-side to modify rendering, add new blocks, and add behaviors: Mods typically need to be installed on both client and server, though some are server-only. Plugins are used by server types that only run on servers to add behaviors and commands: Plugins only need to be installed on the server and are never needed on the client. Hybrid Servers like Magma can use both mods and plugins simultaneously.

​
Volume Mount Points

You can attach volumes to supply content that will be copied into the server:

​
/plugins

Content in this directory is synchronized into /data/plugins for plugin-based server types. 
volumes:
  - ./plugins:/plugins:ro
For special cases:
  • Change source with COPY_PLUGINS_SRC
  • Change destination with COPY_PLUGINS_DEST
  • For hybrid mod loaders like Cardboard, set USES_PLUGINS=true
Example: Using Cardboard plugins with Fabric 
environment:
  EULA: "TRUE"
  TYPE: "FABRIC"
  MODRINTH_PROJECTS: |
    fabric-api
    cardboard
  USES_PLUGINS: true

​
/mods

Content in this directory is synchronized into /data/mods for mod-based server types. 
volumes:
  - ./mods:/mods:ro
For special cases:
  • Change source with COPY_MODS_SRC
  • Change destination with COPY_MODS_DEST

​
/config

Contents are synchronized into /data/config by default. 
volumes:
  - ./config:/config:ro
environment:
  # Optional: copy directly to /data instead
  COPY_CONFIG_DEST: /data
Configuration options:
  • Change source with COPY_CONFIG_SRC
  • Change destination with COPY_CONFIG_DEST
  • Set SYNC_SKIP_NEWER_IN_DESTINATION=false to prioritize /config files over newer destination files
By default, environment variable processing is performed on synchronized files matching suffixes in REPLACE_ENV_SUFFIXES (default: “yml,yaml,txt,cfg,conf,properties,hjson,json,tml,toml”). Disable with REPLACE_ENV_DURING_SYNC=false.

​
Multiple Source Directories

COPY_PLUGINS_SRC, COPY_MODS_SRC, and COPY_CONFIG_SRC can each be set to a comma or newline delimited list of container directories. 
environment:
  TYPE: PAPER
  # Multiple plugin sources
  COPY_PLUGINS_SRC: /plugins-common,/plugins-local
volumes:
  - mc-data:/data
  # Shared directory used by several projects
  - ../plugins-common:/plugins-common:ro
  # Plugins unique to this project
  - ./plugins:/plugins-local:ro

​
Removing Old Mods/Plugins

To remove old mods/plugins before copying new content, set REMOVE_OLD_MODS=TRUE. 
-e REMOVE_OLD_MODS=TRUE
Fine-tune the removal process:
VariableDescriptionDefault
REMOVE_OLD_MODS_INCLUDEComma-separated glob patterns to include*.jar
REMOVE_OLD_MODS_EXCLUDEComma-separated glob patterns to excludeNone
REMOVE_OLD_MODS_DEPTHMaximum directory depth16
Example: Remove only jar files in top-level directory 
-e REMOVE_OLD_MODS=TRUE \
-e REMOVE_OLD_MODS_INCLUDE="*.jar" \
-e REMOVE_OLD_MODS_DEPTH=1
Excluding a directory will exclude it and all of its contents.

​
Individual Mods/Plugins List

Download or copy individual mods/plugins using MODS or PLUGINS environment variables. Each can be a comma or newline delimited list of:
  • URL of a jar file
  • Container path to a jar file
  • Container path to a directory containing jar files
-e MODS=https://www.example.com/mods/mod1.jar,/plugins/common,/plugins/special/mod2.jar
Auto-removal: Entries removed from the MODS or PLUGINS list will be automatically removed from the mods or plugins directory. An empty list removes all mods/plugins.Disable processing: Comment out the MODS or PLUGINS environment variable to temporarily disable processing.

​
URL Listing Files

As an alternative to MODS/PLUGINS, use MODS_FILE or PLUGINS_FILE with the container path or URL of a text file listing mod/plugin URLs. 
-e MODS_FILE=/extras/mods.txt
Example listing file: 
https://edge.forgecdn.net/files/2965/233/Bookshelf-1.15.2-5.6.40.jar
https://edge.forgecdn.net/files/2926/27/ProgressiveBosses-2.1.5-mc1.15.2.jar
# This and next line are ignored
#https://edge.forgecdn.net/files/3248/905/goblintraders-1.3.1-1.15.2.jar
https://edge.forgecdn.net/files/3272/32/jei-1.15.2-6.0.3.16.jar
https://edge.forgecdn.net/files/2871/647/ToastControl-1.15.2-3.0.1.jar
Blank lines and lines starting with # are ignored.

​
Applying Extra Configuration Files

Download or copy additional configuration files before server startup using APPLY_EXTRA_FILES. The format uses < to separate destination path and source URL/path. Destination paths are relative to /data. 
-e APPLY_EXTRA_FILES="destination<source_url,destination2<source_url2"
APPLY_EXTRA_FILES is processed before patch processing, so it can provide baseline files to be patched at runtime.

​
Zip File Modpack

Specify a URL or container path of a “mod pack” to download and install into mods for Forge/Fabric or plugins for Bukkit/Spigot. 
-e MODPACK=http://www.example.com/mods/modpack.zip
The referenced URL/file must be a zip file with one or more jar files at the top level. Ensure jars are compatible with your server TYPE.

Build docs developers (and LLMs) love

Get started for freeTalk to us