From c9dafa93b41376bdbc0b98de3e823267f69e3d92 Mon Sep 17 00:00:00 2001 From: Max Melchert <maximilian.melchert@stud.hs-bochum.de> Date: Fri, 14 Mar 2025 17:43:45 +0100 Subject: [PATCH] feat: add hidden details text in README --- src/makefile/README.md | 171 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 162 insertions(+), 9 deletions(-) diff --git a/src/makefile/README.md b/src/makefile/README.md index edde22c..1e351a8 100644 --- a/src/makefile/README.md +++ b/src/makefile/README.md @@ -124,10 +124,34 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC ### Server -| Variable | Verwendung | Beispiel | -| :------------ | :---------------- | :----------------- | -| `SERVER_USER` | Server: User Name | `mmustermann` | -| `SERVER_HOST` | Server: Host Name | `hyrican-1-extern` | +| Variable | Verwendung | Beispiel | +| :------------ | :--------------- | :----------------- | +| `SERVER_USER` | Server: Username | `mmustermann` | +| `SERVER_HOST` | Server: Hostname | `hyrican-1-extern` | + +<details> +<summary>Details anzeigen</summary> + +#### `SERVER_USER` + +> Wird vom Server-Admin vergeben. + +#### `SERVER_HOSTNAME` + +> Kann in verschiedenen Formaten vorliegen: + +| Format | Beschreibung | Beispiel | +| :------------------- | :--------------------------- | :------------------- | +| IP-Address (private) | numerisch; lokales Netz | `192.168.1.100` | +| IP-Address (public) | numerisch; öffentliches Netz | `203.0.113.1` | +| FQDN | vollständiger Domänenname | `server.example.com` | +| Hostname | einfacher Name ohne Domäne | `hyrican-1` | +| Alias | alternativer Name; Verweis | `hyrican-1-extern` | + +In der Regel übermittelt der Server-Admin dem neu freigeschalteten User eine SSH-Config. +Die Verwendung der dort definierten Aliases wird empfohlen. + +</details> ### Python Environment @@ -138,12 +162,67 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC | `PYTHON_VERSION` | Python: Gewünschte Version | `3.10` | | `PYTHON_PACKAGES` | Python: Benötigte Pakete | `tensorflow-cpu matplotlib optuna` | +<details> +<summary>Details anzeigen</summary> + +#### `SERVER_CONDA_PATH` + +> Definiert dem Pfad der _Conda_-Installation auf dem Server. + +Auf den Servern `server-*`, `hyrican-*` und `nbb-*` ist _Conda_ unter `/opt/conda` installiert. + +#### `SERVER_CONDA_ENV` + +> Definiert den Pfad des _Conda-Environments_. + +Die Erstellung neuer _Conda Environments_ ist ohne Admin-Rechte global nicht möglich. +Deshalb müssen sie lokal erstellt und installiert werden. +Die vorkonfigurierte _Makefile_ schlägt den Ordner `~/envs` im Home-Verzeichnis vor. + +**WICHTIG:** Möchte man sich manuell auf einem der Server anmelden und bspw. Pakete installieren, muss das _Conda Environment_ aktiviert werden: + +```bash +conda activate ~/envs/ml +``` + +#### `PYTHON_VERSION` + +> Nach Bedarf konfigurierbar + +#### `PYTHON_PACKAGES` + +> Nach Bedarf konfigurierbar. + +Vorkonfiguriert ist das `ml`-Environment mit seinen Packages, wie es in _[install-python-tensorflow-gym](https://gitlab.cvh-server.de/ckaufmann/install-python-tensorflow-gym)_ vorschlägt. +Zusätzlich benötigte Pakete müssen – mit Leerzeichen getrennt – an `PYTHON_PACKAGES` angehängt werden. + +</details> + ### Project Paths -| Variable | Verwendung | Beispiel | -| :------------------- | :------------------------- | :------------------- | -| `LOCAL_PROJECT_DIR` | Client: Projektordner [^1] | `.` | -| `REMOTE_PROJECT_DIR` | Server: Projektordner [^2] | `~s/akis/my_project` | +| Variable | Verwendung | Beispiel | +| :------------------- | :------------------------- | :------------------ | +| `LOCAL_PROJECT_DIR` | Client: Projektordner [^1] | `.` | +| `REMOTE_PROJECT_DIR` | Server: Projektordner [^2] | `~/akis/my_project` | + +<details> +<summary>Details anzeigen</summary> + +#### `LOCAL_PROJECT_DIR` + +> Definiert den Pfad des Projektordners auf dem **lokalen Rechner**. + +Er wird relativ zur _Makefile_ angegeben. +Liegt die _Makefile_ also direkt im Projektordner, ist `LOCAL_PROJECT_DIR := .`. + +#### `REMOTE_PROJECT_DIR` + +> Definiert den Pfad des Projektordners auf dem **Server**. + +Er wird absolut oder relativ zum Home-Verzeichnis angegeben. +Also bspw. `~/akis/my_project` oder `/home/mmustermann/akis/my_project`. + +</details> ### Project Files @@ -152,6 +231,26 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC | `MAIN_SCRIPT` | Auszuführendes Python-Script [^1] | `main.py` | | `LOG_FILE` | Log-Datei (optional) [^1] | `progress.log` | +<details> +<summary>Details anzeigen</summary> + +#### `MAIN_SCRIPT` + +> Definiert das _Python_-Script, welches später durch die _Makefile_ auf dem Server ausgeführt wird. + +Sollte es notwendig sein, dass mehrere Scripts bspw. nacheinander ausgeführt werden, ist es empfehlenswert eine `main.py` zu erstellen. +Dieses `main.py` kann dann alle anderen Scripts ausführen. + +#### `LOG_FILE` + +> Definiert die Datei, in der das _Python_-Script einen Log schreib. + +Logs beinhalten meist Statusmeldungen über den Programmablauf und geben Aufschluss über Fortschritt, Fehler und Erfolg. +Die Verwendung einer Log-File ist optional. +Ist sie vorhanden, kann sie mit `make log` angesehen werden; neue Einträge werden "live" aktualisiert und angezeigt. + +</details> + ### File Transfer | Variable | Verwendung | Beispiel | @@ -160,12 +259,64 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC | `LOCAL_DOWNLOAD_DIR` | Client: Download-Ordner [^1] | `output` | | `REMOTE_DOWNLOAD_FILES` | Server: Download-Dateien [^1] | `output/*.svg output/*.pkl` | +<details> +<summary>Details anzeigen</summary> + +#### `LOCAL_UPLOAD_FILES` + +> Definiert – relativ zum Projektordner –, welche Dateien auf den Server hochgeladen werden sollen. + +Dazu ein paar Beispiele: + +| `LOCAL_UPLOAD_FILES` | Bedeutung | +| :--------------------- | :---------------------------------------------- | +| `.` | gesamter Projektordner | +| `main.py scripts data` | Main-Script, Scripts-Ordner, Data-Ordner | +| `main.py data/*.pkl` | Main-Script; alle Pickle-Dateien im Data-Ordner | + +#### `LOCAL_DOWNLOAD_DIR` + +> Definiert – relativ zum Projektordner – den Pfad, in dem vom Server heruntergeladene Output-Dateien gespeichert werden sollen. + +Dieser kann dem selben Ordner entsprechen, wie er auf dem Server gespiegelt ist. +Er kann jedoch auch ein anderer sein und bspw. `downloads` heißen. + +#### `REMOTE_DOWNLOAD_FILES` + +> Definiert – relativ zum Projektordner –, welche Output-Dateien vom Server heruntergeladen werden sollen. + +Es können sowohl ganze Ordner, als auch einzelne Dateien ausgewählt werden. +Dazu ein paar Beispiele: + +| `REMOTE_DOWNLOAD_FILES` | Bedeutung | +| :------------------------------------------ | :------------------------------------------------------------------------------ | +| `outputs` | alle Dateien im Output-Ordner | +| `outputs/*.csv outputs/*.pkl outputs/*.svg` | alle CSV-, PKL- und SVG-Dateien des Output-Orderns | +| `outputs img/*.png progress.log | alle Dateien im Output-Ordner; alle PNG-Dateien im Image-Ordner; eine Log-Datei | + +</details> + ### Misc | Variable | Verwendung | Beispiel | | :-------------------- | :--------------------------------- | :------- | | `COPY_LINKS_AS_FILES` | Server: Kopiert Symlinks als Datei | `false` | +<details> +<summary>Details anzeigen</summary> + +#### `COPY_LINKS_AS_FILES` + +> Kopiert symbolische Links als Datei + +Wenn in den Projektordnern symbolische Links ("symlinks", "symbolic links") liegen, werden diese von der _Makefile_ **nicht wie Dateien** behandelt. +Sie werden unverändert als _Symlinks_ auf den Server kopiert. + +In manchen Anwendungsfällen ist es jedoch gewollt, dass die Verlinkung aufgelöst und die Links als Dateien kopiert werden. +Für diesen Fall muss `COPY_LINKS_AS_FILES` auf `true` gesetzt werden. + +</details> + [^1]: Relativer Pfad zum Projektordner [^2]: Absoluter Pfad @@ -180,7 +331,7 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC | `run` | Führt Python Script aus | Server | | `kill` | Bricht Python Script ab | Server | | `log` | Zeigt Log-Datei (optional) an | Client | -| `download` | Läd Outputdateien herunter | Server → Client | +| `download` | Läd Output-Dateien herunter | Server → Client | | `delete` | Löscht Projektdateien | Server | --- @@ -191,9 +342,11 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC - [ ] Datasets über NFS - [ ] Benachrichtigung bei Abbruch/Erfolg - [ ] Slack + - [ ] E-Mail - [ ] Matrix - [ ] parallele Ausführung mehrerer Scripts - [ ] docs: get local python packages; append to `PYTHON_PACKAGES` +- [ ] ggf. mehrere Log-Files --- -- GitLab