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 · 2025-10-31 11:50:31 -07:00 · c31e48e2b1
commit c31e48e2b1
25 changed files with 3382 additions and 0 deletions
--- a/references/itzg-projects.md
+++ b/references/itzg-projects.md
@ -0,0 +1,283 @@
+# 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](https://docker-minecraft-server.readthedocs.io/en/latest/mods-and-plugins/)
+
+#### 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:
+     ```yaml
+     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
+