Browse Source

More docs

main
Dustin Frisch 1 year ago
parent
commit
dae245e5e6
No known key found for this signature in database GPG Key ID: B4C3BF012D9B26BE
  1. 57
      docs/config.nix
  2. 19
      docs/content/first_steps.md
  3. 1
      docs/content/index.md
  4. 79
      docs/content/internal/deployment.md
  5. 18
      docs/default.nix
  6. 37
      docs/mkdocs.yaml
  7. 19
      docs/module.nix
  8. 1
      docs/result
  9. 1
      machines/manager/default.nix
  10. 20
      machines/manager/docs.nix

57
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"; }
];
}
];
}

19
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.

1
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.

79
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).

18
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"
'';
}

37
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

19
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}"
'';
}

1
docs/result

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

1
machines/manager/default.nix

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

20
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;
};
};
};

Loading…
Cancel
Save