More docs

docs/config.nix

@@ -0,0 +1,57 @@
+{ config, ... }:
+
+{
+  site_name = "HPC @ HS-Fulda";
+  site_description = ''
+    User documentation for high performance cluster on University of Applied Sciences Fulda
+  '';
+  site_url = "http://${config.networking.domain}/";
+
+  use_directory_urls = false;
+  strict = true;
+
+  repo_url = "https://gogs.informatik.hs-fulda.de/hpc/nixcfg.git";
+
+  docs_dir = ./content;
+
+  theme = {
+    name = "readthedocs";
+    locale = "de";
+    prev_next_buttons_location = "none";
+    highlightjs = true;
+    hljs_languages = [
+      "bash"
+      "yaml"
+      "rust"
+    ];
+  };
+
+  markdown_extensions = [
+    "extra"
+    "admonition"
+  ];
+
+  plugins = [
+    "search"
+  ];
+
+  extra = {
+    "manager"."host" = config.networking.domain;
+  };
+
+  nav = [
+    { "Start" = "index.md"; }
+    { "Erste Schritte" = "first_steps.md"; }
+    { "Nutzung" = "usage.md"; }
+    { "Software" = "environment.md"; }
+    { "Daten" = "storage.md"; }
+    { "Best Practices" = "best_practice.md"; }
+    { "Hilfe" = "support.md"; }
+    {
+      "Internes" = [
+        { "Deployment" = "internal/deployment.md"; }
+        { "Netzwerk" = "internal/network.md"; }
+      ];
+    }
+  ];
+}

docs/content/first_steps.md

@@ -6,7 +6,7 @@ Willkommen zum Abschnitt "Erste Schritte" der Benutzer-Dokumentation für den Le
 
 Bevor Sie mit dem Lehr-HPC Cluster arbeiten können, müssen Sie Zugang beantragen. Hier sind die Schritte, um den Zugang zu erhalten:
 
-1. Besuchen Sie die Webseite des Lehr-HPC Clusters: https://lehr-hpc-cluster-university.edu.
+1. Besuchen Sie die Webseite des Lehr-HPC Clusters: {{ config.site_url }}.
 1. Suchen Sie nach dem Abschnitt "Zugang beantragen" oder ähnlichem.
 1. Füllen Sie das Zugangsformular aus, das Ihre Kontaktdaten, den Grund für den Zugang und möglicherweise andere Informationen abfragt.
 1. Senden Sie den Antrag ab und warten Sie auf die Bestätigung Ihrer Zugangsberechtigung. Dies kann einige Zeit in Anspruch nehmen.
@@ -16,11 +16,11 @@ Bevor Sie mit dem Lehr-HPC Cluster arbeiten können, müssen Sie Zugang beantrag
 Sobald Ihr Zugang genehmigt wurde, können Sie sich auf dem Lehr-HPC Cluster anmelden:
 
 1. Öffnen Sie ein Terminal auf Ihrem Computer.
-1. Verwenden Sie den Befehl ssh in Verbindung mit Ihrer zugewiesenen Benutzer-ID und der Cluster-Adresse, um sich anzumelden:
+1. Verwenden Sie den Befehl ssh in Verbindung mit Ihrer fd-Nummer und der Cluster-Adresse, um sich anzumelden:
 ```bash
-ssh benutzername@lehr-hpc-cluster-university.edu
+ssh fd-nummer@{{ config.extra.manager.host }}
 ```
-  Geben Sie Ihr Passwort ein, wenn Sie dazu aufgefordert werden.
+1. Geben Sie Ihr Passwort ein, wenn Sie dazu aufgefordert werden.
 
 ## Grundlegende Begriffe kennenlernen
 Um erfolgreich mit dem Cluster zu arbeiten, sollten Sie einige grundlegende HPC-Konzepte verstehen:
@@ -49,7 +49,7 @@ Dieses Skript führt einen einfachen Befehl aus und wartet dann 60 Sekunden.
 
 * Laden Sie die Datei auf den Cluster hoch, beispielsweise mit dem Befehl scp:
 ```bash
-scp testjob.sh benutzername@lehr-hpc-cluster-university.edu:~/testjob.sh
+scp testjob.sh fd-nummer@{{ config.extra.manager.host }}:~/testjob.sh
 ```
 
 * Verbinden Sie sich erneut mit dem Cluster und reichen Sie den Testjob ein:
