README: Add first steps informations

1 files changed, 44 insertions, 5 deletions

diff --git a/README.md b/README.md
index e11242d..d19fe44 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,54 @@
 # Introduction
 
-Ansible roles and scripts used for rgoncalves.se's homelab. This repository is
-a rewrite of the now deprecated `_infrastructure/ansible`.
+[ansible](https://github.com/ansible/ansible) roles and scripts used
+for rgoncalves.se's homelab. This repository is a rewrite of the now deprecated
+`_infrastructure/ansible`.
 
 # Quickstart
 
-## Development
+Setup your development environment and run you first playbooks with the
+following commands:
+
+```
+$ poetry install
+$ poetry shell
+$ . ./bin/env
+# ansible-playbook playbooks/workstation.yml -e workstation_user=$USER
+$ ansible-playbook playbooks/site.yml
+```
+
+# Getting started
+
+## Poetry environment
+
+[poetry](https://github.com/python-poetry/poetry) is used for managing the
+`ansible` and `mitogen` packages.
+
+```
+poetry install
+```
+
+## Mitogen
+
+[mitogen](https://github.com/mitogen-hq/mitogen) is a really fast executor
+plugin for Ansible. It is not enabled by default, and that's the reason
+`poetry` and the following script are used.
+
+You have to source the `env` script if you want to execute playbooks with
+`mitogen`, preferably inside a `poetry` environment. It is important because
+`mitogen` upstream is currently set to master, allowing compatibility with
+`ansible` 2.12.
+
+```
+poetry shell
+. ./bin/env
+```
+
+## Development machine
 
 A new development workstation can be scaffolded thanks to the workstation
-playbook.
+playbook and role.
 
 ```
-$ ansible-playbook playbooks/workstation.yml
+# ansible-playbook playbooks/workstation.yml
 ```