docs: refactor

This commit does a lot of things at ones:

* introduce a temporary logo to unbreak the image reference in the docs
* introduce a getting started documentation
* introduce a proper user guide. It's still missing a lot of things.
* rename the various categories of modules to be clearer.
* complete the missing module references.
* add a tiny FAQ

README.md

@@ -15,16 +15,26 @@ example to deploy a GitHub Action runner on Hetzner:
 
 ```nix
 {
+  description = "My machines flakes";
   inputs = {
     srvos.url = "github:numtide/srvos";
+    # Use the version of nixpkgs that has been tested to work with SrvOS
+    nixpkgs.follows = "srvos/nixpkgs";
   };
-  outputs = { srvos, nixpkgs, ... }: {
+  outputs = { self, nixpkgs, srvos }: {
     nixosConfigurations.myHost = nixpkgs.lib.nixosSystem {
       system = "x86_64-linux";
       modules = [
-        srvos.nixosModules.common
+        # This machine is a server
+        srvos.nixosModules.server
+        # Deployed on the AMD Hetzner hardware
         srvos.nixosModules.hardware-hetzner-amd
+        # Configured with extra terminfos
+        srvos.nixosModules.mixins-terminfo
+        # And designed to run the GitHub Actions runners
         srvos.nixosModules.roles-github-actions-runner
+        # Finally add your configuration here
+        ./myHost.nix
       ];
     };
   };
@@ -39,7 +49,7 @@ To improve the documentation, take a look at the `./docs` folder. You can also r
 
 ## Contributing
 
-Contributions are always welcome.
+Contributions are always welcome!
 
 ## License
 

docs/faq.md

@@ -0,0 +1,15 @@
+Some questions and answers that haven't been integrated in the documentation yet.
+
+## What version of NixOS should I use?
+
+SrvOS is currently only tested against `nixos-unstable`. SrvOS itself is automatically updated and tested against the latest version of that channel once a week.
+
+If you want to make sure to use a tested version, use the "follows" mechanims of Nix flakes to pull the same version as the one of SrvOS:
+
+```nix
+{
+  inputs.srvos.url = "github:numtide/srvos";
+  # Use the version of nixpkgs that has been tested to work with SrvOS
+  inputs.nixpkgs.follows = "srvos/nixpkgs";
+}
+```

docs/getting_started.md

@@ -0,0 +1,52 @@
+# Getting Started with SrvOS
+
+This project is designed to work in combination with [NixOS](https://nixos.org).
+
+In this documentation, we expect the reader to be already familiar with the base operating system, and introduce how to compose it with our own extensions.
+
+## Finding your way around
+
+This project exports four big categories of NixOS modules which are useful to define a server configuration:
+
+* Machine type - these are high-level settings that define the machine type (Eg: common, server or desktop). Only one of those would be included.
+* Machine hardware - these define hardware-releated settings for well known hardware. Only one of those would be included. (eg: AWS EC2 instances).
+* Machine role - theses take over a machine for a specific role. Only one of those would be included. (eg: GitHub Actions runner)
+* Configuration mixins - these define addons to be added to the machine configuration. One or more can be added.
+
+## Example
+
+Combining all of those together, here is how your `flake.nix` might look like, to deploy a GitHub Actions runner on Hetzner:
+
+```nix
+{
+  description = "My machines flakes";
+  inputs = {
+    srvos.url = "github:numtide/srvos";
+    # Use the version of nixpkgs that has been tested to work with SrvOS
+    nixpkgs.follows = "srvos/nixpkgs";
+  };
+  outputs = { self, nixpkgs, srvos }: {
+    nixosConfigurations.myHost = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        # This machine is a server
+        srvos.nixosModules.server
+        # Deployed on the AMD Hetzner hardware
+        srvos.nixosModules.hardware-hetzner-amd
+        # Configured with extra terminfos
+        srvos.nixosModules.mixins-terminfo
+        # And designed to run the GitHub Actions runners
+        srvos.nixosModules.roles-github-actions-runner
+        # Finally add your configuration here
+        ./myHost.nix
+      ];
+    };
+  };
+}
+```
+
+## Continue
+
+Now that we have gone over the high-level details, you should have an idea of how to use this project.
+
+To dig further, take a look at the [User guide](user_guide.md).

docs/github_actions_runner.md

@@ -1,4 +1,4 @@
-# Installing a GitHub Action Runner
+# GitHub Actions Runner
 
 GitHub Action Runners are processes that execute the automated jobs you specify in your GitHub Actions workflows. These runners can be hosted on GitHub-hosted infrastructure or your infrastructure. Self-hosted runners run for your project only and are available at no additional cost.
 

docs/help.md

@@ -0,0 +1,9 @@
+# Getting help
+
+## Bugs
+
+If you found a bug, feel free to create a new [GitHub issue](https://github.com/numtide/srvos/issues/new/choose).
+
+## Feature development
+
+For dedicated help or priority support, we are also available. Here is the best place to contact us: <https://numtide.com/contact/>.

docs/index.md

@@ -1,38 +1,7 @@
-# Hello
+# Home
 
-SrvOS is a collection of opinionated and sharable NixOS configurations.
+Welcome!
 
-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.
+SrvOS is a collection of NixOS modules that are optimized for servers. They includes many lessons that we gained over the years while deploying servers for our customers. As we like to share, we hope that this project will be useful to you.
 
-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.
+To get started, start by reading the [introductory tutorial](getting_started.md), then check the [User Guide](user_guide.md) for more information.

docs/nixos/general.md

@@ -1,25 +0,0 @@
-## General
-
-Used to define the type of machine.
-
-- `server`:
-  - Use this for headless systems that are remotely managed via ssh
-  - Includes everything from common
-  - Disables desktop features like sound
-  - Defaults to UTC
-  - Enables ssh
-  - Configures watchdog for reboot
-  - Sets up sudo without password
-  - ...
-- `desktop`:
-  - Mostly based on common but also includes some optimization for useful for interactive usage
-- `common`:
-  - Use if you are unsure if your nixos module will be used on server or desktop
-  - Better nix-daemon defaults
-  - Better serial console support
-  - Colored package diffs on nixos-rebuild
-  - Use systemd in initrd by default and networkd as a backend for the
-    Networking module
-  - Do not block on networkd/networkmanager's online target
-  - Better zfs defaults
-  - Add well-known ssh git ssh keys to the git configuration

docs/nixos/hardware.md

@@ -1,8 +1,29 @@
-## Hardware
+Hardware modules are used to configure NixOS for well known hardware.
 
-NixOS hardware configurations that we know about.
+We expect only one hardware module to be imported per NixOS configuration.
 
-- `hardware-amazon`: Amazon AWS virtual machines
-- `hardware-hetzner-cloud`: Hardware and network defaults for Hetzner virtual machine
-- `hardware-hetzner-amd`: Hardware and network defaults for Hetzner bare-metal servers for AMD and Intel cpus.
-- `hardware-hetzner-intel`: "
+Here are some of the hardwares that are supported:
+
+### `nixosModules.hardware-amazon`
+
+Hardware configuration for <https://aws.amazon.com/ec2> instances.
+
+The main difference here is that the default userdata service is replaced by cloud-init.
+
+### `nixosModules.hardware-hetzner-cloud`
+
+Hardware configuration for <https://www.hetzner.com/cloud> instances.
+
+The main difference here is that cloud-init is enabled.
+
+### `nixosModules.hardware-hetzner-online-amd`
+
+Hardware configuration for <https://www.hetzner.com/dedicated-rootserver> bare-metal AMD servers.
+
+Introduces some workaround for the perticular IPv6 configuration that Hetzner has.
+
+### `nixosModules.hardware-hetzner-online-intel`
+
+Hardware configuration for <https://www.hetzner.com/dedicated-rootserver> bare-metal Intel servers.
+
+Introduces some workaround for the perticular IPv6 configuration that Hetzner has.

docs/nixos/mixins.md

@@ -1,10 +1,23 @@
-## Mixins
-
 Config extensions for a given machine.
 
-- `mixins-cloud-init` enables [cloud-init](https://cloud-init.io)
-- `mixins-systemd-boot` configure systemd-boot as bootloader
-- `mixins-telegraf` enables a generic telegraf configuration. See [Mic's dotfiles](https://github.com/Mic92/dotfiles/blob/master/nixos/eva/modules/prometheus/alert-rules.nix)
-  for monitoring rules targeting this telegraf configuration.
-- `mixins-nginx` recommended nginx settings
-- `mixins-trusted-nix-caches` list of trust-worthy public binary caches
+One or more can be included per NixOS configuration.
+
+### `nixosModules.mixins-cloud-init`
+
+Enables [cloud-init](https://cloud-init.io)
+
+### `nixosModules.mixins-systemd-boot`
+
+Configure systemd-boot as bootloader.
+
+### `nixosModules.mixins-telegraf`
+
+Enables a generic telegraf configuration. See [Mic's dotfiles](https://github.com/Mic92/dotfiles/blob/master/nixos/eva/modules/prometheus/alert-rules.nix) for monitoring rules targeting this telegraf configuration.
+
+### `nixosModules.nginx`
+
+Configure Nginx with recommended settings. Is quite useful when using nginx as a reverse-proxy on the machine to other services.
+
+### `nixosModules.mixins-trusted-nix-caches`
+
+Add the common list of public nix binary caches that we trust.

docs/nixos/role.md

@@ -0,0 +1,13 @@
+Roles are special types of NixOS modules that are designed to take over a machine configuration.
+
+We assume that only one role is assigned per machine.
+
+By making this assumption, we are able to make deeper change to the machine configuration, without having to worry about potential conflicts with other roles.
+
+### GitHub Actions runner (`nixosConfiguration.roles-github-actions-runner`)
+
+Dedicates the machine to becoming a cluster of GitHub Actions runners. 
+
+### Nix Remote builder (`nixosConfiguration.roles-nix-remote-builder`)
+
+Dedicates the machine to acting as a remote builder for Nix. The main use-case we have is to add more build capacity to the GitHub Actions runners, in a star fashion.

docs/nixos/type.md

@@ -0,0 +1,37 @@
+Those high-level modules are used to define the type of machine.
+
+We expect only one of those to be imported per NixOS configuration.
+
+### Common (`nixosModules.common`)
+
+Use this module if you are unsure if your nixos module will be used on server or desktop.
+
+- Better nix-daemon defaults
+- Better serial console support
+- Colored package diffs on nixos-rebuild
+- Use systemd in initrd by default and networkd as a backend for the
+  Networking module
+- Do not block on networkd/networkmanager's online target
+- Better zfs defaults
+- Add ssh host keys to well-known Git servers (eg: github)
+- Enable sudo for @wheel users.
+- ...
+
+### Server (`nixosModules.server`)
+
+Use this for headless systems that are remotely managed via ssh.
+
+- Includes everything from common
+- Enables OpenSSH server
+- Disables desktop features like sound
+- Defaults to UTC
+- Configures watchdog for reboot
+- Sets up sudo without password
+- ...
+
+### Desktop (`nixosModules.desktop`)
+
+Despite this project being about servers, we wanted to dogfood the common module.
+
+- Includes everything from common
+- Use pipewire instead of PulseAudio.

docs/user_guide.md

@@ -0,0 +1,3 @@
+# User guide
+
+This part of the documentation provides reference documentation for day-to-day users. Use the navigation menu to jump around.

mkdocs.yml

@@ -2,7 +2,7 @@ INHERIT: !ENV MKDOCS_NUMTIDE_THEME
 
 ### Site metadata ###
 
-site_name: srvos
+site_name: SrvOS
 site_description: NixOS profiles for servers
 site_url: https://numtide.github.io/srvos/
 repo_name: 'numtide/srvos'
@@ -12,12 +12,19 @@ edit_uri: edit/main/docs
 ### Navigation ###
 
 nav:
-  - Hello: index.md
-  - NixOS modules:
-      - General: nixos/general.md
-      - Hardware: nixos/hardware.md
-      - Mixins: nixos/mixins.md
-      - Roles:
-        - GitHub Action Runner: nixos/roles/github_actions_runner.md
-  - Installation:
-      - Hetzner Cloud: installation/hetzner_cloud.md
+  - Home: index.md
+
+  - Getting started: getting_started.md
+  - User guide:
+    - Intro: user_guide.md
+    - NixOS modules:
+      - Machine type: nixos/type.md
+      - Machine hardware: nixos/hardware.md
+      - Machine role: nixos/role.md
+      - Configuration mixins: nixos/mixins.md
+    - Roles:
+      - GitHub Action Runner: github_actions_runner.md
+    - Installation:
+        - Hetzner Cloud: installation/hetzner_cloud.md
+    - FAQ: faq.md
+  - Getting help: help.md