stronghold/references/examples/EXAMPLES-ANALYSIS.md

Detailed Example Analysis

This document provides detailed analysis of each example docker-compose file from the itzg repository.

1. docker-compose-big.yml - Large Biomes World Type

Source: itzg/docker-minecraft-server/examples/docker-compose-big.yml

Purpose

Demonstrates configuration for a vanilla Minecraft server with:

• Large Biomes world generation
• High memory allocation (32G)
• RCON web admin integration
• Performance tuning settings

Key Features

World Configuration

• LEVEL_TYPE: LARGEBIOMES - Generates worlds with larger biome sizes

Performance Settings

• MAX_MEMORY: 32G - Very high memory allocation (for large servers)
• MAX_BUILD_HEIGHT: 256 - Standard build height
• VIEW_DISTANCE: 15 - Moderate view distance
• MAX_PLAYERS: 100 - High player capacity
• CONSOLE: "false" - Disables console (likely uses RCON instead)

Multi-Service Setup

• minecraft: Main server container
• rcon: Separate RCON web admin service (itzg/rcon)
  • Exposes ports 4326 and 4327 for web admin access
  • Uses separate volume for RCON database

Stronghold Implementation Notes

1. World Type Selection: UI needs dropdown/selector for world types:

   • DEFAULT
   • FLAT
   • LARGEBIOMES
   • AMPLIFIED
   • And modded world types (e.g., "biomesoplenty")

2. Memory Presets: Provide memory presets:

   • Small (1-2G): Single player / small groups
   • Medium (4-8G): Small servers
   • Large (16G+): Large servers
   • Custom: User-specified

3. RCON Integration: Show option to include RCON web admin:

   • Separate service
   • Automatic port configuration
   • Link to web admin interface

4. Performance Tuning: Advanced options panel:

   • View distance
   • Max players
   • Build height
   • Console enable/disable

---

2. docker-compose-curseforge-atm7.yaml - All The Mods 7

Source: itzg/docker-minecraft-server/examples/docker-compose-curseforge-atm7.yaml

Purpose

Complete example for installing "All The Mods 7" modpack from CurseForge. This is a comprehensive, well-documented example that serves as an excellent template.

Key Features

CurseForge Modpack Installation

• TYPE: CURSEFORGE - CurseForge modpack type
• CF_SERVER_MOD: /modpacks/ATM7-0.4.32-server.zip - Path to modpack server files
• Modpack zip file mounted from local ./modpacks directory

Extensive Configuration

• Memory: 8G - Appropriate for large modpacks
• Timezone: America/New_York - Server timezone configuration
• Logging: ENABLE_ROLLING_LOGS: "true" - Automatic log rotation
• Game Options: Extensive server properties override

Server Properties Override

• OVERRIDE_SERVER_PROPERTIES: "true" - Allows environment variable overrides
• Custom difficulty, view distance, max players
• PVP settings
• Level type (biomesoplenty for ATM7)
• MOTD customization
• Flight allowed
• Max tick time set to -1 (no timeout)

Edge Cases Demonstrated

1. EULA in Modpack: Important note that EULA file in modpack.zip will overwrite EULA flag
2. Local Modpack Files: Shows mounting local modpacks directory
3. Custom Container Name: container_name: mc_atm7
4. Restart Policy: unless-stopped for persistence

Stronghold Implementation Notes

1. Modpack Installation Wizard:

   • Step 1: Select modpack source (CurseForge, Modrinth, local file, URL)
   • Step 2: If local file, prompt for file path or upload
   • Step 3: Auto-detect recommended memory based on modpack size/complexity
   • Step 4: Configuration presets (can customize later)

2. Configuration UI Sections:

   • Basic: EULA, memory, restart policy
   • Modpack: Type, source, file path
   • Performance: View distance, max players, tick time
   • Gameplay: Difficulty, PVP, flight, MOTD
   • Advanced: Override flags, timezone, logging

3. Modpack Detection:

   • Parse modpack manifest to suggest:
     • Server type (FORGE/FABRIC)
     • Recommended memory
     • Minecraft version
     • Required mods/dependencies

4. File Management:

   • UI for managing modpack files
   • Upload/download modpack files
   • Version selection
   • Update notifications

5. Template Generation:

   • Use this as a template for modpack installations
   • Generate similar structure with user's selections

---

3. docker-compose-curseforge.yml - Basic CurseForge Example

Source: itzg/docker-minecraft-server/examples/docker-compose-curseforge.yml

Purpose

Minimal example showing CurseForge modpack installation. Demonstrates simplicity for basic use cases.

Key Features

Minimal Configuration

• Only essential variables
• TYPE: CURSEFORGE
• CF_SERVER_MOD pointing to modpack zip
• Uses environment variable substitution: ${IMAGE_TAG:-java8}

Multiple Modpack Examples (Commented)

Shows flexibility with commented examples:

• Different modpack names
• URL-based modpack (direct download)
• Environment variable substitution for modpack selection

Edge Cases Demonstrated

1. Java Version Selection: Uses ${IMAGE_TAG:-java8} to select Java version
2. URL Modpacks: Shows that modpack can be a URL (direct download)
3. Environment Variable Modpack Selection: ${MODPACK:-default.zip}
4. Read-only Modpack Mount: ./modpacks:/modpacks:ro

Stronghold Implementation Notes

1. Simple Modpack Installation:

   • Minimal UI for quick setup
   • Three input methods:
     • Local file (browse/upload)
     • URL (direct download)
     • Modpack ID (if we integrate with CurseForge API)

2. Java Version Selection:

   • Dropdown for Java version
   • Auto-detect based on Minecraft version
   • Allow manual override

