Skip to content
Snippets Groups Projects
Select Git revision
  • ff3da14654d4fcab776d6e273b3a75cf053d2a00
  • main default protected
2 results

README.md

Blame
    • README.md 14.43 KiB

    Makefile

    Voraussetzungen

    Important

    Server-Admin kontaktieren

    • Server: SSH-Key (public) eingerichtet
    • Client: SSH-Key (private) eingerichtet
    • Client: SSH-Config angepasst
    Details anzeigen

    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.

    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.

    Empfehlung

    Tip

    Die Verwendung des Terminal-Multiplexers Byobu wird empfohlen.

    # Debian / Ubuntu
sudo apt install byobu

    Download & Installation: https://www.byobu.org/downloads

    Details anzeigen

    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.

    Installation

    Automatisch

    Important

    ~/akis/my_project durch Pfad des Projektordners ersetzen!

    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

    2. Speichern: in Projektordner ablegen

    3. Umbenennen: in makefile oder Makefile umbenennen

      mv basic.mk makefile

    4. Konfigurieren: siehe Konfiguration

    5. Installation: siehe Befehle

      make install
    Details anzeigen

    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 ist ein beispielhafter Aufbau eines Projekts skizziert.

    Hilfen zur Konfiguration der Makefile und Bedeutung der verwendeten Variablen sind im Abschnitt Konfiguration zu finden.

    Bedienung

    Tip

    siehe Befehle

    1. make upload Projektdateien hochladen
    2. make run Python-Script ausführen
    3. make log Fortschritt überprüfen
    4. make download Output-Dateien herunterladen
    Details anzeigen

    Die Makefile ist so konfiguriert, dass sie mit Erhalt einfacher Befehlen komplexe oder aufwendige Prozesse ausführt.

    Im Abschnitt Befehle sind diese sogenannten Targets und deren Aufgabe näher beschrieben.

    Projektstruktur

    Note

    Beispielhafter Aufbau eines Projektordners

    ~/akis/my_project
├── data
│   ├── one.pkl
│   ├── three.pkl
│   └── two.pkl
├── main.py
├── makefile
├── output
│   └── empty
└── scripts
    ├── script-1.py
    ├── script-2.py
    └── script-3.py
    Details anzeigen

    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; hier: main.py. Dieses Python-Script muss in der Makefile definiert sein. Der Befehl make run führt dieses Script aus.

    Der Aufbau des MAIN_SCRIPTs 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.

    Datasets

    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:

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

    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.

    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
    SERVER_USER Server: Username mmustermann
    SERVER_HOST Server: Hostname hyrican-1-extern
    Details anzeigen

    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.

    Python Environment

    Variable Verwendung Beispiel
    SERVER_CONDA_PATH Server: Conda-Installations-Pfad /opt/conda
    SERVER_CONDA_ENV Server: Conda-Environment-Pfad ~/envs/ml
    PYTHON_VERSION Python: Benötigte Version 3.10
    PYTHON_PACKAGES Python: Benötigte Pakete tensorflow-cpu matplotlib optuna
    Details anzeigen

    SERVER_CONDA_PATH

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

    Die Erstellung neuer Conda Environments ist ohne Admin-Rechte global nicht möglich. Deshalb muss eine lokale Erstellung und Installation erfolgen. Die vorkonfigurierte Makefile schlägt den Ordner ~/envs im Home-Verzeichnis vor.

    WICHTIG: Meldet sich ein User manuell über SSH auf dem Server an, um bspw. Packages zu installieren, muss er/sie das Conda-Environment aktiviert:

    conda activate ~/envs/ml

    PYTHON_VERSION

    ... ist nach Bedarf konfigurierbar.

    PYTHON_PACKAGES

    ... ist nach Bedarf konfigurierbar.

    Vorkonfiguriert ist das ml-Environment mit seinen Packages, wie es install-python-tensorflow-gym vorschlägt. Zusätzlich benötigte Pakete werden – mit Leerzeichen getrennt – an PYTHON_PACKAGES angehängt.

    Project Paths

    Variable Verwendung Beispiel
    LOCAL_PROJECT_DIR Client: Projektordner 1 .
    REMOTE_PROJECT_DIR Server: Projektordner 2 ~/akis/my_project
    Details anzeigen

    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.

    Project Files

    Variable Verwendung Beispiel
    MAIN_SCRIPT Auszuführendes Python-Script 1 main.py
    LOG_FILE Log-Datei (optional) 1 progress.log
    Details anzeigen

    MAIN_SCRIPT

    ... definiert das Python-Script, welches die Makefile auf dem Server ausführt.s

    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.

    Logs beinhalten zumeist Statusmeldungen über den Programmablauf und geben Aufschluss über Fortschritt, Fehler und Erfolg. Die Verwendung einer Log-File ist optional. make log öffnet die Log-Datei und zeigt neue Einträge "live" an.

    File Transfer

    Variable Verwendung Beispiel
    LOCAL_UPLOAD_FILES Client: Upload-Dateien 1 main.py scripts data/*.pkl
    LOCAL_DOWNLOAD_DIR Client: Download-Ordner 1 output
    REMOTE_DOWNLOAD_FILES Server: Download-Dateien 1 output/*.svg output/*.pkl
    Details anzeigen

    LOCAL_UPLOAD_FILES

    ... definiert – relativ zum Projektordner –, welche Dateien die Makefile auf den Server hochläd.

    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 die Makefile Output-Dateien herunterläd und speichert.

    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 die Makefile vom Server herunterläd.

    Es können sowohl ganze Ordner, als auch einzelne Dateien zum Download ausgewählt werden. Dazu ein paar Beispiele:

    REMOTE_DOWNLOAD_FILES Bedeutung
    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

    Misc

    Variable Verwendung Beispiel
    COPY_LINKS_AS_FILES Server: Kopiert Symlinks als Datei false
    Details anzeigen

    COPY_LINKS_AS_FILES

    ... kopiert symbolische Links als Datei.

    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 vorliegen. Für diesen Fall ist COPY_LINKS_AS_FILES auf true zu setzen.

    Befehle

    Tip

    make <target>

    Target Aktion Ort
    install Installiert Python Environment und Pakete Server
    upload Läd veränderte Projektdateien hoch Client → Server
    run Führt Python Script aus Server
    kill Bricht Python Script ab Server
    log Zeigt Log-Datei (optional) an Client
    download Läd Output-Dateien herunter Server → Client
    delete Löscht Projektdateien Server

    TODOs

    • Bedienung über Byobu
    • 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
    • source Mamba

    Fragen & Anregungen

    Fragen, Unklarheiten, Anregungen und Wünsche können gerne über folgende Kommunikationswege an mich herangetragen werden:

    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.

    1. Relativer Pfad zum Projektordner ↩ ↩2 ↩3 ↩4 ↩5 ↩6

    2. Absoluter Pfad ↩

    Impressum Datenschutzerklärung