more docs, things are still pretty messy

README.md

@@ -31,13 +31,15 @@ example to deploy a GitHub Action runner on Hetzner:
 }
 ```
 
-For more usage and documentation in general, see <https://numtide.github.io/srvos/>.
+## Documentation
 
-## Known limitations
+The [Documentation](https://numtide.github.io/srvos/) website shows more general usage, how to install SrvOS, etc...
 
-The current modules are only tested to work on the NixOS unstable release.
-When updating srvos, we commend that you follow the same pin of nixpkgs that
-is being used by this project.
+To improve the documentation, take a look at the `./docs` folder. You can also run `nix run .#docs.serve` to start a preview server on <http://localhost:3000>.
+
+## Contributing
+
+Contributions are always welcome.
 
 ## License
 

docs/SUMMARY.md

@@ -6,4 +6,6 @@
     - [Hardware](./modules/hardware.md)
     - [Mixins](./modules/mixins.md)
     - [Roles](./modules/roles.md)
+- [Installation](./installation.md)
+    - [Hetzner Cloud](./installation/hetzner_cloud.md)
 - [Design](./design.md)

docs/hello.md

@@ -1,5 +1,38 @@
 # Hello
 
-Welcome to the new docs website.
+SrvOS is a collection of opinionated and sharable NixOS configurations.
 
-For now it's mostly an information dump that needs to be sorted out.
+As we learn more about NixOS in various deployments, we end up re-writing the same modules and configs. This is a way for us to speed up and share our setups.
+
+Instead of supporting everything, our goal is to target certain verticals and make the support super smooth there.
+
+## Quick Usage
+
+Add `srvos` to your `flake.nix` to augment your NixOS configuration. For
+example to deploy a GitHub Action runner on Hetzner:
+
+```nix
+{
+  inputs = {
+    srvos.url = "github:numtide/srvos";
+  };
+  outputs = { srvos, nixpkgs, ... }: {
+    nixosConfigurations.myHost = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        srvos.nixosModules.common
+        srvos.nixosModules.hardware-hetzner-amd
+        srvos.nixosModules.roles-github-actions-runner
+      ];
+    };
+  };
+}
+```
+
+## Technologies
+
+SrvOS is a thin wrapper, sitting on the shoulder of others:
+
+* [Nix and NixOS](https://nixos.org) of course.
+* [nixos-anywhere](https://github.com/numtide/nixos-anywhere) to bootstrap new systems.
+* [disko](https://github.com/nix-community/disko) to partition and configure disks.

docs/installation.md

@@ -0,0 +1,3 @@
+# Installation
+
+* [Hetzner Cloud](./installation/hetzner_cloud.md)

docs/installation/hetzner_cloud.md

@@ -0,0 +1,58 @@
+# Hetzner Cloud installation
+
+> ⚠️ Only works with VMs that have more than 2GB of RAM.
+
+> ⚠️ This document reflects more of an ideal than reality right now.
+
+1. Create the VM in Hetzner Cloud, get the IP, IPv6, set the SSH public key.
+2. Create a new NixOS configuration in your flake:
+
+```nix
+{
+  inputs.nixos-anywhere.url = "github:numtide/nixos-anywere";
+  inputs.srvos.url = "github:numtide/srvos"; 
+  inputs.disko.url = "github:nix-community/disko";
+
+  outputs = { self, nixos-remote, srvos, disko, nixpkgs }: {
+    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [{ 
+        imports = [ 
+          srvos.nixosModules.hardware-hetzner-cloud
+          srvos.nixosModules.server
+
+          # Are those together?
+          disko.nixosModules.disko
+          srvos.diskoModules.disk-layout-single-v1
+        ];
+        networking.hostName = "my-host";
+        # FIXME: Hetzner Cloud doesn't provide us with that configuration
+        systemd.network.networks."10-uplink".networkConfig.Address = "2a01:4f9:c010:52fd::1/128";
+      }];
+    };
+    # TODO other $systems
+    devShells.x86_64-linux.default = with nixpkgs.legacyPackages.x86_64-linux; mkShellNoCC {
+      packages = [
+        # TODO: add nixos-rebuild as a package
+        nixos-anywhere.packages.x86_64-linux.default
+      ];
+    };
+  };
+}
+```
+
+3. Update the hostname and IPv6 address in the config.
+
+4. Bootstrap the NixOS deployment:
+   ```console
+   $ nix develop
+   $ nixos-anywhere --flake .#my-host --target <ip>
+   ```
+
+🎉
+
+5. Pick a nixos deployment tool of your choice! Eg:
+
+   ```
+   $ nixos-rebuild --flake .#my-host --target <ip> switch
+   ```