begin of doc

README.md

@@ -1 +1,50 @@
-# Configuration NixOS au Crans
+# Configuration NixOS au Crans
+
+Voici la configuration NixOS du Crans.
+
+Les fichiers `README.md` des différents dossiers devraient indiquer assez précisément le rôle du dossier (et si ce n'est pas le cas, fais de la doc !).
+
+**Table des matières**
+
+1. [`Nix` et `NixOS`](#nix-et-nixos)
+    1. [`Nix`](#nix)
+    2. [`NixOS`](#nixos)
+    3. [`Nix Store`](#nix-store)
+    4. [`Flakes`](#flakes)
+
+## Nix et NixOS
+
+Voici une petite introduction de ce que sont `nix` et `NixOS`. Le but n'est pas de faire un véritable tutoriel mais plutôt faire des rappels qui peuvent toujours être utiles (ou pour les nouveaux et nouvelles apprenti⋅e⋅s !).
+
+[`NixOS`](https://nixos.org/) est une distribution Linux basé sur une configuration **déclarative**, permettant ainsi une **reproducibilité**. Cette configuration est écrite dans le langage [`nix`](https://nixos.org/manual/nix/stable/language/index.html). N'ayez pas peur de ce langage, on peut le décrire comme une version plus expressive du JSON (avec des variables, des fonctions, ...).
+
+### Nix
+
+En lisant quelques fichiers de configuration, vous devriez rapidement comprendre la syntaxe de `nix` (qui n'est pas très complexe). Voici une liste non exhaustive de subtilités que vous pouvez rencontrer dans la configuration NixOS du Crans qu'il faut avoir en tête en lisant du code `nix` :
+
+* `nix` est typé et, dans la grande majorité des cas, ne pourra pas être exécuté si les types ne sont pas respectés. Les types les plus importants sont : les nombres (ex : `1`), les chaînes de caractères (ex : `"toto1234"`), les listes (ex d'une liste de nombres : `[ 1 10 1234 ]`, attention il n'y a pas de séparateur entre les éléments), les ensembles (ex : `{ a = "foo"; b = 3; }`), et les fonctions (ex : `x: x + 1` qui correspond à une fonction qui à `x` associe `x + 1`). Vous trouverez plus de détails [sur cette page](https://nixos.org/manual/nix/stable/language/values).
+
+* Les codes `a.b = 3;` et `a = { b = 3; };` sont sémantiquement équivalents : cela signifie que vous pouvez changer l'un en l'autre et réciproquement. Usuellement, la première version n'est utilisé que lorsque `a` n'a qu'un seul attribut.
+
+* La variable `config` contient toute la configuration actuelle : elle permet d'utiliser des valeurs déclarées dans un autre fichier et susceptibles d'être modifiées dans le futur sans que cela ne pose de problème. Cela sera très utile notamment pour `Sops` (voir [secrets/README.md](secrets/README.md)).
+
+* Lorsque vous importez d'autres fichiers avec `imports`, vous ne pouvez qu'importer des fichiers. Si vous importez un dossier, cela n'aura pour effet que d'importer le fichier `default.nix` du dossier importé.
+
+### NixOS
+
+`NixOS` se construit (*build* en anglais) sous forme de dérivations (voir [la partie sur le `Nix Store`](#nix-store) pour plus d'explications). Celles-ci contiennent l'intégralité de la configuration au moment du build, ce qui est forcé par le fait que l'évaluation se fait de façon pure, c'est-à-dire qu'il n'est pas possible d'utiliser des éléments en dehors de la configuration pour écrire la configuration. Cela est forcé par l'utilisation des `flakes` (voir [la partie consacrée aux `flakes`](TODO)).
+
+Dans cette configuration, et grâce à l'utilisation des `flakes`, il est possible d'écrire la configuration de plusieurs machine dans ce même dépôt git. Chaque machine sous `NixOS` aura donc le code de chaque autre machine inscrite dans la configuration, mais du fait que **nix s'évalue de manière paresseuse**, chaque machine n'évaluera et ne compilera que ce qui est nécessaire pour sa propre configuration.
+
+Pour trouver des options pour décrire la configuration d'une machine, rendez-vous sur le saint graal de `nixpkgs` (le dépôt contenant tous les logiciels et librairies packagés pour `nix`, le package manager du même nom que le langage), et de `NixOS` : https://search.nixos.org/. Vous pouvez également trouver de l'aide pour la configuration de services sur https://nixos.wiki/.
+
+### Nix Store
+
+Le `Nix Store` est une abstraction permettant de stocker **de manière immuable** des données utiles au package manager `nix` et à `NixOS` (comme les dérivations, les sources de packages, ...). On peut découper le `Nix Store` en plusieurs parties, les principales étant le dossier `/nix/store` en local, ou les différents caches contenant des binaires pour éviter la recompilation de tous les packages (le principal étant situé à https://cache.nixos.org).
+
+Il est important de noter que **`/nix/store` est un dossier monté en lecture seule et est visible par tous les utilisateurices**. Il est donc crucial de **ne jamais laisser apparaître de mot de passe en clair dans cette configuration**, car celui-ci serait alors lisible par tous les utilisateurices ayant accès à la machine. L'utilisation de `Sops` (voir [secrets/README.md](secrets/README.md)) permet de palier ce problème en introduisant des secrets chiffrés uniquement accessibles pour les machines devant y avoir accès et pour les nounous.
+
+### Flakes
+
+Le fichier [`flake.nix`](flake.nix) dénote de tous les autres fichiers de cette configuration : celui-ci est une `flake`, à savoir l'unité de permettant de packager du code `nix` de manière reproducible. Plus simplement, dans notre cas, cette `flake` contient toutes les sources utilisées dans la configuration pour pouvoir être évaluée, ainsi que toutes les sorties, à savoir les configurations de toutes les machines, ainsi que les shells de développement (voir [la partie sur les `devshells`](TODO)).
+