{"id":38542401,"url":"https://github.com/secondfry/docker-minecraft","last_synced_at":"2026-01-17T07:12:28.732Z","repository":{"id":323034836,"uuid":"1091873133","full_name":"secondfry/docker-minecraft","owner":"secondfry","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-07T18:50:01.000Z","size":109,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-07T19:04:53.187Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/secondfry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-07T16:40:28.000Z","updated_at":"2025-11-07T18:50:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/secondfry/docker-minecraft","commit_stats":null,"previous_names":["secondfry/docker-minecraft"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/secondfry/docker-minecraft","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secondfry%2Fdocker-minecraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secondfry%2Fdocker-minecraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secondfry%2Fdocker-minecraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secondfry%2Fdocker-minecraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/secondfry","download_url":"https://codeload.github.com/secondfry/docker-minecraft/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secondfry%2Fdocker-minecraft/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28503178,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T07:12:28.073Z","updated_at":"2026-01-17T07:12:28.723Z","avatar_url":"https://github.com/secondfry.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker Minecraft Server\n\nDockerized Minecraft server with **automatic RAM detection** and Aikar's optimized JVM flags.\n\nFeatures Eclipse Temurin 21 JRE on Alpine Linux with intelligent memory management.\n\n## Why This Exists\n\nMost Minecraft Docker solutions require manual memory configuration:\n\n```bash\n# itzg/docker-minecraft-server\ndocker run -e MEMORY=8G ...\n\n# marctv/minecraft-papermc-server\ndocker run -e MAX_RAM=8G ...\n```\n\n**But how do you calculate the right value?** Too little causes crashes. Too much causes garbage collection lag.\n\n**secondfry/docker-minecraft** solves this through:\n\n- ✅ **Automatic RAM detection** - reads system memory, calculates optimal heap\n- ✅ **Intelligent overhead** - reserves 1-2GB for OS based on total RAM\n- ✅ **Reasonable defaults** - caps heap at 12GB to avoid GC issues on large systems\n- ✅ **Adaptive GC tuning** - adjusts G1GC parameters based on allocated heap size\n- ✅ **Trivial migration** - copy existing servers without file preservation\n\nJust run `docker-compose up -d` and it works.\n\n## Comparison with Alternatives\n\n| Feature | **secondfry** | itzg | marctv | Pterodactyl |\n|---------|---------------|------|--------|-------------|\n| **RAM Configuration** | ✅ Automatic | ❌ Manual | ❌ Manual | ❌ Web UI |\n| **GC Tuning** | ✅ Adaptive | ❌ Static | ❌ Static | ❌ Static |\n| **Server Migration** | ✅ Trivial | ⚠️ Complex | ⚠️ Manual | ⚠️ Import |\n| **Image Size** | 100MB Alpine | 793MB Ubuntu | 200MB | N/A |\n| **Setup Complexity** | 3 commands | Moderate | Simple | Complex |\n| **Auto Downloads** | ❌ Manual JAR | ✅ Auto | ✅ Auto | ✅ Auto |\n| **Web Interface** | ❌ None | ❌ None | ❌ None | ✅ Full UI |\n| **Best For** | Dev UX | Features | ARM/Pi | Enterprise |\n\n### When to Use Alternatives\n\n**Use [itzg/docker-minecraft-server](https://github.com/itzg/docker-minecraft-server) if you need:**\n- Automatic mod/plugin downloads\n- 100+ configuration options\n- Multi-version server management\n- Established community (10k+ stars)\n\n**Use [Pterodactyl](https://pterodactyl.io/) if you need:**\n- Multi-server management\n- User access controls\n- Web-based administration\n- Enterprise features\n\n**Use [marctv/minecraft-papermc-server](https://github.com/marctv/minecraft-papermc-server) if you:**\n- Only run PaperMC servers\n- Prefer simplicity over flexibility\n- Run on ARM/Raspberry Pi\n\n**Use secondfry/docker-minecraft if you value:**\n- Zero-configuration memory optimization\n- Clean architecture and minimal footprint\n- Easy migration of existing servers\n- Smart defaults over config files\n\n## Prerequisites\n\n- Docker and Docker Compose ([installation instructions](https://docs.docker.com/engine/install/))\n- Your Minecraft server JAR file (Fabric, Paper, Vanilla, etc.)\n- Minimum 6GB RAM recommended (8GB+ preferred)\n\n## Quick Start\n\n### New Server\n\n1. **Clone or download** this repository:\n   ```bash\n   git clone https://github.com/secondfry/docker-minecraft.git\n   cd docker-minecraft\n   # Or download and unzip the repository\n   ```\n\n2. **Place your server JAR** in the `server/` directory:\n   ```bash\n   cd server\n   # Example for Fabric:\n   wget https://meta.fabricmc.net/v2/versions/loader/1.21.8/0.17.0/1.1.0/server/jar \\\n     -O fabric-server-mc.1.21.8-loader.0.17.0-launcher.1.1.0.jar\n   cd ..\n   ```\n\n3. **Start the server**:\n   ```bash\n   docker-compose up -d\n   ```\n\n4. **View logs**:\n   ```bash\n   docker-compose logs -f\n   ```\n\n### Existing Server (Already Have a Server Folder)\n\n1. **Clone or download** this repository:\n   ```bash\n   git clone https://github.com/secondfry/docker-minecraft.git\n   cd docker-minecraft\n   ```\n\n2. **Move or copy your existing server** into the `server/` directory:\n   ```bash\n   # Move your server directory (replaces empty ./server/)\n   mv /path/to/your/existing/server/ ./server/\n\n   # Or copy if you want to keep the original\n   cp -a /path/to/your/existing/server/. ./server/\n   ```\n\n3. **Start the server**:\n   ```bash\n   docker-compose up -d\n   ```\n\n### From Tarball (Server Backup)\n\n1. **Clone or download** this repository:\n   ```bash\n   git clone https://github.com/secondfry/docker-minecraft.git\n   cd docker-minecraft\n   ```\n\n2. **Extract your server tarball** into the `server/` directory:\n   ```bash\n   # Move tarball to repo root, then extract\n   mv /path/to/server-backup.tar.gz ./\n   tar -xzf ./server-backup.tar.gz -C ./server/\n   ```\n\n3. **Start the server**:\n   ```bash\n   docker-compose up -d\n   ```\n\n---\n\n**That's it!** The server automatically detects available RAM and configures itself with Aikar's optimized flags.\n\n**Note**: The `secondfry-start.sh` script is automatically injected into the server at runtime. You never need to worry about preserving it when copying or extracting server files - it's always provided fresh from the repository!\n\n## Memory Management\n\n### Automatic Detection (Default)\n\nThe server **automatically detects available RAM** and configures JVM heap size with proper overhead:\n\n| Total RAM | Heap Allocation | OS Overhead | Notes |\n|-----------|-----------------|-------------|-------|\n| 6-7 GB    | Total - 1 GB    | 1 GB        | Minimum viable |\n| 8-15 GB   | Total - 2 GB    | 2 GB        | Recommended |\n| 16+ GB    | Total - 2 GB    | 2 GB        | **Capped at 12GB** |\n\n**Example**: On an 8GB system → 6GB heap. On a 32GB system → 12GB heap (capped).\n\n**Why the 12GB cap?** Aikar recommends 6-10GB for most servers. Research shows that allocating more than 12GB rarely improves performance and can cause severe garbage collection pauses (2-5 second freezes). See the [official Aikar's flags documentation](https://docs.papermc.io/paper/aikars-flags) for details.\n\n### Manual Override\n\n#### Option 1: Using .env File (Best Practice)\n\nCreate a `.env` file from the example:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and uncomment/set `MEMORY_GB`:\n\n```bash\nMEMORY_GB=6  # Force specific heap size\nTZ=UTC\n```\n\nThen restart: `docker-compose up -d`\n\n**Why .env file?** Best practice for configuration management - keeps sensitive values out of docker-compose.yml and version control.\n\n#### Option 2: Environment Variable in docker-compose.yml\n\nEdit `docker-compose.yml` and uncomment the `MEMORY_GB` line:\n\n```yaml\nenvironment:\n  - TZ=UTC\n  - MEMORY_GB=6  # Force specific heap size (in GB, without 'G' suffix)\n```\n\nThen restart: `docker-compose up -d`\n\n#### Option 3: Override Maximum Cap (Heavy Modpacks)\n\nIf you have a **heavily modded server** that genuinely needs more than 12GB, you can override the cap:\n\n```yaml\nenvironment:\n  - TZ=UTC\n  - MAX_MEMORY_GB=16  # Increase cap from 12GB to 16GB\n```\n\nOr in `.env`:\n```bash\nMAX_MEMORY_GB=16\n```\n\n**Warning**: Only increase this if you have a specific need (e.g., 200+ mods). Aikar recommends 6-10GB for most servers. Over-allocation causes performance issues, not improvements.\n\n### Docker Memory Limits (Optional)\n\n**By default, Docker containers can use ALL host RAM** without limits. This is the recommended configuration for dedicated Minecraft servers, as the startup script will automatically detect all available RAM and configure itself optimally.\n\nThe memory limits in `docker-compose.yml` are **commented out by default**.\n\n#### When to Use Memory Limits\n\nOnly uncomment and set memory limits if you need to:\n1. **Multi-tenant hosts** - Prevent one container from using all RAM and starving other services\n2. **Shared hosting** - Enforce resource quotas per customer/container\n3. **Testing** - Simulate lower-memory environments\n\n#### How Docker Memory Works\n\n```yaml\n# Uncomment to enable limits:\n# deploy:\n#   resources:\n#     limits:\n#       memory: 8G   # Hard limit - container killed if exceeded\n#     reservations:\n#       memory: 6G   # Soft limit - guaranteed minimum\n```\n\n**Important**: If you set a memory limit, the auto-detection script will detect ONLY that limit, not the host's total RAM.\n\n**Example**:\n- Host has 16GB RAM\n- Set `memory: 8G` limit\n- Script detects 8GB and allocates ~6GB heap (leaving 2GB overhead)\n- Container cannot use the other 8GB even though it's available on the host\n\n**Recommendation**: Leave limits commented out unless you have a specific need.\n\n## Project Structure\n\n```\n.\n├── docker/                  # Docker build context (isolated from server data)\n│   ├── Dockerfile          # Container image definition\n│   └── .dockerignore       # Files to exclude from build\n├── server/                  # YOUR MINECRAFT SERVER GOES HERE\n│   ├── *.jar               # Your server JAR (place here)\n│   ├── world/              # World data (generated)\n│   ├── mods/               # Your mods (if using Fabric/Forge)\n│   ├── plugins/            # Your plugins (if using Paper/Spigot)\n│   ├── server.properties   # Server config (generated)\n│   └── ...                 # All other server files\n├── secondfry-start.sh      # Startup script (auto-injected into container)\n├── docker-compose.yml      # Service orchestration\n├── .env.example            # Environment variable template\n└── README.md               # This file\n```\n\n### Why This Structure?\n\n- **`server/` directory**: All your Minecraft files in one place\n  - Easy to understand: \"put your server here\"\n  - Clean separation from Docker infrastructure\n  - Easy to backup: just tar the `server/` directory\n  - Easy to migrate: copy/move existing servers without worry\n\n- **`secondfry-start.sh` overlay**: Automatically injected at runtime\n  - Stored at repository root, not in server/\n  - Never gets overwritten by your server files\n  - Always up-to-date from repository\n  - You can destructively copy/move/extract servers safely\n\n- **`docker/` subdirectory**: Docker build files isolated\n  - Faster builds: only sends Docker files to build context\n  - No pollution: world data and logs stay out of Docker layers\n  - Clean: infrastructure separate from application data\n\nThis structure makes it trivial to dockerize existing servers - no file preservation needed!\n\n## Configuration\n\n### Ports\n\nDefault configuration:\n- `25565` - Minecraft server (exposed)\n- `25575` - RCON remote console (**disabled by default** for security)\n\n#### Enabling RCON\n\nRCON (Remote Console) is disabled by default as it can be a security risk if exposed unintentionally.\n\n**To enable RCON:**\n\n1. Uncomment the RCON port in `docker-compose.yml`:\n   ```yaml\n   ports:\n     - \"25565:25565\"\n     - \"25575:25575\"  # Uncomment this line\n   ```\n\n2. Configure RCON in `server.properties`:\n   ```properties\n   enable-rcon=true\n   rcon.port=25575\n   rcon.password=your-secure-password-here\n   ```\n\n3. Restart: `docker-compose restart`\n\n**Security Warning**: Only expose RCON if you need it, and always use a strong password. Consider using SSH tunneling instead of exposing RCON publicly.\n\n### Server JAR Auto-Detection\n\nThe startup script automatically finds your server JAR in this priority order:\n1. `fabric-server-mc.*.jar`\n2. `paper-*.jar`\n3. `server.jar`\n4. First `*.jar` file found\n\n**No manual configuration needed!** Just drop your JAR in the root directory.\n\n### File Permissions and Volume Mounts\n\nThe container runs as user `minecraft` (UID 1000, GID 1000) for security. Since the current directory is mounted as a volume, file permissions are inherited from your host system.\n\n#### Permission Requirements\n\nFiles in the mounted directory must be **readable by UID 1000**. There are three approaches:\n\n**Option 1: Match Host User to Container (Recommended)**\n\nIf your host user is already UID 1000, no action needed:\n```bash\nid -u  # Check your UID\n# If 1000, you're good!\n```\n\n**Option 2: Fix Permissions on Host**\n\nMake files readable/writable by UID 1000:\n```bash\n# Change ownership (if you have sudo)\nsudo chown -R 1000:1000 .\n\n# Or make files world-readable (less secure)\nchmod -R 755 .\n```\n\n**Option 3: Run Container as Your Host User**\n\nAdd to `docker-compose.yml`:\n```yaml\nservices:\n  minecraft:\n    user: \"${UID}:${GID}\"  # Runs as your host user\n    # ... rest of config\n```\n\nThen start with:\n```bash\nUID=$(id -u) GID=$(id -g) docker-compose up -d\n```\n\n#### Troubleshooting Permission Errors\n\nIf you see permission denied errors:\n```bash\n# Check file ownership\nls -la\n\n# Fix ownership\nsudo chown -R 1000:1000 .\n\n# Or run as your user (Option 3 above)\n```\n\n**Note**: The Dockerfile intentionally does NOT include `chown` commands because volume mounts override image layers. Permissions must be handled on the host or via runtime configuration.\n\n## JVM Optimization - Aikar's Flags\n\nThis setup uses **Aikar's flags**, the industry-standard JVM optimizations for Minecraft servers.\n\n### Key Optimizations\n\n- **G1GC** garbage collector for low-latency pauses (targets \u003c200ms)\n- **Adaptive G1 tuning** based on heap size:\n  - ≤12GB: 30-40% new generation\n  - \u003e12GB: 40-50% new generation + larger heap regions\n- **MaxTenuringThreshold=1**: Prevents short-lived objects from aging unnecessarily\n- **DisableExplicitGC**: Blocks plugins from triggering full GC lag spikes\n- **Optimized for Minecraft's ~800MB/s memory allocation rate**\n\n### GC Logging\n\nGarbage collection logs are automatically saved to `logs/gc.log` with rotation (5 files × 1MB each).\n\n**Reference**: [PaperMC - Aikar's Flags](https://docs.papermc.io/paper/aikars-flags/)\n\n## Docker Commands\n\n```bash\n# Start server (detached)\ndocker-compose up -d\n\n# Stop server gracefully\ndocker-compose down\n\n# Restart server\ndocker-compose restart\n\n# View logs (follow mode)\ndocker-compose logs -f\n\n# View logs (last 100 lines)\ndocker-compose logs --tail=100\n\n# Access console (interactive)\ndocker attach minecraft-server\n# Press Ctrl+P, Ctrl+Q to detach without stopping\n\n# Rebuild after Dockerfile changes\ndocker-compose up -d --build\n\n# View detected RAM allocation\ndocker-compose logs | grep \"Detected\"\n```\n\n## Technical Details\n\n| Component | Value |\n|-----------|-------|\n| **Base Image** | Eclipse Temurin 21 JRE on Alpine Linux |\n| **Java Distribution** | Eclipse Temurin (recommended for MC servers) |\n| **User** | Non-root `minecraft` user (UID 1000) |\n| **Volume Mount** | Current directory → `/server` (read/write) |\n| **Auto-restart** | Enabled (unless manually stopped) |\n| **Healthcheck** | TCP port 25565 check every 30s |\n| **EULA** | Auto-accepted on first run |\n\n## Advanced Configuration\n\n### Changing Java Flags\n\nIf you need to customize JVM flags beyond Aikar's recommendations, edit `secondfry-start.sh` lines 103-128.\n\n**Warning**: Only modify if you understand JVM tuning. Aikar's flags are optimal for 99% of servers.\n\n### Multiple Server Instances\n\nTo run multiple servers on one host:\n\n1. Create separate directories for each server\n2. Modify `container_name` and `ports` in each `docker-compose.yml`:\n   ```yaml\n   container_name: minecraft-server-survival\n   ports:\n     - \"25565:25565\"  # Server 1\n\n   container_name: minecraft-server-creative\n   ports:\n     - \"25566:25565\"  # Server 2 (different host port)\n   ```\n\n### Using External Database\n\nIf using a plugin that requires a database (like CoreProtect), add a database service to `docker-compose.yml`:\n\n```yaml\nservices:\n  minecraft:\n    # ... existing config ...\n    depends_on:\n      - database\n\n  database:\n    image: mariadb:latest\n    environment:\n      MYSQL_ROOT_PASSWORD: changeme\n      MYSQL_DATABASE: minecraft\n    volumes:\n      - ./data/mysql:/var/lib/mysql\n```\n\n## Troubleshooting\n\n### Server won't start\n\n**Check logs first:**\n```bash\ndocker-compose logs\n```\n\n**Common issues:**\n- No JAR file found → Place server JAR in root directory\n- Port already in use → Change port in `docker-compose.yml`\n- Permission denied → Run `chmod +x secondfry-start.sh`\n\n### Out of Memory Errors\n\n**Symptoms**: `OutOfMemoryError` in logs, server crashes\n\n**Solutions**:\n1. Check detected RAM: `docker-compose logs | grep \"Detected\"`\n2. Increase Docker memory limits in `docker-compose.yml`\n3. Ensure you're leaving 1-2GB overhead for the OS\n4. For 8GB host, use: `limits: memory: 8G` (will allocate ~6GB heap)\n\n### Performance Issues\n\n**Check GC logs:**\n```bash\ncat logs/gc.log\n```\n\n**If GC pauses are \u003e200ms:**\n- Increase heap size (more RAM)\n- Reduce view distance\n- Use server optimization plugins (Lithium, Starlight, FerriteCore)\n- Consider upgrading to 16GB+ RAM\n\n### Permission Issues\n\nThe container runs as UID 1000. If you get permission errors:\n\n```bash\n# Fix ownership\nsudo chown -R 1000:1000 .\n\n# Or make files readable\nchmod -R 755 .\n```\n\n### Cannot Connect to Server\n\n1. **Check server is running**: `docker ps`\n2. **Check port mapping**: `docker-compose logs | grep \"25565\"`\n3. **Check firewall**: Allow port 25565 TCP\n4. **Check server.properties**: `server-ip=0.0.0.0` (binds to all interfaces)\n\n## Performance Tips\n\n1. **Preallocate world**: Use a world pregeneration plugin to avoid generation lag\n2. **Optimize view distance**: 6-8 chunks is usually sufficient\n3. **Use Paper/Fabric**: Better performance than Vanilla\n4. **Install optimization mods**: Lithium, Starlight, Sodium (client)\n5. **Monitor with GC logs**: Check `logs/gc.log` for pause times\n\n## Backup Strategy\n\nCreate a backup script:\n\n```bash\n#!/bin/bash\n# backup.sh\ndocker-compose exec minecraft rcon-cli save-off\ndocker-compose exec minecraft rcon-cli save-all\ntar -czf \"backup-$(date +%Y%m%d-%H%M%S).tar.gz\" world world_nether world_the_end\ndocker-compose exec minecraft rcon-cli save-on\n```\n\nOr use a backup plugin like [DiscordSRV Backup](https://www.spigotmc.org/resources/discordsrv.18494/).\n\n## Updating Server\n\n1. **Stop server**: `docker-compose down`\n2. **Backup world**: `tar -czf backup.tar.gz world/`\n3. **Replace JAR**: Download new server JAR\n4. **Start server**: `docker-compose up -d`\n5. **Check logs**: `docker-compose logs -f`\n\n## Security Considerations\n\n- Container runs as non-root user (UID 1000)\n- Alpine Linux base for minimal attack surface\n- No unnecessary packages installed\n- Automatic EULA acceptance (ensure you agree to Minecraft EULA)\n- Consider using a firewall (iptables/ufw) to restrict port access\n\n## Contributing\n\nFound an issue or have a suggestion? Please open an issue or pull request.\n\n## License\n\nThis Docker configuration is provided as-is under the MIT License. Minecraft server software has its own licenses and EULA.\n\n## Additional Resources\n\n- [PaperMC Documentation](https://docs.papermc.io/)\n- [Fabric Wiki](https://fabricmc.net/wiki/)\n- [Minecraft Wiki - Server](https://minecraft.wiki/w/Server)\n- [Aikar's Flags Explained](https://docs.papermc.io/paper/aikars-flags/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecondfry%2Fdocker-minecraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsecondfry%2Fdocker-minecraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecondfry%2Fdocker-minecraft/lists"}