Provisioning

A POST to /api/servers takes a small JSON body. The panel validates it, allocates a port, and asks Docker to build the container. The HTTP call returns as soon as the container row is persisted; the JVM still has to download the requested version, which is what causes the first start to take 30 to 90 seconds.

POST /api/servers
Authorization: Bearer <jwt>

{
  "name":     "Survival SMP",
  "type":     "PAPER",
  "version":  "1.20.4",
  "memoryMb": 4096,
  "cpuLimit": 2.0
}

Type values map directly to itzg/minecraft-server's TYPE environment variable.

PAPER

Paper. The default. Plugins via Bukkit/Spigot APIs.

FABRIC

Fabric. Mods only, not plugins. Lightweight.

FORGE

Forge. Mods only. Heaviest of the three.

VANILLA

Vanilla Mojang server. No plugins, no mods.

The version string is passed through to itzg/minecraft-server verbatim. Use a literal like 1.20.4, or the strings LATEST / SNAPSHOT. The image resolves these at startup and persists them under /data, so the second start uses the cached jar.

M.A.F Cloud owns a port pool, default 25565 to 25700. The PortAllocator picks the first free integer in that range and writes it to the server row before container creation, then binds the container's internal 25565 to that host port. The pool is configurable via MC_PORT_MIN and MC_PORT_MAX.

A single port also implies a hard ceiling of 136 simultaneous servers per node by default. Multi-node sharding is on the Phase 3 roadmap.

Every container is created with HostConfig.Memory set to the requested memoryMb and NanoCpus set to cpuLimit * 1e9. There is also an admin-side cap, MAX_MEMORY_MB and MAX_CPU, that user requests cannot exceed. The JVM heap inside the container is sized via the image's MEMORY env, set automatically.

Once created, a server moves through CREATED → STARTING → RUNNING → STOPPING → STOPPED based on lifecycle calls. Errors reaching Docker push the row to ERROR. The status visible in the panel is authoritative; container labels (mcplatform.serverId) are the source of truth on the host.