From 7b2720ec44e65c4e2eb84585535bb7b5c7d91042 Mon Sep 17 00:00:00 2001 From: Max Melchert <maximilian.melchert@stud.hs-bochum.de> Date: Tue, 11 Mar 2025 11:14:19 +0100 Subject: [PATCH] docs: add detailed instructions --- src/makefile/README.md | 111 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 103 insertions(+), 8 deletions(-) diff --git a/src/makefile/README.md b/src/makefile/README.md index b699776..beb2039 100644 --- a/src/makefile/README.md +++ b/src/makefile/README.md @@ -4,9 +4,41 @@ > Server-Admin kontaktieren -- SSH-Public-Key auf Server -- SSH-Private-Key auf Client -- SSH-Config auf Client konfiguriert +- Server: Public SSH-Key +- Client: Private SSH-Key +- Client: SSH-Config konfiguriert + +<details> +<summary>Details anzeigen</summary> + +Diese Projekt sieht eine Kommunikation zwischen Client und Server mittels _SSH_ vor. +Aufgrund der höheren Sicherheit und einfacheren Bedienbarkeit sind _SSH-Keys_ für den Authentifizierungsprozess zu verwenden. + +Das Schlüsselpaar aus _Private-Key_ und _Public-Key_ muss zuvor gemeinsam mit dem Server-Admin eingerichtet werden. +Je nach Server-Konfiguration kann es erforderlich sein, die _SSH-Config_ anzupassen. + +</details> + +## Empfehlung + +Die Verwendung des Terminal-Multiplexers _[Byobu](https://www.byobu.org/)_ wird empfohlen. + +```bash +# Debian / Ubuntu +sudo apt install byobu +``` + +Download & Installation: [https://www.byobu.org/downloads](https://www.byobu.org/downloads) + +<details> +<summary>Details anzeigen</summary> + +Vorteile von _Byobu_: + +- **Sitzungen beibehalten**: Byobu ermöglicht das Starten von Sitzungen, die im Hintergrund weiterlaufen, selbst wenn das Terminal geschlossen oder die Verbindung getrennt wird. +- **Einfache Wiederherstellung**: Es ist jederzeit möglich, zu einer bestehenden Sitzung zurückzukehren, um den Status von Prozessen zu überprüfen oder die Arbeit fortzusetzen. + +</details> ## Installation @@ -16,6 +48,17 @@ 3. Makefile [konfigurieren](#konfiguration) 4. `make install` +<details> +<summary>Details anzeigen</summary> + +Die _Makefile_ dient in diesem Projekt zur Vereinfachung von Prozessen, die sonst in vielen Einzelschritten manuell über die bash-Konsole durchgeführt werden müssten. + +Im Abschnitt [Projektstruktur](#projektstruktur) ist ein beispielhafter Aufbau eines Projekts skizziert. + +Hilfen zur Konfiguration der _Makefile_ und Bedeutung der verwendeten Variablen sind im Abschnitt [Konfiguration](#konfiguration) zu finden. + +</details> + ## Bedienung > siehe [Befehle](#befehle) @@ -25,7 +68,14 @@ 3. `make log` Fortschritt überprüfen 4. `make download` Output-Dateien herunterladen ---- +<details> +<summary>Details anzeigen</summary> + +Die Makefile ist so konfiguriert, dass sie mit Erhalt einfacher Befehlen komplexe oder aufwendige Prozesse ausführt. + +Im Abschnitt [Befehle](#befehle) sind diese sogenannten _Targets_ und deren Aufgabe näher beschrieben. + +</details> ## Projektstruktur @@ -34,19 +84,41 @@ ```txt /home/max/akis/my_project/ ├── data -│ ├── one.pkl -│ ├── three.pkl -│ └── two.pkl +│ ├── one.pkl +│ ├── three.pkl +│ └── two.pkl ├── main.py ├── makefile ├── output -│ └── empty +│ └── empty └── scripts ├── script-1.py ├── script-2.py └── script-3.py ``` +<details> +<summary>Details anzeigen</summary> + +Diese Projektstruktur ist nur ein Beispiel. +Sie soll jedoch verdeutlichen, dass auch verschachtelte Projekte mit der _Makefile_ bedienbar sind. + +Wichtig ist jedoch, dass in der _Makefile_ das `MAIN_SCRIPT` konfiguriert ist. +Dieses Python-Script wird durch die _Makefile_ ausgeführt; hier: `main.py`. + +Wie das `MAIN_SCRIPT` aufgebaut ist, ist dabei nicht relevant. +Es könnte ein alleinstehendes Script sein, welches ohne andere Python-Scripts auskommt. +Oder es führt andere Python-Scripts aus; wie im obigen Beispiel `scripts/script-1.py`, `scripts/script-2.py` und `scripts/script-3.py`. + +Importierte Datasets liegen oft nicht innerhalb des Projektordners, sondern werden von extern importiert. +Es ist darauf zu achten, dass auch der Server Zugriff auf den Pfad der Datasets hat. +Symbolische Links können hier hilfreich sein. + +Output-Dateien, die nach Abschluss des Scripts wieder auf den Client heruntergeladen werden sollen, können mit `REMOTE_OUTPUT_FILES` definiert werden. +Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOCAL_OUTPUT_DIR` abgespeichert. + +</details> + ## Konfiguration | Variable | Verwendung | Beispiel | @@ -80,3 +152,26 @@ | `log` | Zeigt Log-Datei (optional) an | Client | | `download` | Läd Outputdateien herunter | Server → Client | | `delete` | Löscht Projektdateien | Server | + +--- + +## TODOs + +- [x] Bedienung über _Byobu_ +- [ ] Datasets über NFS +- [ ] Benachrichtigung bei Abbruch/Erfolg + - [ ] Slack + - [ ] Matrix +- [ ] parallele Ausführung mehrerer Scripts + +--- + +## Fragen & Anregungen + +Fragen, Unklarheiten, Anregungen und Wünsche können gerne über folgende Kommunikationswege an mich herangetragen werden: + +- [Slack](https://cvhai.slack.com/team/U084BA4GQ8M) +- [E-Mail](maximilian.melchert@stud.hs-bochum.de) + +Es ist durchaus im Sinne des Projekts, auch individualisierte _Makefiles_ für einzelne Projekte anzupassen und umzuschreiben. +Die hier beschriebene _Makefile_ ist nur die Basis, auf der zukünftige Maßanfertigungen aufbauen können. -- GitLab