minectl

minectl creates and manages Minecraft servers on 15 cloud providers via declarative YAML manifests.

Creating a Manifest

Every operation starts with a manifest file:

apiVersion: minectl.ediri.io/v1alpha1
kind: MinecraftServer
metadata:
  name: my-minecraft
spec:
  server:
    cloud: hetzner
    region: fsn1
    size: cx21
    ssh:
      port: 22
      publickeyfile: ~/.ssh/id_rsa.pub
      fail2ban:
        bantime: 1000
        maxretry: 3
    port: 25565
  minecraft:
    java:
      openjdk: 21
      xmx: 2G
      xms: 2G
      rcon:
        password: changeme
        port: 25575
        enabled: true
    edition: papermc
    version: "1.21"
    eula: true
    properties: |
      max-players=20
      difficulty=normal
      motd=My Minecraft Server

Choosing an Edition

| Edition | Best for | |---------|----------| | java | Vanilla experience, no mods | | papermc | Performance + plugin support (recommended) | | spigot | Bukkit plugin ecosystem | | craftbukkit | Legacy Bukkit plugins | | fabric | Lightweight mods | | forge | Large mod packs | | purpur | Paper + extra gameplay tweaks | | bedrock | Cross-platform (mobile/console/PC) | | nukkit | Java-based Bedrock server | | powernukkit | Extended Nukkit |

For proxy setups, use kind: MinecraftProxy with editions: bungeecord, waterfall, or velocity.

Edition-Specific Tuning

Different editions need different server.properties and resource allocations. Getting these wrong causes crashes, kicks, or poor performance — this is where most new server admins struggle.

Forge / Fabric (modded servers):

• Set max-tick-time=90000 (or -1 to disable). Modded servers regularly exceed the default 60s watchdog, especially during chunk generation or mod initialization. Leaving the default causes the server to kill itself under normal modded load.
• Set allow-flight=true. Many mods (Botania, Mekanism jetpacks, Elytra mods, etc.) trigger the vanilla flight detection. Without this, modded players get kicked constantly.
• Allocate generous heap: 8G minimum for light mods, 12G+ for heavy packs (100+ mods). Set xms equal to xmx to avoid expensive heap resizing under load.
• Always add volumeSize: 50 (or more). Mod packs, world data with modded chunks, and backups consume significant disk. Running out of disk silently corrupts worlds.
• Upload mods to /minecraft/mods (not /minecraft/plugins).
• Enable monitoring (monitoring.enabled: true) — modded servers are resource-hungry and benefit from Prometheus metrics to catch memory/CPU issues early.

PaperMC / Spigot / CraftBukkit / Purpur (plugin servers):

• Default max-tick-time=60000 is usually fine.
• Keep allow-flight=false unless a specific plugin requires it.
• 2-4G heap is sufficient for up to 20 players with typical plugins.
• Upload plugins to /minecraft/plugins.
• PaperMC is the recommended default — it's the most performant fork and supports all Bukkit/Spigot plugins.

Bedrock / Nukkit / PowerNukkit:

• No java block needed in the manifest (Bedrock is a native binary, not Java-based).
• Default port is 19132 (UDP), not 25565.
• RCON is not available for Bedrock edition.
• Lower resource requirements: 1-2G RAM is typically sufficient.

Instance Sizing Guide

| Use case | Players | Recommended RAM | Example sizes | |----------|---------|----------------|---------------| | Vanilla / Paper (casual) | 1-10 | 2-4 GB | Hetzner cx21, DO s-2vcpu-4gb | | Paper with plugins | 10-20 | 4-8 GB | Hetzner cpx31, DO s-4vcpu-8gb, AWS t3.large | | Forge/Fabric (light mods) | 1-10 | 8 GB | AWS t3.xlarge, Hetzner cpx41 | | Forge/Fabric (heavy mods) | 5-15 | 16 GB+ | AWS m5.xlarge, Hetzner cpx51 | | Proxy (BungeeCord/Velocity) | N/A | 1-2 GB | Smallest available |

When using spot instances (spot: true), prefer regions with large capacity pools (e.g., us-east-1 for AWS) to minimize interruption risk. Always warn users that spot instances can be terminated with 2 minutes notice — world backups are essential.

Security Recommendations

Always include these in every manifest:

• fail2ban block under SSH config (prevents brute-force attacks)
• Strong RCON password (never deploy with "changeme")
• Consider white-list=true and enforce-whitelist=true for private servers
• online-mode=true to verify player accounts (prevents unauthorized access)

Optional Features

Add to spec.server:

• spot: true - Spot/preemptible instances (AWS, Azure, GCE) to save cost
• arm: true - ARM instances (Hetzner, AWS, GCE)
• volumeSize: 50 - Extra storage in GB

Add to spec:

• monitoring: { enabled: true } - Prometheus + Node Exporter

Naming Rules

• metadata.name must be lowercase alphanumeric with hyphens only
• SSH port must be 22 or between 1024-65535
• eula must be true

Server Lifecycle

# Generate a manifest interactively
minectl wizard

# Create a server (waits for startup by default)
minectl create -f server.yaml

# Verify the server is running after creation
minectl list -p hetzner -r fsn1
# Expected: server appears with a valid ID and status. If absent, check credentials and quota.

# List running servers
minectl list -p hetzner -r fsn1

# Connect via RCON for remote commands
minectl rcon -f server.yaml --id <server-id>

# Upload a plugin
minectl plugins -f server.yaml --id <server-id> -k ~/.ssh/id_rsa \
  -p myplugin.jar -d /minecraft/plugins

# Update Minecraft version (edit version in manifest first)
minectl update -f server.yaml --id <server-id> -k ~/.ssh/id_rsa

# Delete the server
minectl delete -f server.yaml --id <server-id> -y

Error Recovery

| Symptom | Likely cause | Action | |---------|--------------|--------| | create exits without a server ID | Authentication failure | Verify provider environment variables are exported (see references/cloud-providers.md) | | create fails with quota/limit error | Cloud account quota exceeded | Switch region, use a smaller size, or request a quota increase from the provider | | create succeeds but server absent from list | Wrong region or provider flag | Re-run minectl list with the exact -p and -r values from the manifest | | Plugin upload fails | SSH key mismatch | Confirm -k points to the private key matching spec.server.ssh.publickeyfile | | RCON connection refused | RCON not enabled or wrong port | Ensure rcon.enabled: true and the port in the manifest matches rcon.port |

Cloud Provider Selection

When helping a user choose a provider, consider:

• Budget: Civo, Hetzner, and DigitalOcean are cheapest. Use spot: true on AWS/Azure/GCE for savings.
• Region needs: Check references/cloud-providers.md for available regions.
• Local testing: Use multipass for local VMs with no cloud account needed.

Each provider requires specific environment variables for authentication. See references/cloud-providers.md for the full list.

References

• Cloud providers, credentials, and sizes: references/cloud-providers.md
• Full manifest schema: references/manifest-schema.md
• CLI command flags and details: references/cli-commands.md