From 80d622a6a4dcf666c3e1ff39a74a54cc11ec6372 Mon Sep 17 00:00:00 2001
From: Wojciech Kozlowski <wk@wojciechkozlowski.eu>
Date: Sun, 4 Dec 2022 15:43:10 +0100
Subject: [PATCH] Update readme to document inventory and tag usage

---
 README.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/README.md b/README.md
index 6f0a4ea..4300a1d 100644
--- a/README.md
+++ b/README.md
@@ -8,3 +8,43 @@ Ansible playbooks for provisioning The Nine Worlds.
 - Decrypt with: ```ansible-vault decrypt secrets.yml```
 - Print secrets to STDOUT: ```ansible-vault decrypt --output - secrets.yml```
 - Run a playbook with ```ansible-playbook --vault-id @prompt playbook.yml```
+
+## Main
+
+The main entrypoint for The Nine Worlds is [`main.yml`](main.yml).
+
+### Production and testing
+
+The inventory files are split into [`production`](production) and [`testing`](testing).
+
+To run the `main.yml` play on production hosts:
+``` sh
+ansible-playbook main.yml -i production
+```
+
+To run the `main.yml` play on production hosts:
+``` sh
+ansible-playbook main.yml -i testing
+```
+
+### Roles
+
+The plays are composed of roles defined in [`plays/roles`](plays/roles).
+
+To play only a specific role, e.g. `system_base`, run:
+
+``` sh
+ansible-playbook --tags "role:system_base"
+```
+
+### Role sub-tasks
+
+Some roles are split into smaller groups of tasks. This can be checked by looking at the
+`tasks/main.yml` file of a role, e.g.
+[`plays/roles/system_base/tasks/main.yml`](plays/roles/system_base/tasks/main.yml).
+
+To play only a particular group within a role, e.g. `sshd` in `system_base`, run:
+
+``` sh
+ansible-playbook --tags "role:system_base:sshd"
+```