CurseForge-Modpacks mit Docker Compose betreiben

Pack, Loader, Java und Speicher gemeinsam behandeln

Ein CurseForge-Pack legt Minecraft, Loader, Mods und Konfiguration fest. AUTO_CURSEFORGE liest das Manifest und installiert den dort vorgesehenen Forge- oder Fabric-Loader.

Wähle nicht unabhängig einen vermeintlich besseren Loader. Pinne eine getestete Pack-Datei und folge ihren Java- und Speicheranforderungen.

Voraussetzungen

• CurseForge-Pack mit Serverunterstützung
• File-ID der normalen Pack-Datei, nicht des separaten Server-Downloads
• ausreichend RAM und Speicherplatz
• zur Minecraft-Version passender Java-Tag
• dieselbe Pack-Version auf den Test-Clients
• vollständiges Backup vor Übernahme einer Welt

Compose-Grundlage mit fester File-ID

Die folgende ATM8-ID stammt aus dem offiziellen itzg-Beispiel. Sie ist bewusst konkret und älter. Für ein anderes Pack müssen Slug, File-ID, Java und Speicher gemeinsam ersetzt werden.

services:
  mc:
    image: itzg/minecraft-server:java17
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: AUTO_CURSEFORGE
      CF_SLUG: all-the-mods-8
      CF_FILE_ID: "4248390"
      CF_API_KEY_FILE: /run/secrets/cf_api_key
      MEMORY: 6G
    mem_limit: 8g
    volumes:
      - ./data:/data
      - ./downloads:/downloads:ro
    secrets:
      - cf_api_key

secrets:
  cf_api_key:
    file: ./cf_api_key.secret

Lege cf_api_key.secret neben Compose an, beschränke die Host-Rechte und schließe die Datei aus Git aus. Solange du den im Image enthaltenen Key nutzt, entferne CF_API_KEY_FILE und beide Secret-Deklarationen.

docker compose config
docker compose pull mc

Warum die File-ID wichtig ist

Ohne CF_FILE_ID sucht das Image bei einem späteren Start erneut nach dem neuesten Pack. Ein normaler Neustart kann dadurch ungewollt Pack und Loader aktualisieren.

Pinning funktioniert per konkreter Datei-URL, CF_FILE_ID oder CF_FILENAME_MATCHER. Die numerische ID ist am eindeutigsten. Wähle nicht das separat veröffentlichte Server File: Ihm fehlt üblicherweise das Manifest für AUTO_CURSEFORGE.

Erster Start auf leeren Daten

mkdir -p data downloads
docker compose up -d
docker compose logs -f mc

Der Erststart lädt viele Artefakte und dauert deutlich länger als Paper. Warte auf die Bereitschaftsmeldung. Bei einem Fehler sichere die erste Meldung, bevor die Restart-Policy weitere Starts anhängt.

Manuell benötigte Downloads

Wenn Autoren die Drittverteilung untersagen, protokolliert das Image eine „Mods Need Download“-Liste:

1. angegebene Seite im Browser öffnen
2. exakt verlangte Datei herunterladen
3. in den Host-Ordner ./downloads kopieren
4. docker compose up -d mc erneut ausführen

Rate keine direkte curl-URL. Die itzg-Dokumentation verlangt für diese eingeschränkten Dateien ausdrücklich einen Browserdownload.

Installation prüfen

docker compose exec mc rcon-cli version
docker compose exec mc sh -c 'find /data/mods -maxdepth 1 -type f -name "*.jar" | wc -l'
docker compose logs --since=20m mc

Tritt mit dem exakt passenden Client-Pack bei und prüfe eigene Blöcke, Gegenstände, Dimensionen, Rezepte und erneuten Login. Erstelle danach das erste Backup.

Ausschlüsse und Synchronisierung

CF_EXCLUDE_MODS ist für fälschlich serverseitig ausgelieferte Client-Mods gedacht, CF_FORCE_INCLUDE_MODS für falsch als client-only markierte Server-Mods. Melde fehlerhafte Metadaten beim Projekt.

CF_FORCE_SYNCHRONIZE: "TRUE" gleicht den installierten Stand bewusst mit dem Pack ab. Nutze es nur nach Backup zur Fehlerbehebung und entferne es anschließend.

Pack aktualisieren und zurückrollen

Behandle eine neue File-ID wie ein Serverupdate: Backup und vollständige Stop-Kopie erstellen, nur CF_FILE_ID ändern, Start und Client prüfen. Bei Fehlern alte Compose-Datei und /data gemeinsam wiederherstellen.

Arbeite dafür das Update- und Rollback-Runbook ab. Ein altes Pack darf nicht auf bereits migrierte Weltdaten starten.

Fehlerbehebung

Nächste Schritte

• Mit dem Modrinth-Modpack-Guide vergleichen.
• Fehlstarts über das Restart-Loop-Runbook untersuchen.
• API-Key und Host mit der Docker-Sicherheitsbasis schützen.