Add README.md

README.md

@@ -0,0 +1,104 @@
+# 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)
+```
+
+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.
+
+### 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
+
+* Management of whitelist, banlist, and ops.json
+
+* INI/TOML configuration support for mods
+
+PRs are welcome.