From 1e0f5cf2f398d83c6064d918007456bc7ab61bb0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Romain=20Gon=C3=A7alves?= <me@rgoncalves.se>
Date: Tue, 21 Dec 2021 15:33:54 +0000
Subject: README: Add first steps informations

---
 README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++-----
 1 file 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
 ```
-- 
cgit v1.2.3