stronghold/references/itzg-projects.md

itzg Projects Reference

These are the core Docker projects by itzg that Stronghold will integrate with.

itzg/docker-minecraft-server

GitHub: https://github.com/itzg/docker-minecraft-server
Docs: https://docker-minecraft-server.readthedocs.io/en/latest/

Overview

Docker image for running Minecraft Java Edition servers. Automatically downloads the specified version at startup.

Key Features

• Automatic Version Management: Downloads and sets up the specified Minecraft version at startup
• Server Type Support: Supports multiple server types via TYPE environment variable:
  • VANILLA
  • PAPER (optimized, recommended)
  • FORGE (modded servers)
  • FABRIC (modded servers)
  • SPIGOT
  • BUKKIT
  • And more
• Configuration via Environment Variables: Extensive configuration through environment variables for:
  • Server properties (gamemode, difficulty, seed, etc.)
  • Memory allocation (MEMORY)
  • Java version selection
  • Modpack installation
  • Plugin management
• Modpack Integration:
  • Supports Modrinth and CurseForge modpack installation
  • Can download server packs automatically
  • Handles mod installation and updates
  • Feed the Beast (FTB) support
  • Packwiz modpack support
• Data Persistence: Uses /data volume for:
  • World data
  • Server configurations
  • Mods and plugins
  • Logs
• Health Monitoring: Built-in health checks
• RCON Support: Built-in RCON support for remote console access
• Resource Management: Memory and CPU allocation via Docker

Important Environment Variables

• TYPE: Server type (VANILLA, PAPER, FORGE, FABRIC, etc.)
• VERSION: Minecraft version (LATEST, specific version, or SNAPSHOT)
• MEMORY: JVM memory allocation
• EULA: Must be set to TRUE to accept Minecraft EULA
• MOTD: Server message of the day
• DIFFICULTY: Game difficulty
• MODE: Game mode (survival, creative, adventure, spectator)
• MODPACK: Modpack URL or ID for automatic installation

Mods and Plugins Management

Reference: itzg Mods and Plugins Documentation

Modpack Platforms Supported

• Modrinth: Auto-download modpacks from Modrinth
• CurseForge: Auto-download modpacks from CurseForge
• Feed the Beast (FTB): FTB modpack support
• Packwiz: Packwiz format modpacks

Modpack Installation Methods

1. MODPACK Environment Variable:

   • Set MODPACK to a zip file URL or container path
   • Automatically downloads and installs modpack
   • Works with zip files containing jar files at top level

2. GENERIC_PACK / GENERIC_PACKS:

   • Install all server content (jars, mods, plugins, configs) from zip/tgz
   • Can apply CurseForge modpacks missing server start script
   • Supports multiple packs: GENERIC_PACKS=pack1,pack2
   • Prefix/suffix support: GENERIC_PACKS_PREFIX and GENERIC_PACKS_SUFFIX
   • Update checksum control: SKIP_GENERIC_PACK_CHECKSUM, SKIP_GENERIC_PACK_UPDATE_CHECK, FORCE_GENERIC_PACK_UPDATE
   • Can disable specific mods: GENERIC_PACKS_DISABLE_MODS

Individual Mod/Plugin Installation

1. MODS / PLUGINS Environment Variables:

   • Comma or newline delimited list of:
     • URLs of jar files
     • Container paths to jar files
     • Container paths to directories containing jars
   • Example:

     MODS: |
       https://example.com/mod1.jar
       /plugins/common/mod2.jar
     

   • Auto-removal: Entries removed from list automatically remove files from server
   • Empty list removes all mods/plugins

2. MODS_FILE / PLUGINS_FILE:

   • Path or URL to text file listing mod/plugin URLs (one per line)
   • Blank lines and lines starting with # are ignored
   • Useful for managing large mod lists

Volume Mount Points for Mods/Plugins

1. /plugins Volume:

   • Syncs into /data/plugins for plugin-based server types
   • Customizable: COPY_PLUGINS_SRC, COPY_PLUGINS_DEST
   • Set USES_PLUGINS=true for hybrid mod-based loaders using plugins

2. /mods Volume:

   • Syncs into /data/mods for mod-based server types
   • Customizable: COPY_MODS_SRC, COPY_MODS_DEST

3. /config Volume:

   • Syncs into /data/config by default
   • Customizable: COPY_CONFIG_SRC, COPY_CONFIG_DEST
   • Environment variable processing on config files
   • SYNC_SKIP_NEWER_IN_DESTINATION=false to force overwrite

4. Multiple Source Directories:

   • COPY_PLUGINS_SRC, COPY_MODS_SRC, COPY_CONFIG_SRC can be comma/newline delimited lists
   • Allows combining shared and project-specific mods/plugins

Environment Variable Processing

• Config files matching suffixes in REPLACE_ENV_SUFFIXES (default: "yml,yaml,txt,cfg,conf,properties,hjson,json,tml,toml")
• Exclusions: REPLACE_ENV_VARIABLES_EXCLUDES, REPLACE_ENV_VARIABLES_EXCLUDE_PATHS
• Disable with: REPLACE_ENV_DURING_SYNC=false

Removing Old Mods/Plugins

