docs: function of all files documented

README.md

@@ -2,25 +2,28 @@
 
 ## Structure
 
-- `hosts/`
-
-  - `common/` shared configuration
-
-    - `core/` configuration that is shared across all machines. (base setup, ssh, ...)
-
-  - `<hostname>/`
-
+- `hosts/` contains configuration for all hosts.
+  - `common/` shared configuration. Hosts will include what they need from here.
+    - `core/` configuration that is shared across _all_ machines. (base setup, ssh, ...)
+    - `dev/` configuration for development machines
+    - `graphical/` configuration for graphical setup
+    - `hardware/` configuration for various hardware components
+    - `<something>.nix` commonly required configuration for `<something>`
+  - `<hostname>/` configuration for `<hostname>`
 	- `secrets/` Local secrets for this host. Still theoretically accessible by other hosts, but owned by this one.
-
 	  - `secrets.nix.age` Repository-wide local secrets. Decrypted on import via `builtins.extraBuiltins.rageImportEncrypted`.
-	  - `host.pub` This host's public key.Repository-wide local secrets. Decrypted on import via `builtins.extraBuiltins.rageImportEncrypted`.
-
-  - `nom/`
-
+	  - `host.pub` This host's public key. Used for agenix rekeying.
+	- `default.nix` The actual system definition. Follow the imports from there to see what it entails.
+	- `meta.nix` Determines the type and architecture of this system, and some other optional meta information. Used e.g. by `nix/colmena.nix` to know which hosts are NixOS and which are home-manger only.
+	- `fs.nix` Filesystem setup.
+	- `net.nix` Networking setup.
+  - `nom/` - My laptop and main development machine
+  - `ward/` - ODROID H3, energy efficient SBC. Used as a firewall betwenn my ISP and internal home network. Hosts some lightweight services using full KVM virtual machines.
+  - `envoy/` - Hetzner Cloud server. Primarily used as my mailserver and VPN provider.
+  - `zackbiene/` - ODROID N2+. Hosts IoT and Home Automation stuff and fully isolates that from my internal network.
+  - not yet ready for publicized: my main development machine, powerful home server, some services ... (still in transition from gentoo :/)
 - `modules/` additional NixOS modules that are not yet upstreamed.
-
 - `nix/` library functions and plumbing
-
   - `apps.nix` Additional runnable actions for this flake (**WIP:** infrastructure graph renderer)
   - `checks.nix` pre-commit-hooks for this repository
   - `colmena.nix` Setup for distributed deployment using colmena (actually defines all NixOS hosts)
@@ -30,20 +33,25 @@
   - `hosts.nix` Wrapper that extracts all defined hosts from `hosts/`
   - `overlays/**` Local overlay packages. Subject for removal.
   - `overlay.nix` Overlay defintions
-  - `overlay.nix` Overlay defintions
   - `rage-decrypt.sh` Auxiliary script for repository-wide secrets
   - `secrets.nix` Helper to access repository-wide secrets, used by colmena.nix
-
 - `secrets/` Global secrets and age identities
-
   - `secrets.nix.age` Repository-wide global secrets. Decrypted on import via `builtins.extraBuiltins.rageImportEncrypted`.
-  - `backup.pub` Backup age identity in case I lose my YubiKey
-  - `yk1-nix-rage.pub` Master YubiKey split-identity
-
+  - `backup.pub` Backup age-identity in case I ever lose my YubiKey or it breaks.
+  - `yk1-nix-rage.pub` Master YubiKey split-identity. Used as a key-grab.
 - `pkgs/` Custom packages and scripts
-
 - `users/` User account configuration via home-manager. Imported by each host separately.
 
+## How-To
+
+#### Add and deploy new machine
+
+...
+
+#### New secret
+
+...
+
 ## Stuff
 
 This is my personal nix config.
@@ -59,7 +67,7 @@ all commands using these extra parameters, or permanently add the following the
 2. Run all commands with `--option plugin-files "$NIX_PLUGINS"/lib/nix/plugins --option extra-builtins-file ./nix/extra-builtins.nix`
    or permantently
 
-	```toml
+	```ini
 	plugin-files = <copy path from $NIX_PLUGINS>/lib/nix/plugins
 	extra-builtins-file = /path/to/nix-config/nix/extra-builtins.nix
 	```