Skip to content
/ minectl Public

minectl ๐Ÿ—บ is a cli for creating Minecraft server on different cloud provider.

License

Notifications You must be signed in to change notification settings

dirien/minectl

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

New - 1.21 support

minectl ๐Ÿ—บ๏ธ๏ธ supports the Minecraft 1.21 version

logo

minectl ๐Ÿ—บ

minectl

Minecraft Go Ubuntu Prometheus Scaleway DigitalOcean Civo Akamai Connected Cloud Hetzner OVH Equinix Metal Google Cloud Vultr Microsoft Azure Oracle Cloud Infrastructure Ionos Cloud Amazon AWS VEXXHOST Multipass Exoscale Fuga Cloud

Go Reference Go Report Card

GitHub Workflow Status (main) GitHub Quality Gate Status OpenSSF Scorecard CII Best Practices

GitHub release (latest by date)

Artifact Hub

minectl ๐Ÿ—บ๏ธ๏ธ is a cli for creating Minecraft server on different cloud provider.

It is a private side project of me, to learn more about Go, CLI and multi-cloud environments.

Supported cloud provider โ˜

TL;DR ๐Ÿš€

Installing minectl ๐Ÿ—บ

Download the latest binary executable for your operating system.

Installation Script
curl -sLS https://get.minectl.dev | sudo sh

or without sudo

curl -sLS https://get.minectl.dev | sh

This will install the minectl ๐Ÿ—บ to ~/.minctl/ and add it to your path. When it canโ€™t automatically add minectl ๐Ÿ—บ to your path, you will be prompted to add it manually.

Mac OS X
  • Use Homebrew
    brew tap dirien/homebrew-dirien
    brew install minectl