• REMOVE_OLD_MODS=TRUE: Delete old mods/plugins before installing new ones
• Fine-tuning options:
  • REMOVE_OLD_MODS_INCLUDE: Comma-separated glob patterns to include
  • REMOVE_OLD_MODS_EXCLUDE: Comma-separated glob patterns to exclude
  • REMOVE_OLD_MODS_DEPTH: Maximum directory depth (default: 16)
  • Default: Only jar files are removed

Additional Configuration Files

• APPLY_EXTRA_FILES: Download/copy additional config files before server starts
• Format: destination<source_url or destination<source_path
• Multiple entries with comma/newline separation
• Useful for baseline configs to be patched at runtime
• Processed before patch processing

Mods vs Plugins

• Mods: Client-side modifications for Forge/Fabric servers
  • Modify rendering, add blocks, add behaviors
  • Usually need to be installed on both client and server
• Plugins: Server-only modifications for Bukkit/Spigot/Paper
  • Add behaviors, commands, features
  • Only installed on server
• Hybrid: Some types like Magma use both mods and plugins

Usage Pattern

Stronghold will need to:

1. Generate docker-compose.yml files or use Docker API to create containers
2. Set appropriate environment variables based on user configuration
3. Mount volumes for persistent data storage
4. Expose appropriate ports
5. Handle container lifecycle (start, stop, restart, delete)

---

itzg/docker-mc-proxy

GitHub: https://github.com/itzg/docker-mc-proxy

Overview

Docker image for running Minecraft proxy servers (BungeeCord, Waterfall, Velocity). Enables managing multiple Minecraft servers under a single proxy network.

Key Features

• Proxy Type Support:
  • BungeeCord
  • Waterfall (BungeeCord fork)
  • Velocity
• Configuration Management:
  • Configuration files via volume mounts
  • Environment variable substitution in config files
  • Automatic config synchronization
• Plugin Support:
  • Plugins mounted via volumes
  • Supports proxy-specific plugins
• Port Configuration:
  • Default proxy port (25577) can be mapped
  • Custom port configuration
• Health Checks: Built-in health monitoring
• Java Version Support: Multiple Java version tags available
• Multi-Architecture: Supports multiple CPU architectures

Usage Pattern

Stronghold will need to:

1. Create proxy containers with appropriate type
2. Configure proxy config files (config.yml, servers.yml, etc.)
3. Link backend servers to the proxy
4. Manage plugin installation
5. Handle port mapping and routing

---

itzg/mc-router

GitHub: https://github.com/itzg/mc-router

Overview

Lightweight TCP reverse proxy/multiplexer for Minecraft Java servers. Routes client connections to backend servers based on the requested server address (SRV records or subdomain).

Key Features

• Dynamic Routing: Routes based on server address requested by client
• Docker Auto-Discovery: Automatically discovers running Minecraft containers
• Health Checks: Monitors backend server health
• Load Balancing: Can distribute connections across multiple servers
• REST API: Provides REST API for managing routes
• High Availability: Redirects to operational servers if one fails
• Configuration:
  • Can be configured via environment variables
  • Supports static route configuration
  • Docker labels for dynamic discovery

Usage Pattern

Stronghold will need to:

1. Deploy mc-router container alongside servers
2. Configure routing rules (static or dynamic)
3. Use Docker labels for auto-discovery
4. Manage backend server registrations via REST API
5. Monitor route health and availability

---

itzg/docker-rcon-web-admin

GitHub: https://github.com/itzg/docker-rcon-web-admin

Overview

Web-based admin interface for Minecraft servers via RCON (Remote Console).

Key Features

• RCON Integration: Connects to Minecraft servers via RCON protocol
• Web Interface: Browser-based console access
• Command Execution: Execute server commands remotely
• Log Viewing: View server logs in real-time
• Docker Integration: Runs as a side-car container

Usage Pattern

Stronghold may want to:

1. Integrate RCON functionality directly rather than using separate container
2. Use this as reference for RCON implementation
3. Potentially use as a fallback/admin interface

---

Key Takeaways for Stronghold

1. Environment Variable Configuration: All itzg containers use extensive environment variable configuration. Stronghold needs a robust system for:

   • UI to configure these variables
   • Validating configurations
   • Generating docker-compose.yml files or Docker API calls

2. Volume Management: Need to manage Docker volumes for:

   • Server data persistence
   • Configuration files
   • Mods/plugins
   • Backups

3. Network Management: Need to handle:

   • Port allocation and mapping
   • Internal Docker networking for proxy/server communication
   • External port exposure

4. Lifecycle Management: Complete container lifecycle:

   • Create (with proper configuration)
   • Start/Stop/Restart
   • Update/Upgrade
   • Delete (with data handling)

5. Integration Points:

   • Docker API for container management
   • RCON for server console access
   • Health checks for monitoring
   • REST APIs (mc-router) for advanced routing

6. Mod/Plugin Management Complexity: The itzg container provides extensive mod/plugin management options:

   • Multiple modpack platforms (Modrinth, CurseForge, FTB, Packwiz)
   • Multiple installation methods (MODPACK, GENERIC_PACK, MODS/PLUGINS vars, file lists)
   • Volume mounts for mods/plugins/configs
   • Auto-removal of mods/plugins
   • Environment variable substitution in configs
   • Stronghold UI should simplify these options while exposing flexibility when needed
   • Consider wizard-based flows for common scenarios (modpack installation) vs advanced configuration for power users