diff --git a/docs/mods-and-plugins/hangar.md b/docs/mods-and-plugins/hangar.md new file mode 100644 index 00000000..4533d2e1 --- /dev/null +++ b/docs/mods-and-plugins/hangar.md @@ -0,0 +1,39 @@ +# Auto-download from Hangar + +[Hangar](https://hangar.papermc.io/) is PaperMC's plugin repository for [Paper](../types-and-platforms/server-types/paper.md) and its derivatives. At startup, the container will automatically locate and download the newest version of each plugin that supports the `VERSION` in use. Older file versions downloaded previously will automatically be cleaned up. + +## Usage + +To use this feature, set the environment variable `HANGAR_PROJECTS` to a comma or newline separated list of projects. This is supported when `TYPE` is `PAPER`, `FOLIA`, `PURPUR`, `PUFFERFISH`, or `LEAF`. + +Each project entry can be any of the following combinations where a colon (`:`) is used to separate the different parts: + +``` +Project +Project : Version +@ Listing File +``` + +Where: + +- **Project** is the project slug or ID. The slug is the last part of the project page URL, such as "Maintenance" from +- **Version** is the version name, such as "5.1.1". When omitted, the newest version from the channel given by `HANGAR_CHANNEL` that supports the Minecraft `VERSION` is selected. Selecting a specific version skips the Minecraft version check. +- **Listing file** is a container path to a file containing a list of projects + +Append a `?` to a project, such as `Maintenance?`, to mark it as optional. An optional project that is not available is skipped with a warning instead of failing the startup. + +By default, the newest version from the "Release" channel will be selected. You can instead choose another channel by setting `HANGAR_CHANNEL`, such as "Snapshot". The channels of a project are listed on its versions page. + +!!! note "External downloads" + + Some projects, such as [Floodgate](https://hangar.papermc.io/GeyserMC/Floodgate), link to a file hosted outside of Hangar. That file is downloaded from the external location and is downloaded again when the external file has been modified. + +### Example + +```yaml + environment: + TYPE: PAPER + HANGAR_PROJECTS: | + ViaVersion + Maintenance:5.1.1 +``` diff --git a/docs/types-and-platforms/server-types/paper.md b/docs/types-and-platforms/server-types/paper.md index 55e94a6c..c4a95b1d 100644 --- a/docs/types-and-platforms/server-types/paper.md +++ b/docs/types-and-platforms/server-types/paper.md @@ -52,6 +52,8 @@ If you have attached a host directory to the `/data` volume, then you can instal [You can also auto-download plugins using `SPIGET_RESOURCES`.](../../mods-and-plugins/spiget.md) +[You can also auto-download plugins from Hangar using `HANGAR_PROJECTS`.](../../mods-and-plugins/hangar.md) + ## Alternatives ### Pufferfish @@ -126,6 +128,8 @@ If you have attached a host directory to the `/data` volume, then you can instal [You can also auto-download plugins using `SPIGET_RESOURCES`.](../../mods-and-plugins/spiget.md) +[You can also auto-download plugins from Hangar using `HANGAR_PROJECTS`.](../../mods-and-plugins/hangar.md) + !!! note The Folia type inherits from the Paper type. Paper's variables will override the Folia ones. diff --git a/scripts/start-setupModpack b/scripts/start-setupModpack index 2c86936e..7483571e 100755 --- a/scripts/start-setupModpack +++ b/scripts/start-setupModpack @@ -332,6 +332,30 @@ function handleModrinthProjects() { fi } +function handleHangarProjects() { + : "${HANGAR_CHANNEL:=Release}" + + if [[ -v HANGAR_PROJECTS ]]; then + # Older helper builds, including Java 8, don't have the hangar command + if ! mc-image-helper has-feature hangar; then + logError "HANGAR_PROJECTS is not supported by this image variant" + exit 1 + fi + + if ! isType PAPER FOLIA PURPUR PUFFERFISH LEAF; then + logError "HANGAR_PROJECTS requires a Paper based TYPE, such as PAPER, FOLIA, or PURPUR" + exit 1 + fi + + mc-image-helper hangar \ + --output-directory=/data \ + --projects="${HANGAR_PROJECTS}" \ + --game-version="${VERSION}" \ + --platform=PAPER \ + --channel="$HANGAR_CHANNEL" + fi +} + function handleCurseForgeFiles() { args=( --use-http2="$CF_USE_HTTP2" @@ -387,6 +411,8 @@ handleGenericPacks handleModrinthProjects +handleHangarProjects + if usesMods || usesPlugins; then handleCurseForgeFiles fi diff --git a/tests/setuponlytests/hangar/docker-compose.yml b/tests/setuponlytests/hangar/docker-compose.yml new file mode 100644 index 00000000..0a140229 --- /dev/null +++ b/tests/setuponlytests/hangar/docker-compose.yml @@ -0,0 +1,11 @@ +services: + mc: + image: ${IMAGE_TO_TEST:-itzg/minecraft-server} + environment: + EULA: "true" + SETUP_ONLY: "true" + TYPE: PAPER + VERSION: 1.21.4 + HANGAR_PROJECTS: ViaVersion + volumes: + - ./data:/data diff --git a/tests/setuponlytests/hangar/require_inside.sh b/tests/setuponlytests/hangar/require_inside.sh new file mode 100755 index 00000000..a6d7c57d --- /dev/null +++ b/tests/setuponlytests/hangar/require_inside.sh @@ -0,0 +1 @@ +mc-image-helper has-feature hangar || exit 1 diff --git a/tests/setuponlytests/hangar/verify.sh b/tests/setuponlytests/hangar/verify.sh new file mode 100644 index 00000000..96903c66 --- /dev/null +++ b/tests/setuponlytests/hangar/verify.sh @@ -0,0 +1 @@ +mc-image-helper assert fileExists "plugins/ViaVersion-*.jar"