From b2fc4dc08b37f844c270158826b2b44ad2aa0b36 Mon Sep 17 00:00:00 2001
From: NaeiKinDus <git@0x2a.ninja>
Date: Wed, 29 Nov 2023 00:00:00 +0000
Subject: [PATCH] doc: updated README for clearer usage directions and general
 information

---
 README.md | 74 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 58 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index c8d082a..9d5c1fb 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,21 @@
 # Abstract
-## List of services
+## Presentation
+This project aims to help me deploy and manage my homelab and a few other machines / services that I use, only for a personal purpose.
+It is also an opportunity for me to learn and improve my knowledge of Ansible,the IaC side of operations and systems administration.
+
+**What does it mean?**
+The implications are that I will not be using external roles and collections unless they cover a part of my workflow that
+I do not wish to implement or have low value for me.
+The result of this premise is that this repository will probably not cover your use case and you should definitely not use this project as-is unless you
+thoroughly reviewed it, especially the system hardening and security tweaks that are implemented.
+
+## Roles
+- ***common***: all configurations and tools that are deployed everywhere, e.g. basic utilities, common QoL tweaks, shell customization.
+- ***development***: everything I use for development purposes, e.g. development tooling, assets and documentation creation, compilers and toolchains.
+- ***gaming***: gaming on linux, e.g. Steam and Heroic Games Launcher.
+- ***security***: security-related softwares and tweaks, e.g. applying custom system limits, installing an antivirus.
+- ***server***: common tooling for servers, e.g. monitoring, altering, firewall rules.
+
 # Usage
 ## Prerequisites
 ***Required dependencies***
@@ -55,7 +71,34 @@ cp inventory/inventory.yml.dist inventory/inventory.yml
 cp inventory/vault.yml.dist inventory/vault.yml
 ```
 
-## Usage
+## Using Tasks
+### Tasks
+All tasks are available in `Taskfile.yml` and are executed at the root of the project.
+
+#### molecule
+Execute a molecule command, e.g. `task molecule -- converge` to create and populate a test container.
+
+#### venv
+Execute a command using the Python wrapper that activates the virtualenv, e.g. `task venv -- `
+
+#### docker
+*build*: build all docker images available in `/images`, e.g. `task docker:build`
+
+*push*: push built images to docker hub, e.g. `task docker:push`
+
+#### module:<module_name>
+Directly execute a Python module located in `collections/ansible_collections/nullified/infrastructure/plugins/modules` with its default configuration
+(typically the path to a test YAML file). Used only for debugging purpose.
+Example call: `task module:github_artifact`.
+
+#### test:collections
+Executes molecule tests on each collections declared in `collections/ansible_collections`. Requires the collection to have a working molecule configuration.
+Useful to ensure playbooks behave as expected using a Docker container.
+
+#### test:modules
+Run Ansible's sanity tests on each collections declared in `collections/ansible_collections`.
+
+### Examples
 ```shell
 # encrypt vault
 task venv -- ansible-vault encrypt configuration/host_vars/vault.yml
@@ -80,23 +123,22 @@ task venv -- ansible-galaxy collection init tooling
 
 ## Cheatsheet
 ### Ansible usage
-***validate files***
-`ansible-playbook --syntax-check <file>`
+```shell
+# validate files
+ansible-playbook --syntax-check <file>
 
-***gather facts***
-`ansible <target> -m setup`
-
-***handlers***
-invoked by a task through `notify`, executed only if caller triggered a state change; runs at the end of the play in the order
-they are declared;
-```yaml
-# -> force handlers to run:
-- name: some task
-  meta: flush_handlers
+# gather facts of a docker container
+ansible <target> -m setup
 ```
 
-***looping***
-looping in task by using the `loop` array with items to loop over;
+```yaml
+# handlers
+# invoked by a task through `notify`, executed only if caller triggered a state change; runs at the end of the play in the order they are declared;
+
+# -> force handlers to run:
+- name: execute all handlers
+  meta: flush_handlers
+```
 
 ***runtime grouping***
 ```yaml