[docs] make readme the index

still most of it is quite out of date...

doc/src/Index.md

@@ -1 +1,82 @@
-# Index
+# malobeo infrastructure
+
+this repository nxios configurations of the digital malobeo infrastructure. it should be used to setup, test, build and deploy different hosts in a reproducible manner.
+
+the file structure is based on this [blog post](https://samleathers.com/posts/2022-02-03-my-new-network-and-deploy-rs.html)
+
+### deploying configuration
+#### local deployment
+``` shell
+nixos-rebuild switch --use-remote-sudo
+```
+
+#### remote deployment
+you need the hostname and ip address of the host:
+``` shell
+ nixos-rebuild switch --flake .#<hostname> --target-host root@<ip_address> --build-host localhost
+```
+
+in this case 'localhost' is used as buildhost which can be usefull if the target host is low systemresources
+
+
+## development
+
+### requirements
+we use flake based configurations for our hosts. if you want to build configurations on you own machine you have to enable flakes first by adding the following to your *configuration.nix* or *nix.conf*
+``` nix
+nix.extraOptions = ''
+  experimental-features = nix-command flakes
+'';
+```
+
+More information about flakes can be found [here](https://nixos.wiki/wiki/Flakes)
+
+### dev shell
+a development shell with the correct environment can be created by running ```nix develop ```
+
+If you're using direnv you can add flake support by following those steps: [link](https://nixos.wiki/wiki/Flakes#Direnv_integration)
+
+### build a configuration
+
+to build a configuration run the following command (replace ```<hostname>``` with the actual hostname):
+
+``` shell
+nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel
+```
+
+### building raspberry image
+
+for the raspberry it is possible to build the whole configuration as an sd-card image which then can be flashed directly. more information about building arm on nixos can be found [here](https://nixos.wiki/wiki/NixOS_on_ARM).
+
+to be able to build the image you need to enable qemu emulation on the machine you are building with. therefore it is necessary to add the following to your configuration.nix:
+
+``` nix
+boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
+```
+
+then you can build the image with:
+
+``` shell
+nix build .#nixosConfigurations.rpi1_base_image.config.system.build.sdImage
+```
+
+### run a configuration as vm
+
+to run a vm we have to build it first using the following command (replace ```<hostname>``` with the actual hostname):
+
+``` shell
+nix build .#nixosConfigurations.<hostname>.config.system.build.vm
+```
+
+afterwards run the following command to start the vm:
+
+``` shell
+./result/bin/run-<hostname>-vm
+```
+
+### documentation
+
+for documentation we currently just use README.md files.
+
+the devshell provides the python package ['grip'](https://github.com/joeyespo/grip) which can be used to preview different README.md files in the browser.
+the usage is simple, just run ```grip``` in the same folder as the README.md you wanna preview. then open your browser at ```http://localhost:6419 ```.