@@ -57,9 +57,12 @@ scp testjob.sh benutzername@lehr-hpc-cluster-university.edu:~/testjob.sh
 sbatch testjob.sh
 ```
 
-* Überwachen Sie den Status des Jobs mit dem Befehl `squeue -u benutzername` und sehen Sie zu, wie er ausgeführt wird.
+* Überwachen Sie den Status des Jobs mit dem Befehl `squeue -u $USER` und sehen Sie zu, wie dieser ausgeführt wird.
 
 Herzlichen Glückwunsch! Sie haben Ihren ersten Testjob auf dem Lehr-HPC Cluster erfolgreich eingereicht.
-Nächste Schritte
 
-Sie haben nun erfolgreich die ersten Schritte auf dem Lehr-HPC Cluster unternommen! Als nächstes können Sie sich mit fortgeschritteneren Themen wie der Einreichung komplexerer Aufträge und der Nutzung spezifischer Software vertraut machen. Werfen Sie einen Blick auf die anderen Abschnitte dieser Dokumentation, um Ihr Wissen zu vertiefen.
+## Nächste Schritte
+
+Sie haben nun erfolgreich die ersten Schritte auf dem Lehr-HPC Cluster unternommen!
+Als nächstes können Sie sich mit fortgeschritteneren Themen wie der Einreichung komplexerer Aufträge und der Nutzung spezifischer Software vertraut machen.
+Werfen Sie einen Blick auf die anderen Abschnitte dieser Dokumentation, um Ihr Wissen zu vertiefen.

docs/content/index.md

@@ -4,7 +4,6 @@ Herzlich Willkommen zur Benutzer-Dokumentation des High-Performance Computing (H
 Herzlich willkommen zur offiziellen Benutzer-Dokumentation unseres High-Performance Computing (HPC) Clusters.
 Diese Dokumentation soll Ihnen dabei helfen, das volle Potenzial unseres Clusters auszuschöpfen, um komplexe Berechnungen und wissenschaftliche Simulationen effizient durchzuführen.
 
-
 ## Was ist ein HPC Cluster?
 Ein HPC Cluster ist ein leistungsstarkes Netzwerk von miteinander verbundenen Computern, die gemeinsam komplexe Berechnungen und rechenintensive Aufgaben bewältigen können.
 Unser Cluster wurde entwickelt, um den Umgang mit einem HPC Cluster in der Lehre zu vermittel und Forscherinnen und Forschern aus verschiedenen Disziplinen die Möglichkeit zu bieten, Simulationen durchzuführen, Datenanalysen durchzuführen und innovative Forschungsprojekte zu realisieren.

docs/content/internal/deployment.md

@@ -0,0 +1,79 @@
+# Infrastructure Deployment
+
+The whole cluster infrastructure is build using [NixOS](https://nixos.org/).
+The configuration repository is hosted at {{ config.repo_url }} and is deployed using [colmena](https://github.com/zhaofengli/colmena).
+
+## Building the configuration
+To build the configuration, as system with [Nix](https://nix.dev/install-nix) installed is required.
+
+To activate the environment, run `nix develop` inside the configuration folder.
+This will fetch all required build dependecies and makes them available in the environment.
+
+Building the whole configuration is as easy as running:
+```
+colmana build --verbose --show-trace
+```
+*Go grap a coffee, this can take a while*
+
+## Deploying
+> Note: Deployment requires SSH access as the `root` user to all machines.
+
+To deploy a configuration change or updates to the cluster, run the following command:
+```
+colmena apply switch
+```
+
+### Using the manager as a SSH jump host
+SSH access to the nodes is limited.
+Therefore it the manager system can be used as a jump host.
+To do so, add the following lines to your local `~/.ssh/config` file (before the the `Host *` entry):
+```
+Host 10.32.47.1??
+  IdentitiesOnly yes
+  ProxyJump root@10.32.47.10
+```
+
+## Updating
+Updating all systems can be done by running the following command in the configuration repository:
+```
+nix flake update
+```
+
+This will update all dependencies including the NixOS operation system.
+
+After doing the update, the changed config (with the updated dependencies) must be [deployed](#deploying).
+
+## Gather node information
+The configuration repository relies on some information gathered from the machines itself.
+After bootstrapping a machine, these information need to be gathered from the machines into the configuration repository.
+
+To gather there data, run the following command:
+```
+./gather.sh
+```
+
+## Secret management
+The config repository contains several secrets which are secured by [sops](https://github.com/getsops/sops) and the according [Nix integration](https://github.com/Mic92/sops-nix).
+
+To edit a config file, run the following command:
+```
+sops <path/to/secrets/file>
+```
+
+This requires the editor to have its PGP-key fingerprint be part of the `adminKeys` list in `sops.nix`.
+
+Altering the list requires one of the previous members to [update the keys](#update-keys).
+
+### Update keys
+Whenever a key, either the SSH key of a machine or the PGP key of an administrator, changes, the secret files need updating.
+To do so, run the following command:
+```
+find -name "secrets.yaml" -or -path "*/secrets/**" -type f -exec 'sops updatekeys {}'
+```
+
+## Bootstrapping a node
+Compute nodes can be bootstrapped using PXE boot.
+The manager will provide a touchless boot image which will install the node with the current deployment automatically.
+Booting the node from PXE (network boot) is enough to activate the bootstrapping process.
+
+After bootstrapping a node, make sure to [gather the node data](#gather-node-information) and [update the secret keys](#update-keys).

docs/default.nix

@@ -1,18 +0,0 @@
-{ stdenv
-, mkdocs
-, ...
-}:
-
-stdenv.mkDerivation {
-  name = "docs";
-
-  preferLocalBuild = true;
-  allowSubstitutes = false;
-
-  src = ./.;
-
-  buildCommand = ''
-    cd "$src"
-    ${mkdocs}/bin/mkdocs build --site-dir "$out"
-  '';
-}

docs/mkdocs.yaml

@@ -1,37 +0,0 @@
-site_name: HPC @ HS-Fulda
-site_description: User documentation for high performance cluster on University of Applied Sciences Fulda
-site_url: https://docs.hpc.informatik.hs-fulda.de/
-site_dir: public
-use_directory_urls: false
-strict: true
-repo_url: https://gogs.informatik.hs-fulda.de/hpc/nixcfg.git
-docs_dir: content
-
-theme:
-  name: readthedocs
-  locale: de
-  prev_next_buttons_location: none
-  highlightjs: true
-  hljs_languages:
-    - bash
-    - yaml
-    - rust
-
-markdown_extensions:
-  - extra
-  - admonition
-
-plugins:
-  - search
-
-nav:
-  - Start: index.md
-  - Erste Schritte: first_steps.md
-  - Nutzung: usage.md
-  - Software: environment.md
-  - Daten: storage.md
-  - Best Practices: best_practice.md
-  - Hilfe: support.md
-  - Internes:
-    - Netzwerk: internal/network.md
-

docs/module.nix

@@ -0,0 +1,19 @@
+{ pkgs, config, lib, ... }:
+
+with lib;
+
+let
+  mkdocsConfig = import ./config.nix {
+    inherit config lib;
+  };
+
+  mkdocsConfigYaml = pkgs.writeText "mkdocs.yaml" (generators.toYAML { } mkdocsConfig);
+
+in
+{
+  system.build.docs = pkgs.runCommand "docs" { } ''
+    ${pkgs.mkdocs}/bin/mkdocs build \
+      --site-dir "$out" \
+      --config-file "${mkdocsConfigYaml}"
+  '';
+}

docs/result

@@ -1 +0,0 @@
-/nix/store/8v3r668x18fl49yx2s41yzs0qx9cn24d-docs

machines/manager/default.nix

@@ -19,6 +19,7 @@ with lib;
     ./rdma.nix
     ./mpi.nix
     ./slurm.nix
+    ./docs.nix
   ];
 
   deployment = {

machines/manager/docs.nix

@@ -1,16 +1,22 @@
-{ pkgs, lib, ... }:
+{ config, pkgs, lib, ... }:
 
 with lib;
 
-let
-  docs = pkgs.callPackage ../../docs { };
-
-in
 {
+  imports = [
+    ../../docs/module.nix
+  ];
+
   services.nginx = {
     virtualHosts = {
-      "docs.${config.networking.domain}" = {
-        locations."/".root = docs;
+      "${config.networking.domain}" = {
+        default = true;
+
+        serverAliases = [
+          "doku.${config.networking.domain}"
+        ];
+
+        locations."/".root = config.system.build.docs;
       };
     };
   };