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

docs(makefile): rephrase and reformat documentation 

- Improved clarity of instructions in the Makefile documentation.
- Reformatted sections for better readability and consistency.
- Updated examples to reflect current usage.
parent c9dafa93
Branches
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
Showing
with 115 additions and 64 deletions
src/makefile/README.md
+ 115
− 64
View file @ 33e2429a
......@@ -2,11 +2,12 @@
## Voraussetzungen
> [!important]
> Server-Admin kontaktieren
- Server: Public SSH-Key
- Client: Private SSH-Key
- Client: SSH-Config konfiguriert
- [x] Server: SSH-Key (public) eingerichtet
- [x] Client: SSH-Key (private) eingerichtet
- [x] Client: SSH-Config angepasst
<details>
<summary>Details anzeigen</summary>
......@@ -14,14 +15,15 @@
Dieses 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.
User und Server-Admin müssen das Schlüsselpaar aus _Private-Key_ und _Public-Key_ zuvor gemeinsam einrichten.
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.
> [!tip]
> Die Verwendung des Terminal-Multiplexers _[Byobu](https://www.byobu.org/)_ wird empfohlen.
```bash
# Debian / Ubuntu
......@@ -35,24 +37,45 @@ Download & Installation: [https://www.byobu.org/downloads](https://www.byobu.org
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.
- **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
1. Makefile [herunterladen](./basic.mk)
2. Makefile in Projektordner speichern
- Projektstruktur ([Beispiel](#projektstruktur))
3. Makefile in `Makefile` oder `makefile` umbenennen (ohne `.mk`)
4. Makefile [konfigurieren](#konfiguration)
5. `make install`
### Automatisch
> [!important]
> `~/akis/my_project` durch Pfad des Projektordners ersetzen!
```bash
cd ~/akis/my_project
wget https://gitlab.cvh-server.de/mmelchert/akis-cloud-computing/-/raw/main/src/makefile/basic.mk
mv -i basic.mk makefile
```
### Manuell
1. **Herunterladen:** [Download](./basic.mk)
2. **Speichern:** in [Projektordner]((#projektstruktur)) ablegen
3. **Umbenennen:** in `makefile` oder `Makefile` umbenennen
```bash
mv basic.mk makefile
```
4. **Konfigurieren:** siehe [Konfiguration](#konfiguration)
5. **Installation:** siehe [Befehle](#befehle)
```bash
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.
Die _Makefile_ dient in diesem Projekt zur Vereinfachung von Prozessen, die ein User sonst in vielen Einzelschritten manuell über die bash-Konsole durchführen muss.
Im Abschnitt [Projektstruktur](#projektstruktur) ist ein beispielhafter Aufbau eines Projekts skizziert.
......@@ -62,6 +85,7 @@ Hilfen zur Konfiguration der _Makefile_ und Bedeutung der verwendeten Variablen
## Bedienung
> [!tip]
> siehe [Befehle](#befehle)
1. `make upload` Projektdateien hochladen
......@@ -80,10 +104,11 @@ Im Abschnitt [Befehle](#befehle) sind diese sogenannten _Targets_ und deren Aufg
## Projektstruktur
> Beispiel
> [!note]
> Beispielhafter Aufbau eines Projektordners
```txt
/home/max/akis/my_project/
~/akis/my_project
├── data
│ ├── one.pkl
│ ├── three.pkl
......@@ -101,27 +126,52 @@ Im Abschnitt [Befehle](#befehle) sind diese sogenannten _Targets_ und deren Aufg
<details>
<summary>Details anzeigen</summary>
Diese Projektstruktur ist nur ein Beispiel.
Sie soll jedoch verdeutlichen, dass auch verschachtelte Projekte mit der _Makefile_ bedienbar sind.
> [!note]
> Die oben dargestellte Projektstruktur ist lediglich ein Beispiel. Sie demonstriert, wie ein Projektordner aussehen könnte.
### Main-Script
Im Mittelpunkt steht das [`MAIN_SCRIPT`](#main_script); hier: `main.py`.
Dieses Python-Script muss in der _Makefile_ definiert sein.
Der [Befehl](#befehle) `make run` führt dieses Script aus.
Der Aufbau des `MAIN_SCRIPT`s ist nicht vorgeschrieben.
In Projekten mit nur einem Python-Script beinhaltet diese dann den gesamten Code.
### Scripts
In Projekten mit mehreren Python-Scripts führt dieses `MAIN_SCRIPT` meist weitere Python-Scripts aus.
Im Beispiel sind das die Scripts im Ordner `scripts`.
Wichtig ist jedoch, dass in der _Makefile_ das `MAIN_SCRIPT` konfiguriert ist.
Dieses Python-Script wird durch die _Makefile_ ausgeführt; hier: `main.py`.
### Datasets
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`.
Datasets liegen häufig nicht im Projektordner, sondern werden von Extern importiert.
Hier empfiehlt sich die Verwendung von _Symlinks_.
Der bash-Code nachfolgenden Beispiel erstellt eine Verknüpfung des externen Datasets im Ordner `data` des Projektordners:
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.
```bash
cd ~/akis/my_project
ln -s ~/akis/datasets data
```
Verwendet das Projekt eine solche Verknüpfung von _Symlinks_, muss in der Konfiguration der _Makefile_ eine Variable gesetzt werden (siehe [`COPY_LINKS_AS_FILES`](#copy_links_as_files)).
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.
### Output-Files
Nach der Ausführung und Berechnung auf dem Server, möchte man meist einen Output in Form von Dateien erhalten.
In `REMOTE_DOWNLOAD_FILES` definiert man genau diese Dateien, die man herunterladen möchte.
Die _Makefile_ kopiert sie schließlich durch den Aufruf des Befehls `make download` in den zuvor definierten Ordner.
`REMOTE_DOWNLOAD_FILES` definiert, welche Output-Dateien die _Makefile_ nach Abschluss des Scripts wieder auf den Client herunterläd.
Der Aufruf von `make download` speichert diese Dateien im zuvor definierten Ordner `LOCAL_DOWNLOAD_DIR`.
</details>
## Konfiguration
> [!important]
> Die Anpassung der in der _Makefile_ mit `# todo` gekennzeichneten Konfigurationsvariablen ist zwingend erforderlich, um eine korrekte Ausführung sicherzustellen.
### Server
| Variable | Verwendung | Beispiel |
......@@ -134,11 +184,11 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC
#### `SERVER_USER`
> Wird vom Server-Admin vergeben.
> ... wird vom Server-Admin vergeben.
#### `SERVER_HOSTNAME`
> Kann in verschiedenen Formaten vorliegen:
> ... kann in verschiedenen Formaten vorliegen.
| Format | Beschreibung | Beispiel |
| :------------------- | :--------------------------- | :------------------- |
......@@ -148,8 +198,8 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC
| 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.
In der Regel übermittelt der Server-Admin dem neu freigeschalteten User eine _SSH-Config_.
Die Verwendung der dort definierten _Aliases_ wird empfohlen.
</details>
......@@ -159,7 +209,7 @@ Die Verwendung der dort definierten Aliases wird empfohlen.
| :------------------ | :------------------------------- | :--------------------------------- |
| `SERVER_CONDA_PATH` | Server: Conda-Installations-Pfad | `/opt/conda` |
| `SERVER_CONDA_ENV` | Server: Conda-Environment-Pfad | `~/envs/ml` |
| `PYTHON_VERSION` | Python: Gewünschte Version | `3.10` |
| `PYTHON_VERSION` | Python: Benötigte Version | `3.10` |
| `PYTHON_PACKAGES` | Python: Benötigte Pakete | `tensorflow-cpu matplotlib optuna` |
<details>
......@@ -167,19 +217,19 @@ Die Verwendung der dort definierten Aliases wird empfohlen.
#### `SERVER_CONDA_PATH`
> Definiert dem Pfad der _Conda_-Installation auf dem Server.
> ... definiert den 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_.
> ... 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.
Deshalb muss eine lokale Erstellung und Installation erfolgen.
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:
**WICHTIG:** Meldet sich ein User manuell über _SSH_ auf dem Server an, um bspw. Packages zu installieren, muss er/sie das _Conda-Environment_ aktiviert:
```bash
conda activate ~/envs/ml
......@@ -187,14 +237,14 @@ conda activate ~/envs/ml
#### `PYTHON_VERSION`
> Nach Bedarf konfigurierbar
> ... ist nach Bedarf konfigurierbar.
#### `PYTHON_PACKAGES`
> Nach Bedarf konfigurierbar.
> ... ist 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.
Vorkonfiguriert ist das `ml`-Environment mit seinen Packages, wie es _[install-python-tensorflow-gym](https://gitlab.cvh-server.de/ckaufmann/install-python-tensorflow-gym)_ vorschlägt.
Zusätzlich benötigte Pakete werden – mit Leerzeichen getrennt – an `PYTHON_PACKAGES` angehängt.
</details>
......@@ -210,14 +260,14 @@ Zusätzlich benötigte Pakete müssen – mit Leerzeichen getrennt – an `PYTHO
#### `LOCAL_PROJECT_DIR`
> Definiert den Pfad des Projektordners auf dem **lokalen Rechner**.
> ... 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**.
> ... 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`.
......@@ -236,18 +286,18 @@ Also bspw. `~/akis/my_project` oder `/home/mmustermann/akis/my_project`.
#### `MAIN_SCRIPT`
> Definiert das _Python_-Script, welches später durch die _Makefile_ auf dem Server ausgeführt wird.
> ... definiert das _Python_-Script, welches die _Makefile_ auf dem Server ausführt.s
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.
In Projekten mit nur einem Python-Script beinhaltet dieses Script den gesamten Code.
In Projekten mit mehreren Python-Scripts führt das `MAIN_SCRIPT` meist weitere Python-Scripts aus.
#### `LOG_FILE`
> Definiert die Datei, in der das _Python_-Script einen Log schreib.
> ... 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.
Logs beinhalten zumeist 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.
`make log` öffnet die Log-Datei und zeigt neue Einträge "live" an.
</details>
......@@ -264,7 +314,7 @@ Ist sie vorhanden, kann sie mit `make log` angesehen werden; neue Einträge werd
#### `LOCAL_UPLOAD_FILES`
> Definiert – relativ zum Projektordner –, welche Dateien auf den Server hochgeladen werden sollen.
> ... definiert – relativ zum Projektordner –, welche Dateien die _Makefile_ auf den Server hochläd.
Dazu ein paar Beispiele:
......@@ -276,23 +326,23 @@ Dazu ein paar Beispiele:
#### `LOCAL_DOWNLOAD_DIR`
> Definiert – relativ zum Projektordner – den Pfad, in dem vom Server heruntergeladene Output-Dateien gespeichert werden sollen.
> ... definiert – relativ zum Projektordner – den Pfad, in dem die _Makefile_ Output-Dateien herunterläd und speichert.
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.
Dieser kann dem selben lokalen Output-Ordner entsprechen, wie das Script auf dem Server ihn beschreibt.
Es kann jedoch auch ein separater Ordner sein; bspw. `downloads`.
#### `REMOTE_DOWNLOAD_FILES`
> Definiert – relativ zum Projektordner –, welche Output-Dateien vom Server heruntergeladen werden sollen.
> ... definiert – relativ zum Projektordner –, welche Output-Dateien die _Makefile_ vom Server herunterläd.
Es können sowohl ganze Ordner, als auch einzelne Dateien ausgewählt werden.
Es können sowohl ganze Ordner, als auch einzelne Dateien zum Download 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 |
| :--------------------------------------- | :------------------------------------------------------------------------------ |
| `output` | alle Dateien im Output-Ordner |
| `output/*.csv output/*.pkl output/*.svg` | alle CSV-, PKL- und SVG-Dateien des Output-Orderns |
| `output img/*.png progress.log` | alle Dateien im Output-Ordner; alle PNG-Dateien im Image-Ordner; eine Log-Datei |
</details>
......@@ -307,13 +357,13 @@ Dazu ein paar Beispiele:
#### `COPY_LINKS_AS_FILES`
> Kopiert symbolische Links als Datei
> ... kopiert symbolische Links als Datei.
Wenn in den Projektordnern symbolische Links ("symlinks", "symbolic links") liegen, werden diese von der _Makefile_ **nicht wie Dateien** behandelt.
Wenn in den Projektordnern symbolische Links ("symlinks", "symbolic links") liegen, behandelt die _Makefile_ sie **nicht wie Dateien**!
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.
In manchen Anwendungsfällen ist es jedoch gewollt, dass die Verlinkung aufgelöst und die Links als Dateien vorliegen.
Für diesen Fall ist `COPY_LINKS_AS_FILES` auf `true` zu setzen.
</details>
......@@ -322,6 +372,7 @@ Für diesen Fall muss `COPY_LINKS_AS_FILES` auf `true` gesetzt werden.
## Befehle
> [!tip]
> `make <target>`
| Target | Aktion | Ort |
......@@ -346,7 +397,7 @@ Für diesen Fall muss `COPY_LINKS_AS_FILES` auf `true` gesetzt werden.
- [ ] Matrix
- [ ] parallele Ausführung mehrerer Scripts
- [ ] docs: get local python packages; append to `PYTHON_PACKAGES`
- [ ] ggf. mehrere Log-Files
- [ ] `source` Mamba
---
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment

Impressum Datenschutzerklärung