Ansible Role for Minecraft

This role sets up Minecraft or Spigot and configures it to run using systemd or Supervisor.

Thanks to devops-coop for most of this release.

Installation

ansible-galaxy install totaldebug.minecraft

Features

• Works with vanilla Minecraft and Spigot
• Compatible with Debian 10, Ubuntu 18.04, RHEL/CentOS 7, and RHEL/CentOS 8
• Safely stops the server using "stop" when running under systemd
• Uses GitHub Actions and Molecule for integration tests
• Manages user access control lists (ACLs)
• Handles server.properties
• Hooks: include additional tasks at specific points during execution

Role Variables

Role variables

The following default variables are set in defaults/main.yml.

minecraft_server_type choose between minecraft or spigot (default: minecraft)

minecraft_version Minecraft version to install (default: latest)

Examples:

.. code:: yaml

   minecraft_version: latest
   minecraft_version: 1.10
   minecraft_version: 1.9.1
   minecraft_version: 16w21a

minecraft_server_download_url Minecraft download URL (default: https://launcher.mojang.com/v1/objects)

minecraft_server_download_checksum Checksum for the Minecraft download URL

minecraft_user System user for Minecraft (default: minecraft)

minecraft_group System group for Minecraft (default: minecraft)

minecraft_home Directory where Minecraft is installed (default: /srv/minecraft)

minecraft_max_memory Maximum Java memory allocation (-Xmx) (default: 1024M)

minecraft_initial_memory Initial Java memory allocation (-Xms) (default: 1024M)

minecraft_service_name Name of the systemd service or Supervisor program (default: minecraft)

minecraft_supervisor_name DEPRECATED: Name of the Supervisor program (default: {{ minecraft_service_name }})

minecraft_process_control Choose between systemd and supervisor (default: systemd).

minecraft_whitelist List of Minecraft usernames to allow (default: [])

minecraft_ops List of Minecraft usernames with admin rights (default: [])

minecraft_banned_players List of Minecraft usernames to ban (default: [])

minecraft_banned_ips List of IP addresses to ban (default: [])

minecraft_server_properties Dictionary of entries for server.properties (e.g. server-port: 25565) (default: {})

Hooks and Execution Stages

ansible-minecraft organizes its execution into several stages:

setup

• Install prerequisites (e.g., Java)
• Create Minecraft user and group

download

• Get the latest version from the launcher API
• Download Minecraft

install

• Create symlink to minecraft_server.jar
• Agree to the EULA

acl

• Configure server access (whitelist, banned players, etc.)

configure

• Set server.properties options

start

• (Re)start the server

You can add custom tasks before or after specific stages. Just specify a task include file using the appropriate role variable:

.. code:: yaml

- hosts: minecraft
  roles:
    - role: devops-coop.minecraft
      minecraft_hook_before_start: "{{ playbook_dir }}/download-world-from-s3.yml"

Available hooks include:

minecraft_hook_before_setup Run before setup tasks

minecraft_hook_after_setup Run after setup tasks

minecraft_hook_before_download Run before download tasks

minecraft_hook_after_download Run after download tasks

minecraft_hook_before_install Run before install tasks

minecraft_hook_after_install Run after install tasks

minecraft_hook_before_start Run before start tasks

minecraft_hook_after_start Run after start tasks

Example

.. code:: yaml

- hosts: minecraft
  roles:
     - { role: devops-coop.minecraft, minecraft_whitelist: ["jeb_", "dinnerbone"]}

Contributing

Pull requests are welcome. This role currently does not support custom Minecraft servers.

Versioning

This project follows semantic versioning.

In semantic versioning, the role contract is defined by the role variables.

• Breaking changes will increase the major version. This includes changing the default value of a role variable.
• Changes that add new features but do not require user action will increase the minor version.
• Bug fixes will increase the patch version.