robojerk/stronghold
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
stronghold/references/examples/EXAMPLES-ANALYSIS.md
robojerk c31e48e2b1 Proof of concept: Container management with FastAPI backend 
- FastAPI backend with REST API endpoints
- SQLite database for container metadata
- Docker/Podman SDK integration with label filtering
- Frontend: Server creation form and management page
- Container operations: create, list, start, stop, delete
- Single container deployment (nginx + Python + supervisor)
- Support for Docker and Podman (rootless)
- Volume management for persistent data
2025-10-31 11:50:31 -07:00

370 lines
12 KiB
Markdown
Raw Blame History

# 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](https://github.com/itzg/docker-minecraft-server/blob/master/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](https://github.com/itzg/docker-minecraft-server/blob/master/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](https://github.com/itzg/docker-minecraft-server/blob/master/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](https://github.com/itzg/docker-minecraft-server/blob/master/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](https://github.com/itzg/docker-minecraft-server/blob/master/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
Reference in a new issue View git blame Copy permalink