ansible-role-minecraft/README.md

# ansible-role-minecraft

A role to install a Minecraft server, supporting Paper and Forge.

## Supported Configuration

The role supports the following distros:

* Anything Debian-like

The only dependency is really Java. Outside of that, if you want to install Java some other way, you can probably use this role on any distro.

The following Minecraft configuration is supported:

* Any release version of Minecraft (no beta or alpha, sadly) that has an appropriate Forge or Paper release

## Basic Setup

Template out the role, ensuring it has root privileges. Set the following vars:

```yaml
minecraft_name: Name of the subdirectory of the server
minecraft_version: Version of Minecraft desired in semver (i.e. 1.7.10, 1.16.4, does not support Beta)
minecraft_enabled: Boolean to determine state of server (defaults to yes)
```

You must also set one of `minecraft_paper_install` *or* `minecraft_forge_install` depending on desired configuration. Vanilla servers are not supported; use Paper.

You can also set the following variables for additional configuration, which may be necessary depending on the size of the modpack or the plugins installed:

```yaml
minecraft_jre_xmx: 4096m
minecraft_jre_xms: 2048m
```

`server.properties` can be managed programatically as well:

```yaml
minecraft_server_properties:
  - opt: difficulty
    value: hard
  - opt: server-port
    value: 12345
  - opt: view-distance
    value: 12
```

Run the play and enjoy.

## Paper Setup

The out-of-the-box defaults are probably ideal, but if you want, you can configure the URL from which to install Paper (should you want to backdate or test bleeding edge or something) by setting the `minecraft_paper_downloadurl` variable.

## Forge Setup

In addition to the vanilla configuration above, you'll want to set at least these variables:

```yaml
minecraft_forge_version: Forge version in semver*
```

The Forge version does *not* include the Minecraft version in its string; we're only interested in the last technically semver-compatible section of the version string. Consider the following 1.16.3 release of Forge:

forge-1.16.3-34.1.42

In this case, set `minecraft_forge_version` to `34.1.42`. The role will automatically download and install Forge through the Universal installer of the related release.

Older versions of Forge may require changing `minecraft_forge_versionstring` to `{{ minecraft_name }}-{{ minecraft_forge_version }}-{{ minecraft_name }}` and `minecraft_forge_jar_name` to `forge-{{ minecraft_forge_versionstring }}-universal.jar`.

### Mods

Naturally, Forge is nothing without mods. To install a modpack, specify the following variable as a URL to a zip file with the modpack:

```yaml
minecraft_forge_packurl: https://modpack.whatever/path/to/modpack.zip
```

The exact layout of the pack need not be specified; when installing a modpack, the role will use a short script to find the first directory that contains a `mods` directory and install from there. Updating automatically is not supported; you'll probably have to prune the `mods` directory before an update.

You can also manually configure additional mods through the following variables:

```yaml
minecraft_forge_mods:
  - "https://media.forgecdn.net/files/3113/275/industrial-foregoing-1.16.4-3.2.2-daea863.jar"
minecraft_forge_mods_remove:
  - industrial-foregoing-1.16.3-3.1.1-a834e76.jar
```

In this case, `minecraft_forge_mods` is a list of URLs to download and install in the `mods` directory. `minecraft_forge_mods_remove` is the opposite.

## Administration

The role will install any servers as systemd units. A server named `foo` will have the unit `minecraft@foo.service`. The server runs as its own user.

To access the server console, invoke `screen` as the `minecraft` user. For example, to access the console of a server named `foo`, use `sudo -u minecraft screen -r foo`.

## TODO

There's a lot that I want to add to this role. Namely:

* Vanilla server installation

* INI/TOML configuration support for mods

* YAML configuration support for plugins

PRs are welcome.