3. Quick Setup Mode:

   • Use this as "Simple" mode template
   • Advanced options hidden by default
   • "Show Advanced" toggle for power users

4. Presets/Saved Configurations:

   • Save common modpack configurations
   • Quick-switch between different modpacks
   • Template library

---

4. docker-compose-magma.yml - Hybrid Mods + Plugins

Source: itzg/docker-minecraft-server/examples/docker-compose-magma.yml

Purpose

Demonstrates Magma server type - a hybrid that supports both Forge mods AND Bukkit/Spigot plugins simultaneously.

Key Features

Hybrid Server Type

• TYPE: MAGMA - Enables both mods and plugins
• VERSION: 1.16.5 - Specific Minecraft version
• image: itzg/minecraft-server:java8 - Java 8 required for this version

Interactive Container

• tty: true - Allocates a pseudo-TTY
• stdin_open: true - Keeps STDIN open
• Allows interactive console access

Edge Cases Demonstrated

1. Hybrid Server Type: Unique server type requiring special handling
2. Version-Specific Java: Older versions require Java 8
3. Interactive Mode: Console access configuration

Stronghold Implementation Notes

1. Server Type Detection:

   • When user selects Magma (or other hybrid types):
     • Show both "Mods" and "Plugins" tabs/sections
     • Support both /mods and /plugins volume mounts
     • Set USES_PLUGINS=true if needed

2. Java Version Compatibility:

   • Map Minecraft versions to required Java versions
   • Warn user if incompatible Java version selected
   • Auto-select appropriate Java version

3. Version-Specific Handling:

   • Some server types only work with specific Minecraft versions
   • Validate compatibility
   • Show warnings/errors

4. Interactive Console:

   • Option to enable interactive console
   • Useful for debugging
   • May not be needed for most users

5. Hybrid Server UI:

   • Special UI mode for hybrid servers
   • Clear separation of mods vs plugins
   • Different management for each type

---

5. docker-compose-rconcmd.yml - Advanced RCON Commands

Source: itzg/docker-minecraft-server/examples/docker-compose-rconcmd.yml

Purpose

Demonstrates advanced RCON usage with:

• Automated command execution at different lifecycle events
• CurseForge API integration for mod installation
• YAML heredoc syntax for multi-line commands

Key Features

RCON Lifecycle Commands

• RCON_CMDS_STARTUP - Commands executed when server starts
• RCON_CMDS_ON_CONNECT - Commands executed when any player connects
• RCON_CMDS_FIRST_CONNECT - Commands executed on first player connection
• RCON_CMDS_LAST_DISCONNECT - Commands executed when last player disconnects

CurseForge API Integration

• CURSEFORGE_FILES - List of CurseForge mod names to auto-install
• CF_API_KEY - CurseForge API key from environment variable
• Requires API key from https://console.curseforge.com/

Advanced YAML Syntax

• Uses |- heredoc to remove leading/trailing newlines
• Multi-line command lists
• Proper formatting for readability

Example Use Case

The example shows:

• Setting game rules on startup
• Creating teams for players
• Using Chunky (world pregeneration) mod
• Giving items to new players
• Managing entities when players disconnect

Edge Cases Demonstrated

1. Environment Variable Security: API keys from .env file (not in compose file)
2. YAML Heredoc Syntax: Proper multi-line string handling
3. CurseForge API Key: Requires external API key management
4. Lifecycle Hooks: Automated server management via RCON

Stronghold Implementation Notes

1. RCON Command Management UI:

   • Tabs/sections for each lifecycle event
   • Multi-line text editor for commands
   • Command validation
   • Preview of commands that will run
   • Test/simulate commands

2. CurseForge API Integration:

   • UI for managing API key (stored securely)
   • Search/browse CurseForge mods by name
   • Auto-install mods via API
   • Dependency resolution

3. Lifecycle Events:

   • Startup: Server initialization commands
   • On Connect: Welcome messages, permissions, etc.
   • First Connect: One-time setup (world generation, etc.)
   • Last Disconnect: Cleanup, save, shutdown tasks

4. Command Editor:

   • Syntax highlighting (Minecraft commands)
   • Auto-completion
   • Validation
   • Help/cheat sheet

5. Security:

   • Secure storage of API keys
   • Environment variable management
   • Never expose secrets in generated files

6. Advanced Features:

   • Schedule commands (cron-like)
   • Conditional commands
   • Command templates
   • Import/export command sets

---

Common Patterns Across Examples

1. Volume Management

• All use named volumes or bind mounts for /data
• Some use read-only mounts for modpacks
• Consistent pattern: volume_name:/data

2. Environment Variables

• EULA: "TRUE" - Always required
• TYPE - Server type
• MEMORY - Memory allocation
• Port mapping: 25565:25565

3. Restart Policies

• always - Production servers
• unless-stopped - Common for game servers
• on-failure - Development/testing

4. Image Tags

• Default: itzg/minecraft-server
• Java version: :java8, :java17, etc.
• Architecture: :arm64, :amd64, etc.
• Environment variable substitution common

Implementation Priorities for Stronghold

Phase 1 (MVP)

• Basic server creation (like curseforge.yml)
• Simple modpack installation
• Essential environment variables

Phase 2 (V1.0)

• Advanced modpack configuration (like atm7.yaml)
• World type selection (like big.yml)
• RCON basic integration

Phase 3 (V1.5)

• Hybrid server support (like magma.yml)
• RCON lifecycle commands (like rconcmd.yml)
• CurseForge API integration

Phase 4 (Future)

• Multi-service orchestration
• Advanced RCON features
• Template library
• Import/export configurations