Skip to content
/ minectl Public

minectl 🗺 is a cli for creating Minecraft server on different cloud provider.

License

Apache-2.0 license
166 stars 9 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

dirien/minectl

BranchesTags

Repository files navigation

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:

[1] https://www.spigotmc.org/wiki/what-is-spigot-craftbukkit-bukkit-vanilla-forg/

About

minectl 🗺 is a cli for creating Minecraft server on different cloud provider.

Topics

golang minecraft digitalocean azure spigotmc ovh gce scaleway vultr hacktoberfest hetzner oracle-cloud-infrastructure hetzner-cloud civo fabricmc equinix ovhcloud

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Security policy

Security policy
Activity

Stars

166 stars

Watchers

6 watching

Forks

9 forks
Report repository

Releases 43

v0.52.0 Latest
Jun 19, 2024
+ 42 releases

Packages

 
 
 

Contributors 10

Languages