fix: migrate PaperMC to v3 API, fix NeoForge beta fallback, add test suite
- Migrate Paper loader from sunset v2 API to v3 (fill.papermc.io) - Fix NeoForge: fall back to beta versions when no stable exists (set -e + grep) - Fix setEula/setperms ordering (was writing eula.txt before /data was writable) - Fix setEula/serverInfoWrite to use absolute paths (/data/server/) - Add VOLUME directive removal (was shadowing bind mounts) - Add comprehensive API test suite (110 tests across 6 suites) - Move test.sh to tests/integration.sh, switch to named volumes - Add Docker build cache to CI workflows - Add .editorconfig, expand .gitignore, improve README docs
This commit is contained in:
@@ -2,7 +2,16 @@
|
||||
|
||||
A Docker image for running Minecraft servers with support for multiple loaders.
|
||||
|
||||
## Usage
|
||||
## Features
|
||||
|
||||
- **Multi-loader support** — Vanilla, Paper, Fabric, Forge, NeoForge, and Bedrock
|
||||
- **Auto-detection** — Java version and loader versions are auto-detected from Mojang manifests
|
||||
- **Persistent data** — Server files, worlds, and Java installations are stored in `/data`
|
||||
- **Health checks** — Built-in container health monitoring
|
||||
- **Flexible Java** — Pin or auto-detect Java version (Temurin, Zulu, GraalVM, etc.)
|
||||
- **Bedrock support** — Native Bedrock Dedicated Server without Java
|
||||
|
||||
## Quick Start
|
||||
|
||||
```yaml
|
||||
services:
|
||||
@@ -33,13 +42,13 @@ services:
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `EULA` | — | **Required.** Set to `true` to accept the Minecraft EULA |
|
||||
| `MC_VERSION` | — | Minecraft version (e.g., `1.21.1`) |
|
||||
| `MC_LOADER` | — | Server loader: `vanilla`, `paper`, `fabric`, `forge`, or `neoforge` |
|
||||
| `MC_VERSION` | — | Minecraft version (e.g., `1.21.1`). Required for Java loaders; auto-detected for Bedrock |
|
||||
| `MC_LOADER` | — | **Required.** Server loader: `vanilla`, `paper`, `fabric`, `forge`, `neoforge`, or `bedrock` |
|
||||
| `MC_LOADER_VERSION` | — | Fallback version for any loader |
|
||||
| `FABRIC_LOADER_VERSION` | `$MC_LOADER_VERSION` | Fabric loader version |
|
||||
| `FORGE_VERSION` | `$MC_LOADER_VERSION` | Forge version (e.g., `52.1.14`) |
|
||||
| `NEOFORGE_VERSION` | `$MC_LOADER_VERSION` | NeoForge version (e.g., `21.1.185`) |
|
||||
| `PAPER_BUILD` | latest | Paper build number (auto-detects latest if unset) |
|
||||
| `PAPER_BUILD` | latest | Paper build number (auto-detects latest stable if unset) |
|
||||
| `JAVA_VERSION` | auto-detected | Java version (via Jabba, e.g., `temurin@21`, `zulu@17`). Auto-detects from Mojang manifest if unset: 1.20.5+→21, 1.17-1.20.4→17, 1.17→16, pre-1.17→8 |
|
||||
| `JAR` | `server.jar` | Server jar filename |
|
||||
| `XMS` | `2G` | Initial Java heap size |
|
||||
@@ -50,13 +59,157 @@ services:
|
||||
|
||||
## Supported Loaders
|
||||
|
||||
- **Vanilla** — Official Mojang server
|
||||
- **Paper** — High-performance papermc.io
|
||||
- **Fabric** — Lightweight mod loader via fabricmc.net
|
||||
- **Forge** — Heavyweight mod loader via minecraftforge.net
|
||||
- **NeoForge** — Fork of Forge via neoforged.net
|
||||
- **Bedrock** — Official Bedrock dedicated server (native binary, no Java required)
|
||||
| Loader | Description | Ports |
|
||||
|---|---|---|
|
||||
| **Vanilla** | Official Mojang server | TCP 25565 |
|
||||
| **Paper** | High-performance fork from papermc.io | TCP 25565 |
|
||||
| **Fabric** | Lightweight mod loader via fabricmc.net | TCP 25565 |
|
||||
| **Forge** | Mod loader via minecraftforge.net | TCP 25565 |
|
||||
| **NeoForge** | Community fork of Forge via neoforged.net | TCP 25565 |
|
||||
| **Bedrock** | Official Bedrock Dedicated Server (no Java) | UDP 19132 |
|
||||
|
||||
## Volumes
|
||||
|
||||
- `/data` — Persists server data, worlds, config, and Java installations
|
||||
|
||||
## Loader-Specific Examples
|
||||
|
||||
### Paper
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- EULA=true
|
||||
- MC_VERSION=1.21.1
|
||||
- MC_LOADER=paper
|
||||
- PAPER_BUILD=132 # optional, auto-detects latest stable
|
||||
```
|
||||
|
||||
### Fabric
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- EULA=true
|
||||
- MC_VERSION=1.21.1
|
||||
- MC_LOADER=fabric
|
||||
- FABRIC_LOADER_VERSION=0.19.3 # optional, auto-detects latest
|
||||
```
|
||||
|
||||
### Forge / NeoForge
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- EULA=true
|
||||
- MC_VERSION=1.21.1
|
||||
- MC_LOADER=forge # or neoforge
|
||||
- FORGE_VERSION=52.1.14 # optional, auto-detects latest
|
||||
```
|
||||
|
||||
### Bedrock
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- EULA=true
|
||||
- MC_LOADER=bedrock
|
||||
- MC_VERSION=1.21.50 # Bedrock server version
|
||||
ports:
|
||||
- 19132:19132/udp
|
||||
- 19133:19133/udp # IPv6 (optional)
|
||||
```
|
||||
|
||||
## Java Version Management
|
||||
|
||||
Java is managed via [Jabba](https://github.com/Jabba-Team/jabba). Java installations are cached in `/data/java/` so they persist across container restarts.
|
||||
|
||||
Supported distributions include `temurin`, `zulu`, `adopt`, `openjdk`, `graalvm`, and more. Use the format `distribution@version`:
|
||||
|
||||
```yaml
|
||||
- JAVA_VERSION=temurin@21
|
||||
- JAVA_VERSION=zulu@17
|
||||
- JAVA_VERSION=graalvm@21
|
||||
```
|
||||
|
||||
If unset, the Java version is auto-detected from the Mojang version manifest based on `MC_VERSION`.
|
||||
|
||||
## Health Checks
|
||||
|
||||
The container includes a built-in health check:
|
||||
|
||||
- **Java servers** — TCP check on port 25565
|
||||
- **Bedrock servers** — UDP check on port 19132
|
||||
|
||||
The health check has a 2-minute start period to allow the server time to initialize.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server fails to start
|
||||
|
||||
Check the container logs:
|
||||
|
||||
```bash
|
||||
docker logs minecraft
|
||||
```
|
||||
|
||||
### EULA not accepted
|
||||
|
||||
If you see an EULA error, make sure `EULA=true` is set in your environment variables.
|
||||
|
||||
### Java not found
|
||||
|
||||
If Java installation fails, check that the `/data` volume is writable. Java is installed to `/data/java/` on first run.
|
||||
|
||||
### Wrong UID/GID
|
||||
|
||||
If you get permission errors on server files, check that `PUID` and `PGID` match your host user:
|
||||
|
||||
```bash
|
||||
id -u # your UID
|
||||
id -g # your GID
|
||||
```
|
||||
|
||||
### Port conflicts
|
||||
|
||||
Make sure the Minecraft port (25565 for Java, 19132 for Bedrock) is not already in use:
|
||||
|
||||
```bash
|
||||
ss -tlnp | grep 25565
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Building locally
|
||||
|
||||
```bash
|
||||
docker build -t dockercraft:local .
|
||||
```
|
||||
|
||||
### Running tests
|
||||
|
||||
**API tests** — verify all external APIs are healthy and returning correct data (no Docker needed):
|
||||
|
||||
```bash
|
||||
# All suites
|
||||
./tests/run_tests.sh
|
||||
|
||||
# Specific MC version
|
||||
./tests/run_tests.sh -m 1.21.1
|
||||
|
||||
# Specific suites only
|
||||
./tests/run_tests.sh -s mojang,fabric,neoforge
|
||||
```
|
||||
|
||||
**Integration tests** — spin up Docker containers and verify full download → install → server start:
|
||||
|
||||
```bash
|
||||
# Test all loaders
|
||||
./tests/integration.sh
|
||||
|
||||
# Test a specific loader
|
||||
./tests/integration.sh -m 1.21.1 -l fabric
|
||||
|
||||
# Custom timeout
|
||||
./tests/integration.sh -t 300
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
See [LICENSE](LICENSE) for details.
|
||||
|
||||
Reference in New Issue
Block a user