readme

README.md

@@ -1,3 +1,56 @@
-# ansible-role-minecraft-server
+# ansible-minecraft-server
 
-An ansible role to deploy a minecraft server.
+An ansible role to deploy a minecraft server.
+
+## Prerequisites
+
+* Some basic Linux knowledge.
+* Some way of provisioning a machine to host the server.
+* [ansible](https://docs.ansible.com/ansible/latest/index.html)
+
+## Deploy
+
+1. Provision a machine to host the minecraft server.
+   * Exact steps will vary depending on your hosting solution. Refer to their documentation.
+   * Refer to the [wiki](https://minecraft.fandom.com/wiki/Server/Requirements) for recommendations on the appropriate size of the machine for your expected player count.
+   * Make sure to create a user account on the server with access to the command `sudo` (sudoer). Make this account have the same name as your local user account to simplify the next steps.
+2. Edit *hosts* and replace `minecraft-server` with the hostname or ip of the machine hosting the minecraft server.
+3. Edit *group_vars/minecraft-server.yaml* to change the basic server configuration. Refer to **Configuration options** below for more detail on available configurations.
+   * Set `mc_server_memory` to an appropriate value.
+   * Optionally, configure `mc_server_ops` to be the info of a server "operator" (admin).
+4. Deploy the minecraft server using the command `ansible-playbook --ask-become-pass -i hosts`
+   * You will be prompted for a password by ansible. Provide the password that you would use to run a command with `sudo` on the server.
+
+## Configuration options
+
+All configuration options are in the file `group_var/minecraft-server.yaml`. Additional configurations are available, but are not exposed by the ansible role at this time. To change them, you can connect to the server and find them in the server install directory */srv/minecraft-server*.
+
+Do not edit the following configuration files, they will be overwritten if ansible is ran again:
+* */srv/minecraft-server/eula.txt*
+* */srv/minecraft-server/ops.json*
+
+This table list the options that can be configured in `group_var/minecraft-server.yaml`
+| Name | Default | Description |
+| --- | --- | --- |
+| `mc_server_version` | `15c777e2cfe0556eef19aab534b186c0c6f277e1` | The version of the server to download on the server |
+| `mc_server_memory` | `1000M` (1GB) | The quantity of the memory assigned to the minecraft server. Take care of leaving some (around 500M) memory available for system processes. Memory requirements scales with the number of players on the server, refer to the [wiki](https://minecraft.fandom.com/wiki/Server/Requirements) for recommendations.
+| `mc_server_ops` | `[]` (none) | A list of server operators (admins). See the section below on what needs to be provided for each entry to the list |
+
+Each entries of the list `mc_server_ops` must have the **all** following values set:
+| Name | Example | Description |
+| --- | --- | --- |
+| `uuid` | `649a9370-5cad-4553-93c8-cf0af25208dd` | The uuid of the the player. The uuid can be queried using [this tool](https://mcuuid.net/). |
+| `name` | `jirost` | The name of the player. |
+| `level` | `4` | The level of permissions granted to the player. Refer to the [wiki](https://minecraft.fandom.com/wiki/Permission_level) for more details |
+
+### Example configuration
+
+``` yaml
+# Assign 3.5GB of memory to the server
+mc_server_memory: 3500M
+# Grant player with name "jirost" owner permissions
+mc_server_ops:
+  - uuid: 649a9370-5cad-4553-93c8-cf0af25208dd
+    name: jirost
+    level: 4
+```

group_vars/minecraft-server.yaml

@@ -1,4 +1,4 @@
-mc_server_memory: 3500M
+mc_server_memory: 2000M
 mc_server_ops:
   - uuid: 649a9370-5cad-4553-93c8-cf0af25208dd
     name: jirost