dockercraft/README.md

# Dockercraft

A Docker image for running Minecraft servers with support for multiple loaders.

## Features

- **Multi-loader support** — Vanilla, Paper, Fabric, Forge, NeoForge, and Bedrock
- **Auto-detection** — Java version and loader versions are auto-detected from Mojang manifests
- **Persistent data** — Server files, worlds, and Java installations are stored in `/data`
- **Health checks** — Built-in container health monitoring
- **Flexible Java** — Pin or auto-detect Java version (Temurin, Zulu, GraalVM, etc.)
- **Bedrock support** — Native Bedrock Dedicated Server without Java

## Quick Start

```yaml
services:
  minecraft:
    image: git.jeremymcclure.com/jeremy/dockercraft:latest
    container_name: minecraft
    stdin_open: true
    tty: true
    environment:
      - EULA=true
      - MC_VERSION=1.21.1
      - MC_LOADER=neoforge
      - MC_LOADER_VERSION=21.1.185
      - JAVA_VERSION=temurin@21
      - XMS=2G
      - XMX=4G
      - PUID=1000
      - PGID=1000
    volumes:
      - ./data:/data
    ports:
      - 25565:25565
    restart: unless-stopped
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `EULA` | — | **Required.** Set to `true` to accept the Minecraft EULA |
| `MC_VERSION` | — | Minecraft version (e.g., `1.21.1`). Required for Java loaders; auto-detected for Bedrock |
| `MC_LOADER` | — | **Required.** Server loader: `vanilla`, `paper`, `fabric`, `forge`, `neoforge`, or `bedrock` |
| `MC_LOADER_VERSION` | — | Fallback version for any loader |
| `FABRIC_LOADER_VERSION` | `$MC_LOADER_VERSION` | Fabric loader version |
| `FORGE_VERSION` | `$MC_LOADER_VERSION` | Forge version (e.g., `52.1.14`) |
| `NEOFORGE_VERSION` | `$MC_LOADER_VERSION` | NeoForge version (e.g., `21.1.185`) |
| `PAPER_BUILD` | latest | Paper build number (auto-detects latest stable if unset) |
| `JAVA_VERSION` | auto-detected | Java version (via Jabba, e.g., `temurin@21`, `zulu@17`). Auto-detects from Mojang manifest if unset: 1.20.5+→21, 1.17-1.20.4→17, 1.17→16, pre-1.17→8 |
| `JAR` | `server.jar` | Server jar filename |
| `XMS` | `2G` | Initial Java heap size |
| `XMX` | `4G` | Maximum Java heap size |
| `ADD_ARGS` | — | Additional Java arguments |
| `PUID` | `1000` | User ID for /data ownership |
| `PGID` | `1000` | Group ID for /data ownership |

## Supported Loaders

| Loader | Description | Ports |
|---|---|---|
| **Vanilla** | Official Mojang server | TCP 25565 |
| **Paper** | High-performance fork from papermc.io | TCP 25565 |
| **Fabric** | Lightweight mod loader via fabricmc.net | TCP 25565 |
| **Forge** | Mod loader via minecraftforge.net | TCP 25565 |
| **NeoForge** | Community fork of Forge via neoforged.net | TCP 25565 |
| **Bedrock** | Official Bedrock Dedicated Server (no Java) | UDP 19132 |

## Volumes

- `/data` — Persists server data, worlds, config, and Java installations

## Loader-Specific Examples

### Paper

```yaml
environment:
  - EULA=true
  - MC_VERSION=1.21.1
  - MC_LOADER=paper
  - PAPER_BUILD=132  # optional, auto-detects latest stable
```

### Fabric

```yaml
environment:
  - EULA=true
  - MC_VERSION=1.21.1
  - MC_LOADER=fabric
  - FABRIC_LOADER_VERSION=0.19.3  # optional, auto-detects latest
```

### Forge / NeoForge

```yaml
environment:
  - EULA=true
  - MC_VERSION=1.21.1
  - MC_LOADER=forge        # or neoforge
  - FORGE_VERSION=52.1.14  # optional, auto-detects latest
```

### Bedrock

```yaml
environment:
  - EULA=true
  - MC_LOADER=bedrock
  - MC_VERSION=1.21.50     # Bedrock server version
ports:
  - 19132:19132/udp
  - 19133:19133/udp        # IPv6 (optional)
```

## Java Version Management

Java is managed via [Jabba](https://github.com/Jabba-Team/jabba). Java installations are cached in `/data/java/` so they persist across container restarts.

Supported distributions include `temurin`, `zulu`, `adopt`, `openjdk`, `graalvm`, and more. Use the format `distribution@version`:

```yaml
- JAVA_VERSION=temurin@21
- JAVA_VERSION=zulu@17
- JAVA_VERSION=graalvm@21
```

If unset, the Java version is auto-detected from the Mojang version manifest based on `MC_VERSION`.

## Health Checks

The container includes a built-in health check:

- **Java servers** — TCP check on port 25565
- **Bedrock servers** — UDP check on port 19132

The health check has a 2-minute start period to allow the server time to initialize.

## Troubleshooting

### Server fails to start

Check the container logs:

```bash
docker logs minecraft
```

### EULA not accepted

If you see an EULA error, make sure `EULA=true` is set in your environment variables.

### Java not found

If Java installation fails, check that the `/data` volume is writable. Java is installed to `/data/java/` on first run.

### Wrong UID/GID

If you get permission errors on server files, check that `PUID` and `PGID` match your host user:

```bash
id -u  # your UID
id -g  # your GID
```

### Port conflicts

Make sure the Minecraft port (25565 for Java, 19132 for Bedrock) is not already in use:

```bash
ss -tlnp | grep 25565
```

## Development

### Building locally

```bash
docker build -t dockercraft:local .
```

### Running tests

**API tests** — verify all external APIs are healthy and returning correct data (no Docker needed):

```bash
# All suites
./tests/run_tests.sh

# Specific MC version
./tests/run_tests.sh -m 1.21.1

# Specific suites only
./tests/run_tests.sh -s mojang,fabric,neoforge
```

**Integration tests** — spin up Docker containers and verify full download → install → server start:

```bash
# Test all loaders
./tests/integration.sh

# Test a specific loader
./tests/integration.sh -m 1.21.1 -l fabric

# Custom timeout
./tests/integration.sh -t 300
```

## License

See [LICENSE](LICENSE) for details.