Skip to content
Snippets Groups Projects
Commit 2f6d8d3a authored by Max Melchert's avatar Max Melchert
Browse files

feat: add hiiden details text in README

Added <details> tags to provide expandable sections for more information in the README file.
parent b09fd4f8
Branches
No related tags found
No related merge requests found
......@@ -125,9 +125,33 @@ 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` |
| :------------ | :--------------- | :----------------- |
| `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` |
| `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
---
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment