This role installs Minecraft or Spigot and configures it to run under systemd or Supervisor.
If you're viewing this at https://github.com/devops-coop/ansible-minecraft/, you're reading the documentation for the master branch. View documentation for the latest release (3.1.0).
- Optional: Python 2.7 on the Ansible control machine to generate user ACLs
- Optional: Ansible 2.0.2+ or
curl
on the control machine to fetch the latest Minecraft version
ansible-galaxy install devops-coop.minecraft
- supports vanilla Minecraft and Spigot
- supports Debian 8, Ubuntu 14.04, Ubuntu 16.04, and RHEL/CentOS 7
supports different process supervisors on different platforms
OS Supervisor systemd Debian 8 ✓ ✓ Ubuntu 14.04 ✓ Ubuntu 16.04 ✓ CentOS 7 ✓ - safely stops the server using stop when running under systemd
- uses Docker and Inspec to run integration tests
- manages user ACLs
- manages
server.properties
- hooks: include arbitrary tasks at specific stages during execution
This project follows semantic versioning.
In the context of semantic versioning, consider the role contract to be defined by the role variables.
- Changes that require user intervention will increase the major version. This includes changing the default value of a role variable.
- Changes that do not require user intervention, but add backwards-compatible features, will increase the minor version.
- Bug fixes will increase the patch version.
Refer to the change log for upcoming changes.
The following variable defaults are defined in defaults/main.yml
.
minecraft_version
Minecraft version to install (default:
latest
)Examples:
minecraft_version: latest minecraft_version: 1.10 minecraft_version: 1.9.1 minecraft_version: 16w21a
minecraft_url
Minecraft download URL (default:
https://s3.amazonaws.com/Minecraft.Download/versions
)minecraft_user
system user Minecraft runs as (default:
minecraft
)minecraft_group
system group Minecraft runs as (default:
minecraft
)minecraft_home
directory to install Minecraft to (default:
/srv/minecraft
)minecraft_max_memory
Java max memory (
-Xmx
) to allocate (default:1024M
)minecraft_initial_memory
Java initial memory (
-Xms
) to allocate (default:1024M
)minecraft_service_name
systemd service name or Supervisor program name (default:
minecraft
)minecraft_supervisor_name
DEPRECATED: Supervisor program name (default:
{{ minecraft_service_name }}
)minecraft_process_control
Choose between
systemd
andsupervisor
(default:systemd
).minecraft_whitelist
list of Minecraft usernames to whitelist (default:
[]
)minecraft_ops
list of Minecraft usernames to make server ops (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 server.properties entries (e.g.
server-port: 25565
) to set (default:{}
)minecraft_server
choose between
minecraft
orspigot
(default:minecraft
)
ansible-minecraft organizes execution into a number of run stages:
setup
- install prerequisites (e.g., Java)
- create Minecraft user and group
download
- fetch the latest version of from the launcher API
- download Minecraft
install
- symlink version to
minecraft_server.jar
- agree to EULA
- symlink version to
acl
- configure server ACLs (whitelist, banned players, etc.)
configure
- set
server.properties
- set
start
- (re)start server
You can execute custom tasks before or after specific stages. Simply specify a task include file using the relevant role variable:
- hosts: minecraft
roles:
- role: devops-coop.minecraft
minecraft_hook_before_start: "{{ playbook_dir }}/download-world-from-s3.yml"
The available hooks are:
minecraft_hook_before_setup
run before
setup
tasksminecraft_hook_after_setup
run after
setup
tasksminecraft_hook_before_download
run before
download
tasksminecraft_hook_after_download
run after
download
tasksminecraft_hook_before_install
run before
install
tasksminecraft_hook_after_install
run after
install
tasksminecraft_hook_before_start
run before
start
tasksminecraft_hook_after_start
run after
start
tasks
- hosts: minecraft
roles:
- { role: devops-coop.minecraft, minecraft_whitelist: ["jeb_", "dinnerbone"]}
The best way to contribute is to use this role to deploy your own Minecraft server! We really appreciate bug reports from the wild.
If you'd like to help with the project itself, here are some other ways you can contribute:
- Add support for additional servers like Cuberite.
- Write integration tests for Minecraft- or Spigot-specific configuration.
- Share useful hooks.
Testing can be done using the provided Vagrantfile or by installing Docker and Docker Compose locally.
This role includes a Vagrantfile used with a Docker-based test harness that approximates the Travis CI setup for integration testing. Using Vagrant allows all contributors to test on the same platform and avoid false test failures due to untested or incompatible docker versions.
- Install Vagrant and VirtualBox.
- Run
vagrant up
from the same directory as the Vagrantfile in this repository. - SSH into the VM with:
vagrant ssh
Run tests with
make
.make -C /vagrant xenial64 test
Integration tests use systemd by default. Set PROCESS_CONTROL
to change this:
make -C /vagrant trusty64 test PROCESS_CONTROL=supervisor
See make help
for more information including a full list of available targets.
Alternatively, you can install Docker and Docker Compose to run these tests locally on your machine.
- Install Docker and Docker Compose.
Run tests with
make
.make jessie64 test
Integration tests use systemd by default. Set PROCESS_CONTROL
to change this:
make trusty64 test PROCESS_CONTROL=supervisor
See make help
for more information including a full list of available targets.
Apache 2.0
To automate the installation, this role automatically accepts the Minecraft EULA. Be aware that by using this role, you implicitly accept the same EULA.