https://github.com/adamiok/minecraft-manager
An ansible role to manage minecraft servers and proxies on multiple machines.
https://github.com/adamiok/minecraft-manager
ansible minecraft minecraft-mana minecraft-manage-tool minecraft-manager minecraft-proxy minecraft-server
Last synced: 8 days ago
JSON representation
An ansible role to manage minecraft servers and proxies on multiple machines.
- Host: GitHub
- URL: https://github.com/adamiok/minecraft-manager
- Owner: Adamiok
- License: mit
- Created: 2023-06-04T05:18:05.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-28T16:52:40.000Z (12 months ago)
- Last Synced: 2025-10-22T20:24:02.407Z (4 months ago)
- Topics: ansible, minecraft, minecraft-mana, minecraft-manage-tool, minecraft-manager, minecraft-proxy, minecraft-server
- Language: Shell
- Homepage:
- Size: 40 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Minecraft Manager
This is an Ansible role that manages remote Minecraft servers.
**Note: This role does not create Minecraft servers. You are responsible for managing the files!**
## Features
- Joins template and override files
- Supports naming services
- Launches services in a screen session
- Provides interaction with services (start, stop, run a command)
- Services can be safely edited and deleted
- Setup script is provided
- **Automatic updates for most popular plugin sites**. See autoupdate section below.
- Includes a bash script wrapper for quick and easy use.
## Installation
Copy the `role/minecraft` directory to any valid Ansible role paths. The default paths are:
- `roles/` (relative to the current playbook - not recommended; does not work with the bash wrapper)
- `/usr/share/ansible/roles`
- `~/.ansible/roles`
- `/etc/ansible/roles`
Then run the `setup/setup-playbook` using `ansible-playbook setup-playbook.yml`. This playbook will prompt you for configuration entries. Make sure it runs in interactive mode and choose the hosts you want to manage with this role.
The iptables update script is optional and is provided for your convenience.
## Configuration
### Defaults
The role uses configurable values located in `roles/defaults/config.yml`. To replace these defaults, simply set the corresponding variable name before invoking the role. To modify defaults for the script, you need to edit it.
### Templates and Overrides
The use of this role relies on two main principles.
When a service is created, it is given two values by the user: the template and the name (passed as `service_name` due to "name" being reserved). The files for the current service are created using the following steps:
1. Find and copy all files from the template.
2. Check if an override for the current name exists. If not, the process stops here.
3. Copy all override files, replacing any template files with the same name.
To illustrate this, here are some examples:
Let's say we have the following service:
`survival (paper)`
So the name is `survival`, and the template is `paper`.
The directory structure on the control node:
```
~/
templates/
paper/
plugins/
AwakenLife.jar
server.jar
start.sh
server.properties
overrides/
survival/
plugins/
Worldguard.jar
server.properties
```
Since the override directory (`overrides/survival`) exists, files from the override will be copied to the service. As a result, the service (on the remote node) will have the following directory structure:
```
/
plugins/
AwakenLife.jar
Worldguard.jar
server.jar
start.sh
server.properties (Content of the file will be taken from overrides)
```
### Bash Scripts
As you may have noticed, there is a `scripts/` directory containing multiple bash scripts. These scripts need to be placed in the template or override directory to be able to use some functions of this role.
Why this approach?
Each different service type (paper, purpur, bungeecord, velocity) has a different approach and options passed to it. This allows us to maintain compatibility with different service types and provide an easy way to modify startup options without having to modify the role.
Please open (and potentially edit) the scripts before adding them to your template/override directory. They have a SETTINGS category for easy modifications.
The `start` command requires the `start.sh` script to be present and it needs to have executable permissions. Similarly, the `backup` command requires the `backup.sh` script to be present and executable.
The `restart.sh` script is different and is not needed by the role. However, it is required for server restarts to work correctly. Set this script as your restart script, for example: `restart-script: ./restart.sh` in `spigot.yml` for Spigot-based servers.
## Usage
### Recommended Usage
Place the `services.sh` script in a directory. This script will interact with the Ansible role without requiring you to create your own playbooks. To use it, navigate to the directory where the script is located and run `./services.sh -h`.
### Advanced Usage
This is still a regular Ansible role that uses tags to separate different actions. Therefore, it can be invoked as a role using the methods specified in the [Ansible documentation](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#using-roles). To view a list of possible tags, refer to `roles/minecraft/tasks/main.yml`.
## Autoupdate
This feature uses file names to update all plugins (and some servers too!) in one command. The currently supported autoupdate hosts are: `bukkit`, `github`, `hangar`, `jenkins`, `modrinth`, `papermc`, `projectkorra`, `spigotmc`. The numbers at the end are managed by the role and are used to store build numbers. If you have created an empty file and want it to be autoupdated, set the build number as 0 (as shown in examples). The next time you update, it will be replaced by the real build number.
File name format for different update sources:
- Bukkit: `AUTOUPDATE_COMMENT_bukkit_pluginName__0.jar`
- GitHub: `AUTOUPDATE_COMMENT_github_Author:Repo_fileNameToDownloadPrefix_0.jar`
- Hangar: `AUTOUPDATE_COMMENT_hangar_Author:Name_releasePlatform_0.jar`
- Jenkins: `AUTOUPDATE_COMMENT_jenkins_jenkinsUrl_fileNameToDownloadPrefix_0.jar`
- Modrinth: `AUTOUPDATE_COMMENT_modrinth_pluginName_releasePlatform_0.jar` (for modrinth, the server version is taken from `target.mcversion` file. The updater will only download versions caompatible with the server, you can skip this check using a `!` before the `releasePlatform`. This is needed for velocity plugins)
- PaperMC: `AUTOUPDATE_COMMENT_papermc_project_mcVersion_0.jar` (for paper, the target mcVersion must also be set in `target.mcversion` file)
- GeyserMC: `AUTOUPDATE_COMMENT_geysermc_project-platform_0_0.jar`
- ProjectKorra: `AUTOUPDATE_COMMENT_projectkorra_id__0.jar`
- SpigotMC: `AUTOUPDATE_COMMENT_spigotmc_id__0.jar`