Add HANGAR_PROJECTS to download plugins from Hangar (#4392)

This commit is contained in:
Vitalii Kotenko authored and GitHub committed 2026-11-18 19:52:29 -06:00
1 parent 0c04150581
commit 2b70dfce94
6 files changed
+82

No files matched your search

+39
View File
@@ -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 <https://hangar.papermc.io/kennytv/Maintenance>
- **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
```
@@ -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 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 ## Alternatives
### Pufferfish ### 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 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 !!! note
The Folia type inherits from the Paper type. Paper's variables will override the Folia ones. The Folia type inherits from the Paper type. Paper's variables will override the Folia ones.
+26
View File
@@ -332,6 +332,30 @@ function handleModrinthProjects() {
fi 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() { function handleCurseForgeFiles() {
args=( args=(
--use-http2="$CF_USE_HTTP2" --use-http2="$CF_USE_HTTP2"
@@ -387,6 +411,8 @@ handleGenericPacks
handleModrinthProjects handleModrinthProjects
handleHangarProjects
if usesMods || usesPlugins; then if usesMods || usesPlugins; then
handleCurseForgeFiles handleCurseForgeFiles
fi fi
@@ -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
+1
View File
@@ -0,0 +1 @@
mc-image-helper has-feature hangar || exit 1
+1
View File
@@ -0,0 +1 @@
mc-image-helper assert fileExists "plugins/ViaVersion-*.jar"