From 8d2a6d27d6e5617786e1df7a286018018c589e5b Mon Sep 17 00:00:00 2001
From: Hippolyte Chauvin <hchauvin38@outlook.fr>
Date: Mon, 4 Dec 2023 16:21:53 +0100
Subject: [PATCH] Mise au propre de la documentation

---
 README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 72 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 8084e55..6043cc2 100644
--- a/README.md
+++ b/README.md
@@ -2,19 +2,83 @@
 
 ## How does it work
 
+`qemush` allows to run commands as Unix user `qemu` to manage virtual
+machines and their disks associated.
+
 ## Why
 
-- daemonless
-- lightweight
-- few dependencies
-- hackable
-- easy to setup
+`qemush` is **daemonless** : no bloaty long running process is needed for
+`qemush` to work.
+
+`qemush` is **lightweight** : it only consists in a shell script to
+automate repeated tasks and force good practices.
+
+`qemush` needs **few dependencies** : see section
+[Dependencies](#dependencies) for details.
+
+`qemush` is **hackable** : you can [write your own launching
+scripts](#write-a-launching-script) to make it work as intended.
+
+`qemush` is **easy to setup** : you can make it work in a few steps, see
+section [Installation instructions](#installation-instructions).
 
 ## Dependencies
 
-- `screen`
-- `source-highlight`
+- `qemu` - this is literally a QEMU wrapper so there's a chance you'll
+need it
+- `bash` - the `qemush` interpreter
+- `coreutils` - used for basic OS operations
+- `sudo` - execute commands as `qemu`
+- `screen` - for process supervision
+- `source-highlight` - for syntax highlighting when displaying launching
+scripts
+- any text editor - used for builting function to edit launching scripts
 
 ## Installation instructions
 
-- `make install`
+### QEMU user and group
+
+`qemush` acts as Unix user `qemu` to manage virtual machines. You need to
+create a system user `qemu` that cannot login, with any home directory,
+in an Unix group of the same name. Example :
+
+```sh
+# Example if the qemu user doesn't exist
+# Make sure /etc/shells contains /bin/nologin
+useradd -r -s /bin/nologin qemu
+```
+
+For ease of use, you need to grant every user in the `qemu` group via
+`sudo` the right to execute commands as `qemu`. You can find an example
+`sudoers` rule in this repo's `etc/sudoers.d` folder.
+
+### Add `qemush` in the `PATH`
+
+Use your preferred way to add the `qemush` script to a folder of `PATH`.
+Recommended : copy the script in `/usr/local/bin` to make it effortlessly
+system wide.
+
+## Usage
+
+### Writing a launching script
+
+The default text editor used by `qemush` is `nvim`, but it can be
+overriden by the `EDITOR` environment variable.
+
+Run the following command to start editing a launching script by the name
+of your choice :
+
+```sh
+qemush edit "$name"
+```
+
+Example scripts are available in this repo's `qemu/bin` folder.
+
+### Launching a virtual machine
+
+Virtual machines are identified by the name of their launching scripts.
+You can launch any machine with the following command :
+
+```sh
+qemush start "$name"
+```