amorfo77/docker-minecraft-server
1
0
Fork 0
mirror of https://github.com/itzg/docker-minecraft-server.git synced 2026-02-17 07:03:57 +00:00
Code Issues Projects Releases Wiki Activity

Support Purpur and Pufferfish config repos & optimize server.properties handling (#3914)

Browse Source
This commit is contained in:
Tomás Alegre Sepúlveda
2026-02-09 18:03:15 -03:00
committed by GitHub
parent fbbe29507e
commit 6e05807865
7 changed files with 180 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/types-and-platforms/server-types/paper.md
View File

@@ -1,6 +1,6 @@
A [PaperMC server](https://papermc.io/) can be automatically downloaded, upgraded, and run by setting the environment variable TYPE to "PAPER".
By default, the container will find and download the latest build for the `VERSION` chosen. If `VERSION` is not specified, then the latest Minecraft version released by PaperMC is selected. Along with a specific `VERSION`, a specific Paper build can be selected by setting the environment variable `PAPER_BUILD`.
By default, the container will find and download the latest build for the `VERSION` chosen. If `VERSION` is not specified, then the latest Minecraft version released by PaperMC is selected. Along with a specific `VERSION`, a specific Paper build can be selected by setting the environment variable `PAPER_BUILD`.
To allow for the selection of experimental builds, set `PAPER_CHANNEL` to "experimental", otherwise only release/default channel builds are selected.
@@ -65,6 +65,7 @@ A [Pufferfish](https://github.com/pufferfish-gg/Pufferfish) server, which is "a
The `VERSION` variable is used to select branch latest, 1.18, or 1.17. Use PUFFERFISH_BUILD to really select the SERVER VERSION number.
Extra variables:
- `PUFFERFISH_BUILD=lastSuccessfulBuild` : set a specific Pufferfish build to use. Example: selecting build 47 => 1.18.1, or build 50 => 1.18.2 etc
- `FORCE_REDOWNLOAD=false` : set to true to force the located server jar to be re-downloaded
- `USE_FLARE_FLAGS=false` : set to true to add appropriate flags for the built-in [Flare](https://blog.airplane.gg/flare) profiler
@@ -80,6 +81,7 @@ A [Purpur](https://purpurmc.org/) server, which is "a drop-in replacement for Pa
The `VERSION` variable is used to lookup a build of Purpur to download
Extra variables:
- `PURPUR_BUILD=LATEST` : set a specific Purpur build to use
- `FORCE_REDOWNLOAD=false` : set to true to force the located server jar to be re-downloaded
- `USE_FLARE_FLAGS=false` : set to true to add appropriate flags for the built-in [Flare](https://blog.airplane.gg/flare) profiler
@@ -129,4 +131,23 @@ If you have attached a host directory to the `/data` volume, then you can instal
## Extra config
- `SKIP_DOWNLOAD_DEFAULTS`: when set to "true" startup will entirely skip checking for default Paper/Bukkit/Spigot config files to download
- `SKIP_DOWNLOAD_DEFAULTS`: when set to "true" startup will entirely skip checking for default Paper/Bukkit/Spigot config files to download
## Configuration Repositories
You can automatically download optimized or custom configuration files (e.g., `bukkit.yml`, `spigot.yml`, `paper-global.yml`, `purpur.yml`) by setting a repository URL. The container will automatically append the Minecraft version to the URL (e.g., `<REPO_URL>/1.21.1/<FILE>`).
| Server Type | Variable |
| :--- | :--- |
| Paper | `PAPER_CONFIG_REPO` |
| Pufferfish | `PUFFERFISH_CONFIG_REPO` |
| Purpur | `PURPUR_CONFIG_REPO` |
### Server Properties
You can also download a base `server.properties` file using `SERVER_PROPERTIES_REPO_URL`.
- **Smart Mode**: If the URL does **not** end in `.properties`, the script treats it as a base URL and appends `/${VERSION}/server.properties` (matching the behavior of the config repos).
- **Direct Mode**: If the URL ends in `.properties`, it downloads that specific file.
**Note**: Environment variables (like `MOTD`, `DIFFICULTY`, `MAX_PLAYERS`) defined in your Docker configuration will **override** values in the downloaded `server.properties` file.

60
examples/optimized-paper-config/README.md
View File

@@ -1,60 +0,0 @@
# A Form to Load New Config Files to Paper MC
In this example, we illustrate how to efficiently load and manage different configuration files to optimize a Paper Minecraft server. To implement this, it is necessary to create a dedicated repository where the configuration files can be stored and later retrieved. The repository should adhere to a specific structure to facilitate seamless integration with your Docker setup. Notably, the configurations must be organized into a folder named after the version of Minecraft you are using.
For reference, I have provided this [repository](https://github.com/Alpha018/paper-config-optimized), which contains optimized configuration files for the latest version of Minecraft. You can use this repository by linking directly to the configuration files in your Docker file, as demonstrated in the example below.
## Usage
You can directly use the optimized configuration files from this repository by accessing them through the GitHub raw URLs. Simply replace the env var like the docker compose with any other repo with different configurations.
To use the raw files, you can download or link to them using the following pattern:
```yaml
services:
mc:
image: itzg/minecraft-server
container_name: paper
environment:
EULA: "true"
TYPE: "PAPER"
VIEW_DISTANCE: 10
MEMORY: 2G
PAPER_CONFIG_REPO: "https://raw.githubusercontent.com/[your-username]/[your-repository]/main/[file-path]"
ports:
- "25565:25565"
volumes:
- mc-paper:/data
restart: unless-stopped
volumes:
mc-paper: {}
```
For example:
```yaml
services:
mc:
image: itzg/minecraft-server
container_name: paper
environment:
EULA: "true"
TYPE: "PAPER"
VIEW_DISTANCE: 10
MEMORY: 2G
PAPER_CONFIG_REPO: "https://raw.githubusercontent.com/Alpha018/paper-config-optimized/main"
ports:
- "25565:25565"
volumes:
- mc-paper:/data
restart: unless-stopped
volumes:
mc-paper: {}
```
Feel free to explore and use the configurations in this repo to enhance your Minecraft server's performance.
## Contribution
If you'd like to improve or suggest changes to these configurations, feel free to submit a pull request in this [repository](https://github.com/Alpha018/paper-config-optimized). We welcome contributions from the community!

129
examples/optimized-server-config/README.md Normal file
View File

@@ -0,0 +1,129 @@
# Optimized Server Configuration (Paper, Purpur, Pufferfish)
This example demonstrates how to automatically download and apply optimized configuration files for your Minecraft server from a remote Git repository. This is useful for maintaining a standard, high-performance configuration across multiple server instances.
## Features
- **Automatic Download**: Fetches `bukkit.yml`, `spigot.yml`, and server-specific configs (`paper-global.yml`, `purpur.yml`, `pufferfish.yml`) on startup.
- **Version Aware**: Downloads configurations from a folder matching your Minecraft version (e.g., `1.21.1`).
- **Base `server.properties`**: Optionally download a base `server.properties` file while still allowing environment variable overrides.
## Repository Structure
Your configuration repository should be structured by Minecraft version. For example:
```text
my-config-repo/
├── 1.21.1/
│ ├── bukkit.yml
│ ├── spigot.yml
│ ├── purpur.yml
│ ├── pufferfish.yml
│ └── server.properties
├── 1.20.4/
│ └── ...
└── README.md
```
## Docker Compose Examples
### 1. Paper Server
For Paper, use `PAPER_CONFIG_REPO`.
```yaml
version: "3.8"
services:
mc:
image: itzg/minecraft-server
environment:
EULA: "TRUE"
TYPE: "PAPER"
VERSION: "1.21.1"
# URL to the root of your config repository (e.g. raw.githubusercontent.com)
# The script automatically appends "/<VERSION>/<FILE>" to this URL.
PAPER_CONFIG_REPO: "https://raw.githubusercontent.com/Alpha018/paper-config-optimized/refs/heads/main"
```
### 2. Purpur Server
For Purpur, use `PURPUR_CONFIG_REPO`.
```yaml
version: "3.8"
services:
mc:
image: itzg/minecraft-server
environment:
EULA: "TRUE"
TYPE: "PURPUR"
VERSION: "1.21.1"
# URL to the root of your config repository (e.g. raw.githubusercontent.com)
# The script automatically appends "/<VERSION>/<FILE>" to this URL.
PURPUR_CONFIG_REPO: "https://raw.githubusercontent.com/Alpha018/paper-config-optimized/refs/heads/main"
```
### 2. Pufferfish Server
For Pufferfish, use `PUFFERFISH_CONFIG_REPO`.
```yaml
version: "3.8"
services:
mc:
image: itzg/minecraft-server
environment:
EULA: "TRUE"
TYPE: "PUFFERFISH"
VERSION: "1.21.1" # Must match a folder in your repo
# Automagically download optimized configs (bukkit.yml, spigot.yml, pufferfish.yml)
PUFFERFISH_CONFIG_REPO: "https://raw.githubusercontent.com/Alpha018/paper-config-optimized/refs/heads/main"
```
### 3. Downloading `server.properties` (Optional)
If you also want to download a base `server.properties` file from your repository, you must explicitly set `SERVER_PROPERTIES_REPO_URL`.
**Smart Feature**:
- If you provide a **base URL** (like the repo root), the script will automatically append `/<VERSION>/server.properties`.
- If you provide a **full URL** (ending in `.properties`), it will download that specific file.
**Crucial Note**: Environment variables (like `MOTD`, `DIFFICULTY`, `MAX_PLAYERS`) in your Docker Compose **WILL override** values in the downloaded file. This allows you to have a shared optimized base but customize specifics per instance.
```yaml
environment:
# ... other vars ...
# Option A: Base URL (Smart)
# Will look for: https://.../main/1.21.1/server.properties
SERVER_PROPERTIES_REPO_URL: "https://raw.githubusercontent.com/Alpha018/paper-config-optimized/refs/heads/main"
# Option B: Specific URL (Manual)
# SERVER_PROPERTIES_REPO_URL: "https://gist.githubusercontent.com/.../server.properties"
# These will OVERRIDE settings in the downloaded file
MOTD: "My Custom Instance"
MAX_PLAYERS: 50
```
## Supported Variables
| Variable | Description |
| :--- | :--- |
| `PAPER_CONFIG_REPO` | Base URL for Paper configs. Downloads `paper-global.yml`, `bukkit.yml`, `spigot.yml`, etc. |
| `PURPUR_CONFIG_REPO` | Base URL for Purpur configs. Downloads `purpur.yml`, `bukkit.yml`, `spigot.yml`. |
| `PUFFERFISH_CONFIG_REPO` | Base URL for Pufferfish configs. Downloads `pufferfish.yml`, `bukkit.yml`, `spigot.yml`. |
| `SERVER_PROPERTIES_REPO_URL` | Boolean/URL. Set to download `server.properties`. Can be a base URL or direct file link. |
## Contribution
Got ideas to squeeze even more performance out of these configs? Or maybe you found a better way to structure things?
I'd love to see your improvements! Feel free to open a Pull Request or an Issue in the [repository](https://github.com/Alpha018/paper-config-optimized). Let's make these configs the best they can be together.

0
examples/optimized-paper-config/docker-compose.yml → examples/optimized-server-config/docker-compose.yml
View File

5
scripts/start-deployPufferfish
View File

@@ -41,6 +41,11 @@ if [[ ! -f "$SERVER" ]] || isTrue "${FORCE_REDOWNLOAD:-false}"; then
exit 3
fi
fi
if [[ "${PUFFERFISH_CONFIG_REPO}" ]]; then
defaultTopLevelConfigs=(bukkit.yml spigot.yml pufferfish.yml)
DOWNLOAD_DEFAULTS=$(buildDownloadList "$PUFFERFISH_CONFIG_REPO" "$VERSION" "${defaultTopLevelConfigs[@]}")
export DOWNLOAD_DEFAULTS
fi
# Normalize on Spigot for later operations
export FAMILY=SPIGOT

7
scripts/start-deployPurpur
View File

@@ -4,6 +4,7 @@ IFS=$'\n\t'
: "${PURPUR_BUILD:=LATEST}"
: "${PURPUR_DOWNLOAD_URL:=}"
: "${PURPUR_CONFIG_REPO:=}"
# shellcheck source=start-utils
. "$(dirname "$0")/start-utils"
@@ -36,6 +37,12 @@ fi
applyResultsFile ${resultsFile}
if [[ "${PURPUR_CONFIG_REPO}" ]]; then
defaultTopLevelConfigs=(bukkit.yml spigot.yml purpur.yml)
DOWNLOAD_DEFAULTS=$(buildDownloadList "$PURPUR_CONFIG_REPO" "$VERSION" "${defaultTopLevelConfigs[@]}")
export DOWNLOAD_DEFAULTS
fi
# Normalize on Spigot for later operations
export FAMILY=SPIGOT

16
scripts/start-setupServerProperties
View File

@@ -134,6 +134,22 @@ if [[ ${TYPE} == "CURSEFORGE" ]]; then
fi
if ! isTrue "${SKIP_SERVER_PROPERTIES}"; then
if [ ! -e "$SERVER_PROPERTIES" ] && [[ "${SERVER_PROPERTIES_REPO_URL:-}" ]]; then
# Helper to support base URLs (like the config repos)
# If the URL doesn't end in .properties, assume it is a base and append version/file
if [[ "${SERVER_PROPERTIES_REPO_URL}" != *".properties" ]]; then
SERVER_PROPERTIES_REPO_URL=$(buildDownloadList "$SERVER_PROPERTIES_REPO_URL" "$VERSION" server.properties)
fi
if ! mc-image-helper mcopy \
--to "$(dirname "$SERVER_PROPERTIES")" \
--skip-existing \
--ignore-missing-sources \
"$SERVER_PROPERTIES_REPO_URL"; then
logWarning "Failed to download server.properties from ${SERVER_PROPERTIES_REPO_URL}"
fi
fi
if [ ! -e "$SERVER_PROPERTIES" ]; then
log "Creating server properties in ${SERVER_PROPERTIES}"