Paper-Plugins mit Docker Compose installieren

Pro Plugin-JAR genau einen Verwalter festlegen

Paper-Plugins laufen mit uneingeschränktem Zugriff auf Serverprozess und Dateien. Installiere nur vertrauenswürdige Software und lege für jedes JAR einen eindeutigen Verwaltungsweg fest.

Für itzg/minecraft-server sind zwei Varianten sinnvoll:

• kuratierte lokale JARs: Quellordner unter /plugins einbinden
• deklarative Modrinth-Projekte: Projekte in MODRINTH_PROJECTS aufführen

Verwalte dasselbe Plugin nicht mit beiden Methoden. Doppelte Versionen führen häufig dazu, dass Paper das Plugin deaktiviert.

Voraussetzungen

• TYPE: PAPER im Service mc
• fest eingestellte Minecraft-/Paper-Version
• Backup von Welten, Konfigurationen, Plugin-Daten und Plugin-JARs
• vertrauenswürdiges Plugin-Release für genau deine Minecraft-Version

Falls das Server-Ökosystem noch nicht feststeht, vergleiche zuerst Paper, Vanilla, Fabric, Forge und NeoForge.

Variante A: kuratierten Plugin-Ordner synchronisieren

Lege neben compose.yml den Ordner plugins-source an, kopiere geprüfte JARs hinein und mounte ihn schreibgeschützt:

services:
  mc:
    image: itzg/minecraft-server:java25
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      VERSION: "26.1.2"
    volumes:
      - ./data:/data
      - ./plugins-source:/plugins:ro

Das Image synchronisiert /plugins bei pluginfähigen Servertypen nach /data/plugins. Das Ziel bleibt beschreibbar, damit Plugins Konfiguration und Daten anlegen können.

Prüfe vor dem Einspielen, ob die Datei wirklich ein Plugin-JAR und keine Mod oder HTML-Fehlerseite ist:

file plugins-source/*.jar
sha256sum plugins-source/*.jar
docker compose config

Notiere Quelle, Release-Version und Prüfsumme in deiner Betriebsdokumentation.

Variante B: Plugins über Modrinth verwalten

Das Image kann anhand von TYPE und VERSION kompatible Plugin-Releases auflösen:

services:
  mc:
    image: itzg/minecraft-server:java25
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      VERSION: "26.1.2"
      MODRINTH_PROJECTS: |
        luckperms:v5.5.53-bukkit
    volumes:
      - ./data:/data

Das Beispiel pinnt den getesteten Bukkit-Build von LuckPerms 5.5.53 über seine Versionsnummer. Eine Versions-ID wird ebenfalls unterstützt, übergeht aber die Minecraft- und Loader-Kompatibilitätsprüfung des Images. Prüfe die Kompatibilität selbst, bevor du eine ID verwendest. Ein nicht gepinnter Slug folgt dem neuesten kompatiblen Release und kann sich bei einem späteren Containerstart ändern.

Dieser Weg kann auch Downloads entfernen, die du aus der Liste löschst. Halte manuell verwaltete JARs getrennt, damit ihre Zuständigkeit sichtbar bleibt.

Sicher installieren oder aktualisieren

1. Release Notes und Abhängigkeiten lesen.
2. Backup auslösen und Erfolg kontrollieren.
3. Vor dem Austausch eines lokalen JARs oder einer Modrinth-Versions-ID den Server stoppen.
4. Sicherstellen, dass nur eine Plugin-Version vorhanden ist.
5. Service neu erstellen und Startprotokoll prüfen.

docker compose stop mc
docker compose config
docker compose up -d mc
docker compose logs -f mc

Nutze /reload nicht als Ersatz für einen Neustart. Plugin-Lebenszyklus und Abhängigkeiten lassen sich bei einem sauberen Start zuverlässiger prüfen.

Plugin prüfen

docker compose exec mc rcon-cli plugins
docker compose exec mc sh -c 'find /data/plugins -maxdepth 1 -type f -name "*.jar" -print'
docker compose logs --since=10m mc

Nach Paper-Dokumentation erscheint ein aktives Plugin in der plugins-Ausgabe grün. Teste außerdem eine echte Funktion und kontrolliere data/logs/latest.log auf Lade- und Abhängigkeitsfehler.

Fehlgeschlagene Änderung zurückrollen

Stoppe den Service, stelle das alte JAR beziehungsweise die alte Modrinth-Referenz und die zugehörigen Plugin-Daten wieder her und starte neu. Ein neues Release kann seine Konfiguration migriert haben; nur das JAR zurückzutauschen reicht dann nicht.

Für eine kombinierte Paper- und Plugin-Änderung gilt das umfassendere Update- und Rollback-Runbook.

Fehlerbehebung

Nächste Schritte

• Vor dem nächsten Paper-Update das sichere Update- und Rollback-Runbook abarbeiten.
• Plugin-bedingte Last mit spark auf Paper und Docker untersuchen.
• Für ein vollständiges Modpack statt Plugins den Modrinth-Docker-Guide nutzen.