Windows
  • Use Powershell

    #Create directory
    New-Item -Path "$HOME/minectl/cli" -Type Directory
    # Download file
    Start-BitsTransfer -Source https://github.com/dirien/minectl/releases/download/v0.7.0/minectl_0.7.0_windows_amd64.zip -Destination "$HOME/minectl/cli/."
    # Uncompress zip file
    Expand-Archive $HOME/minectl/cli/*.zip -DestinationPath C:\Users\Developer\minectl\cli\.
    #Add to Windows `Environment Variables`
    [Environment]::SetEnvironmentVariable("Path",$($env:Path + ";$Home\minectl\cli"),'User')
Source install

You need to have go installed, and need to checkout the Git repository and run the following commands:

make build

This will output the minectl ๐Ÿ—บ binary in the bin/minectl folder.

Architectural overview

You can find a high level architectural overview here

Usage โš™

Access Token ๐Ÿ”‘

minectl ๐Ÿ—บ is completely build on zero-trust. It does not save any API Tokens, instead it looks them up in the ENV variables.

Civo
export CIVO_TOKEN=xx
Digital Ocean
export DIGITALOCEAN_TOKEN=xxx
Scaleway
export ACCESS_KEY=xxx
export SECRET_KEY=yyy
export ORGANISATION_ID=zzz
Hetzner
export HCLOUD_TOKEN=yyyy
Akamai Connected Cloud
export LINODE_TOKEN=xxxx

OVHCloud

You need to create API keys per endpoint. For an overview of available endpoint check supported-apis documentation

For, example, Europe visit https://eu.api.ovh.com/createToken to create your API keys for minectl ๐Ÿ—บ

img.png

For the proper rights choose all HTTP Verbs (GET,PUT,DELETE, POST), and we need only the /cloud/* API.

export OVH_ENDPOINT=ovh-eu
export APPLICATION_KEY=xxx
export APPLICATION_SECRET=yyy
export CONSUMER_KEY=zzz
export SERVICENAME=<projectid>

Equinix Metal

export METAL_AUTH_TOKEN=xxx
export EQUINIX_PROJECT=yyy

Google Compute Engine (GCE)

export GCE_KEY=<pathto>/key.json

See Getting Started - GCE edition for details on how to create a GCP service account for minectl ๐Ÿ—บ`

Vultr

export VULTR_API_KEY=xxx

Azure

Please select a Hypervisor Generation '2' VM Size. As minectl ๐Ÿ—บ use only Hypervisor Generation 2 Image

You need to set the subscription Id via the AZURE_SUBSCRIPTION_ID environment variable.

AZURE_SUBSCRIPTION_ID=xxx
Option 1: Define environment variables
Service principal with a secret
export AZURE_TENANT_ID="<active_directory_tenant_id"
export AZURE_CLIENT_ID="<service_principal_appid>"
export AZURE_CLIENT_SECRET="<service_principal_password>"
Service principal with certificate
export AZURE_TENANT_ID="<active_directory_tenant_id>"
export AZURE_CLIENT_ID="<service_principal_appid>"
export AZURE_CLIENT_CERTIFICATE_PATH="<azure_client_certificate_path>"
Username and password
export AZURE_CLIENT_ID="<service_principal_appid>"
export AZURE_USERNAME="<azure_username>"
export AZURE_PASSWORD="<azure_user_password>"
Option 2: Use a managed identity
export AZURE_CLIENT_ID="<user_assigned_managed_identity_client_id>"
Option 3: Sign in with Azure CLI
az login

See Azure authentication with the Azure SDK for Go for details

Oracle Cloud Infrastructure

To keep things simple for the moment, the authentication uses OCI config file. And there the default.

Example:

cat  /Users/user/.oci/config

[DEFAULT]
user=<ocid>
fingerprint=<SSH fingerprint>
key_file=>path to PEM file>
tenancy=<ocid>
region=<region>

Please follow the instructions under -> https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm

Ionos Cloud (limited support)

I can offer only limited support for Ionos Cloud, as I don't have access to the API anymore. Ionos Cloud is a B2B only cloud service.

export IONOS_USERNAME=xxx
export IONOS_PASSWORD=yyy
export IONOS_TOKEN=<optional>

Amazon AWS

minectl ๐Ÿ—บ looks for credentials in the following order:

  • Environment variables.
  • Shared credentials file.
Credentials file

The credentials file is most often located in the ~/.aws/credentials and contains following content:

cat ~/.aws/credentials
[default]
aws_access_key_id = xxxx
aws_secret_access_key = zzzz
Environment variables can be set in the following way:
export AWS_ACCESS_KEY_ID=<aws_access_key_id>
export AWS_SECRET_ACCESS_KEY=<aws_secret_access_key>
export AWS_REGION=<aws_region>

VEXXHOST

It is recommended to store OpenStack credentials as environment variables because it decouples credential information from source code:

So download the OpenStack RC File from the Horizon UI by click on the "Download OpenStack RC File" button at the top right-hand corner.

To execute the file, run source xxxx-openrc.sh and you will be prompted for your password.

Thats all.

Multipass

โš ๏ธ Set the plan to cpu-memG. For example: 1-2G

Multipass is a mini-cloud on your workstation using native hypervisors of all the supported platforms (Windows, macOS and Linux), it will give you an Ubuntu command line in just a click (โ€œOpen shellโ€) or a simple multipass shell command, or even a keyboard shortcut. Find what images are available with multipass find and create new instances with multipass launch.

To install multipass, just follow the instructions on multipass.run for your platform.

Exoscale

Go to the IAM section in the Exoscale Console and create a new API key. You can restricte the key to just perform operations on the compute service.

export EXOSCALE_API_KEY=<key>
export EXOSCALE_API_SECRET=<secret>

Fuga Cloud

To get the OpenStack RC File from the Fuga Cloud UI, follow this steps:

  1. Log in to the Fuga Cloud Dashboard
  2. Go to Account โ†’ Access โ†’ Credentials
  3. You can choose a user credential or team credential.
  4. If you havenโ€™t already, you should create one of these credentials. Hold on to the password.
  5. Click on download OpenRC. This file contains all necessary configurations for the client.
source fuga-openrc.sh

Enter the password which matches the username of the contents of the OpenRC file.

Minecraft Server Versions ๐Ÿ“š

โš ๏ธ minectl ๐Ÿ—บ is not(!) providing any pre-compiled binaries of Minecraft or download a pre-compiled version.

Every non-vanilla version will be compiled during the build phase of your server.

Following Minecraft versions is minectl ๐Ÿ—บ supporting.

Vanilla (Mincraft: Java Edition or Bedrock Edition)

The Vanilla software is the original, untouched, unmodified Minecraft server software created and distributed directly by Mojang.

CraftBukkit

CraftBukkit is lightly modified version of the Vanilla software allowing it to be able to run Bukkit plugins.

Spigot

Spigot is the most popular used Minecraft server software in the world. Spigot is a modified version of CraftBukkit with hundreds of improvements and optimizations that can only make CraftBukkit shrink in shame.

PaperMC

Paper (formerly known as PaperSpigot, distributed via the Paperclip patch utility) is a high performance fork* of Spigot.

Purpur

Purpur is a drop-in replacement for Paper servers designed for configurability and new, fun, exciting gameplay features.

Forge

Forge is well known for being able to use Forge Mods which are direct modifications to the Minecraft program code. In doing so, Forge Mods can change the gaming-feel drastically as a result of this.

Fabric

Fabric is also an mod loader like Forge is with some improvements. Its lightweight and faster and it may is being the best mod loader in the future because its doing very good.

Source: [1]

Minecraft Proxy Versions ๐Ÿ“š

Network proxy server is what you set up and use as the controller of a network of server - this is the server that connects all of your playable servers together so people can log in through one server IP, and then teleport between the separate servers ingame rather than having to log out and into each different one.

A server network typically consist of the following servers:

  1. The proxy server itself running the desired software (BungeeCord being the most widely used and supported). This is the server that you would be advertising the IP of, as all players should be logging in through the proxy server at all times

  2. The hub (or main) server. When users connect to the network proxy server's IP, it will re-route those users to this server.

  3. All additional servers beyond the main server. Once you have at least one server running the proxy and one as the hub, any other servers will be considered extra servers that you can teleport to from the hub.

Bungee Cord

BungeeCord is a useful software written in-house by the team at SpigotMC. It acts as a proxy between the player's client and the connected Minecraft servers. End-users of BungeeCord see no difference between it and a normal Minecraft server.

Waterfall

Waterfall is a fork of BungeeCord, a proxy used primarily to teleport players between multiple Minecraft servers.

Waterfall focuses on three main areas:

  • Stability
  • Features
  • Scalability

Velocity

A Minecraft server proxy with unparalleled server support, scalability, and flexibility. Velocity is licensed under the GPLv3 license.

  • A codebase that is easy to dive into and consistently follows best practices for Java projects as much as reasonably possible.
  • High performance: handle thousands of players on one proxy.
  • A new, refreshing API built from the ground up to be flexible and powerful whilst avoiding design mistakes and suboptimal designs from other proxies.
  • First-class support for Paper, Sponge, and Forge. (Other implementations may work, but we make every endeavor to support these server implementations specifically.)

Server Configs ๐Ÿ“‹

Spot Instances

When you want to run a Minecraft server on a spot instance, you can use the following configuration options:

...
spot: <true |false>
...

This will enable the server to be run on a spot instance. At the moment, this is only supported by AWS, Azure and GCP.

MinecraftProxy Config ๐Ÿ“ก

If you want to start a server with a Minecraft Proxy, you need to define a MinecraftProxy proxy.

apiVersion: minectl.ediri.io/v1alpha1
kind: MinecraftProxy
metadata:
  name: minecraft-proxy
spec:
  server:
    cloud: <cloud provider name civo|scaleway|do|hetzner|akamai|ovh|equinix|gce|vultr|azure|oci|ionos|aws|vexxhost|multipass|exoscale>
    region: <cloud provider region>
    size: <cloud provider plan>
    ssh:
      port: 22 | or your custom port
      publickeyfile: "<path to ssh public key>.pub"
      fail2ban:
        bantime: "<ban time in seconds>"
        maxretry: "<max retry>"
    port: <server port>
    spot: <true |false>
    arm: <true |false>
  proxy:
    java:
      openjdk: <jdk version>
      xmx: <xmx memory for the vm>
      xms: <xms memory for the vm>
      options:
        - "-XX:+UseG1GC"
        - "-XX:+ParallelRefProcEnabled"
        - "-XX:MaxGCPauseMillis=200"
      rcon:
        password: <RCON server password>
        port: <RCON server port >
        enabled: <RCON enabled true|false>
        broadcast: <RCON broadcase true|false
    type: "bungeecord|waterfall|velocity"
    version: <version>
MincraftServer Config ๐Ÿ•น

You need a MinecraftServer manifest file, to describe the underlying compute instance and the Minecraft Server:

apiVersion: minectl.ediri.io/v1alpha1
kind: MinecraftServer
metadata:
  name: minecraft-server
spec:
  monitoring:
    enabled: true|false
  server:
    cloud: "provider: civo|scaleway|do|hetzner|akamai|ovh|equinix|gce|vultr|azure|oci|ionos|aws|vexxhost|multipass|exoscale"
    region: "region see cloud provider for details eg. fra1"
    size: "see cloud provider docs for details eg. g3.large"
    volumeSize: 100
    ssh:
      port: 22 | or your custom port
      publickeyfile: "<path to ssh public key>.pub"
      fail2ban:
        bantime: "<ban time in seconds>"
        maxretry: "<max retry>"
    port: "25565|19132 are the defaults for tcp/udp"
    spot: <true |false>
    arm: <true |false>
  minecraft:
    java:
      openjdk: "8|16 use jdk 8 for <1.17 java server version"
      xmx: 2G
      xms: 2G
      options:
        - "-XX:+UseG1GC"
        - "-XX:+ParallelRefProcEnabled"
        - "-XX:MaxGCPauseMillis=200"
      rcon:
        password: test
        port: 25575
        enabled: true
        broadcast: true
    edition: "java|bedrock|craftbukkit|fabric|forge|papermc|spigot|purpur"
    version: "<version>"
    eula: true
    properties: |
      level-seed=minectlrocks
      broadcast-rcon-to-ops=true
      ...

Attention: Please lookup the correct service size if you are setting the arm attribute to true

I created some example configs in the config folder for currently supported cloud provider and Minecraft editions.

EULA โš–

You need to set explicitly the EULA as new property in the MinecraftServer manifest to indicate your agreement with the Minecraft End User License. See -> https://minecraft.net/terms for the details.

minectl ๐Ÿ—บ Configuration File Wizard ๐Ÿง™

Calls the minectl wizard to create interactively a minectl ๐Ÿ—บ config

Usage:
  minectl wizard [flags]

Examples:
mincetl wizard

Flags:
  -h, --help            help for wizard
  -o, --output string   output folder for the configuration file for minectl ๐Ÿ—บ (default: /Users/dirien/.minectl)

Global Flags:
      --headless              Set this value to if mincetl is called by a CI system. Enables logging and disables human-readable output rendering (default: false)
      --log-encoding string   Set the log encoding: console|json (default: console) (default "console")
      --verbose string        Enable verbose logging: debug|info|warn|error|dpanic|panic|fatal

Watch the demo, for more details asciicast

Create Minecraft Server ๐Ÿ—

minectl create -h

Create an Minecraft Server.

Usage:
  minectl create [flags]

Examples:
mincetl create  \
    --filename server-do.yaml

Flags:
  -f, --filename string   Location of the manifest file
  -h, --help              help for create
  -w, --wait              Wait for Minecraft Server is started (default true)

Global Flags:
      --headless              Set this value to if mincetl is called by a CI system. Enables logging and disables human-readable output rendering (default: false)
      --log-encoding string   Set the log encoding: console|json (default: console) (default "console")
      --verbose string        Enable verbose logging: debug|info|warn|error|dpanic|panic|fatal

Delete Minecraft Server ๐Ÿ—‘

minectl delete -h

Delete an Minecraft Server.

Usage:
  minectl delete [flags]

Examples:
mincetl delete  \
    --filename server-do.yaml
    --id xxx-xxx-xxx-xxx


Flags:
  -f, --filename string   Location of the manifest file
  -h, --help              help for delete
      --id string         contains the server id
  -y, --yes               Automatically delete the server    

Global Flags:
      --headless              Set this value to if mincetl is called by a CI system. Enables logging and disables human-readable output rendering (default: false)
      --log-encoding string   Set the log encoding: console|json (default: console) (default "console")
      --verbose string        Enable verbose logging: debug|info|warn|error|dpanic|panic|fatal

List Minecraft Server ๐Ÿ“’

minectl list -h

List all Minecraft Server.

Usage:
  minectl list [flags]

Examples:
mincetl list  \
    --provider civo \
    --region LON1

Flags:
  -h, --help              help for list
  -p, --provider string   The cloud provider - civo|scaleway|do|hetzner|akamai|ovh|equinix|gce|vultr|azure|oci|ionos|aws|vexxhost|multipass|exoscale
  -r, --region string     The region for your cloud provider

Global Flags:
      --headless              Set this value to if mincetl is called by a CI system. Enables logging and disables human-readable output rendering (default: false)
      --log-encoding string   Set the log encoding: console|json (default: console) (default "console")
      --verbose string        Enable verbose logging: debug|info|warn|error|dpanic|panic|fatal

Update Minecraft Server ๐Ÿ†™

Update the Minecraft version. The function uses ssh (port 22).

minectl update -h
Update an Minecraft Server.

Usage:
  minectl update [flags]

Examples:
mincetl update  \
    --filename server-do.yaml
    --id xxx-xxx-xxx-xxx

Flags:
  -f, --filename string   Location of the manifest file
  -h, --help              help for update
      --id string         contains the server id
  -k, --ssh-key string    specify a specific path for the SSH key    

Global Flags:
      --headless              Set this value to if mincetl is called by a CI system. Enables logging and disables human-readable output rendering (default: false)
      --log-encoding string   Set the log encoding: console|json (default: console) (default "console")
      --verbose string        Enable verbose logging: debug|info|warn|error|dpanic|panic|fatal

RCON Minecraft Server ๐Ÿ”Œ

Use this function, to connect to the RCON port of your Minecraft Server. RCON is a protocol that allows server administrators to remotely execute Minecraft commands.

minectl rcon -h
RCON client to your Minecraft server.

Usage:
  minectl rcon [flags]

Examples:
mincetl rcon  \
    --filename server-do.yaml / \
    --id xxxx

Flags:
  -f, --filename string   Location of the manifest file
  -h, --help              help for rcon
      --id string         contains the server id

Plugins Minecraft Server โคด๏ธ

๐Ÿšง Plugins feature is still in beta.

Raw mode, to upload a local plugin file to your server. The function uses ssh (port 22).

minectl plugins  -h
Manage your plugins for a specific server

Usage:
  minectl plugins [flags]

Examples:
mincetl plugins  \
    --filename server-do.yaml
    --id xxx-xxx-xxx-xxx
        --plugin plugin.jar
    --destination /minecraft/mods

Flags:
  -d, --destination string   Plugin destination folder
  -f, --filename string      Location of the manifest file
  -h, --help                 help for plugins
      --id string            contains the server id
  -p, --plugin string        Location of the plugin
  -k, --ssh-key string       specify a specific path for the SSH key

Global Flags:
      --headless              Set this value to if mincetl is called by a CI system. Enables logging and disables human-readable output rendering (default: false)
      --log-encoding string   Set the log encoding: console|json (default: console) (default "console")
      --verbose string        Enable verbose logging: debug|info|warn|error|dpanic|panic|fatal

Monitoring ๐Ÿ“Š

Monitoring is optional and disabled by default. It can be enabled with simply adding following fields to the MinecraftServer manifest:

...
apiVersion: minectl.ediri.io/v1alpha1
kind: MinecraftServer
metadata:
  name: minecraft-server
spec:
  monitoring:
    enabled: true|false
  server:
...

Every instance of minectl ๐Ÿ—บ, has following monitoring components included:

The edition:java has on top following exporter included:

You can acces the prometheus via

http://<ip>:9090/graph

Volumes ๐Ÿ’ฝ

With the volumeSize property, you can provision an extra volume during the creation phase of the server.

It is always recommended using the provided volume of the server, but in some cases (large mod packs, community server, etc.) it makes sense to provision a bigger volume separately.

When a separate volume is defined, minectl ๐Ÿ—บ is automatically installing the Minecraft binaries on this volume.

apiVersion: minectl.ediri.io/v1alpha1
kind: MinecraftServer
metadata:
  name: minecraft-server
spec:
  server:
    cloud: akamai
    region: eu-central
    size: g6-standard-4
    volumeSize: 100
    ssh:
      port: 22 | or your custom port
      publickeyfile: "<path to ssh public and private key>/ssh"
      fail2ban:
        bantime: "<ban time in seconds>"
        maxretry: "<max retry>"
    port: 25565
  minecraft:
...

Headless Mode ๐Ÿ‘ป

With the global flag headless, it is now possible to run minectl ๐Ÿ—บ in a less human-readable output version. This is very helpful, if you want to run minectl ๐Ÿ—บ in workflow.

The flag verbose sets the level of logging and with log-encoding you can decide between json and console as encoding format.

Security ๐Ÿ”’

SSH Port

Now you can use the port property under the ssh object, to define the SSH port of the server. Per default, the SSH port is 22. This helps a lot, to avoid hackers to bruteforce your server.

SSH Key

With the publickeyfile property, you can define the location of your SSH public key on your local machine.

With the publickey property, you can define the content of your SSH public key.

...
publickey: "ssh-rsa AAAAB3 ... xxx"

If you need to update or upload a plugin to your server, you need to provide the SSH private key in the command with the new flag --ssh-key.

Fail2Ban

Fail2Ban is an intrusion prevention software framework that protects computer servers from brute-force attacks. With the property bantime you can define the ban time in seconds. With the property maxretry you can define the max retry.

If maxretry is reached, the IP is banned for the defined time (bantime).

Getting Started ๐ŸŽซ

Known Limitation ๐Ÿ˜ต

minectl ๐Ÿ—บ is still under development. There will be the possibility for breaking changes.

Contributing ๐Ÿค

Contributing via GitHub

Feel free to join.

License

Apache License, Version 2.0

Roadmap ๐Ÿ›ฃ

  • Support Bedrock edition #10
  • Add monitoring capabilities to minectl server #21
  • List Minecraft Server #11
  • New Command - Update Minecraft Server #12
  • New cloud provider - Hetzner #26
  • New cloud provider - Linode #31
  • New cloud provider - OVHCloud #43
  • New Cloud Provider Equinix Metal #49
  • New cloud provider - GCE #55
  • Add modded versions as new edition #20
  • New cloud provider - Vultr #90
  • Add Suport for Proxy Server - bungeecord and waterfall #95
  • New cloud provider - Azure #56
  • New cloud provider - Oracle/OCI #107
  • New cloud provider - Ionos Cloud #218
  • New cloud provider - AWS #210
  • Much more to come...

Libraries & Tools ๐Ÿ”ฅ

Legal Disclaimer ๐Ÿ‘ฎ

This project is not affiliated with Mojang Studios, XBox Game Studios, Double Eleven or the Minecraft brand.

"Minecraft" is a trademark of Mojang Synergies AB.

Other trademarks referenced herein are property of their respective owners.

Stargazers over time ๐ŸŒŸ

Stargazers over time

Source: