Diese Seite dokumentiert die nötigen Schritte, um ein neues Jupyter-Profil für eine Vorlesung oder einen Kurs anzulegen.

Wir empfehlen ein eigenes Profil für jeden Kurs, der Jupyter verwenden soll. Nach dem Login können neue Nutzer zuerst ein Profil auswählen. Alternativ können auch Permalinks verwendet werden, um direkt ein spezifisches Profil auszuwählen.

Ein Profil muss vor Beginn des Kurses vorbereitet und installiert werden, bevor es verwendet werden kann.

Profile bestehen aus:

• Einem Namen, der den Zweck des Profils beschreibt (oder den Namen des zugehörigen Kurses)
• Einem Git-Repository, in dem die Notebooks enthalten sind, die standartmäßig in den Workspace importiert werden sollen
• Einem Dockerfile, dass die Laufzeitumgebung und optionale Python Pakete spezifiziert

Wir stellen eine Liste generischer Profile für gängige Programmiersprachen zur Verfügung. Allerdings bieten wir auch die Möglichkeit, eigene Profile für bestimmte Kurse zu erstellen. Dadurch kann eine individuellere Anpassung ermöglicht werden.

Trennung von Laufzeitumgebung und Jupyter Notebooks

Wichtiger Punkt in der Vorbereitung eines neuen Profils ist die Trennung von Laufzeitumgebung und Notebook-Inhalt.

Wir verwenden nbgitpuller, um Jupyter Notebooks aus einem Git-Repository regelmäßig mit dem Workspace des Nutzers zu synchronisieren. Dies erlaubt Dozenten, neue Notebooks im Laufe eines Kurses schrittweise zur Verfügung zu stellen. Jeder Nutzer kann eine private Kopie des Git-Repositorys verwalten und kann dauerhafte Änderungen an den Notebooks in dieser Kopie vornehmen.

Im Gegensatz hierzu ist beabsichtigt, dass die Laufzeitumgebung über die Dauer eines Kurses mehr oder weniger statisch bleibt und keine regelmäßigen Updates erfordert. Alle Nutzer eines Profils teilen eine Laufzeitmgebung. Sämtliche Änderungen außerhalb des Home-Ordners sind nicht permanent und gehen bei Logout verloren.

Hinweis zu Git-Repositories

Studierende erhalten im Rahmen dieses Prozesses vollen read-only Zugang auf das Repository, dass sie zur Verfügung stellen. Falls sie ein Token verwenden, um uns die Synchronisierung privater/interner Repositories zu ermöglichen, wird auch dieses für die Studierenden sichtbar.

Daher bitten wir sie keine Repositories zu teilen, die wichtige oder personenbezogene Daten (auch in anderen Branches) enthalten, da die Studierenden Zugriff auf diese Daten erhalten könnten.

Vorgehen

Im Allgemeinen sind folgende Schritte nötig, um ein neues Profil zu erstellen:

1. Erstellen einer lokalen Testumgebun zur Vorbereitung ihrer Jupyter-Umgebung
2. Auswählen eines Jupyter Kernels
3. Erstellen des Git-Repository für Notebooks und Laufzeiumgebung
4. Vorbereitung der Jupyter-Notebooks
5. Python/Third-Party Requirements sammeln
6. Dockerfile anpassen
7. Antrag auf Eingliederung in die Profilliste stellen
8. Warten, bis der Antrag bearbeitet wird und das neue Profil in der Liste erscheint

Schritte 4.- 6. Beziehen sich nur auf die Erstellung von nicht-standard Profilen, die eine spezielle Anpassung des Kernels oder der Python Abhängigkeiten erfordern.

1. Erstellen einer lokalen Testumgebung

Folgen sie den Anweisungen auf der Jupyter-Webseite: https://jupyter.org/install

Für Windows Nutzer empfehlen wir die Verwendung der Python-Distribution Anaconda. Linux und MacOS Nutzer können sowohl Anaconda als auch das durch die Paketverwaltung installierte pip verwenden.

2. Jupyter-Kernel auswählen

Jupyter kann durch verschiedene Kernels eine große Auswahl an Programmiersprachen verwenden. Der ursprüngliche und meistverwendete Kernel für Jupyter ist der IPython interpreter. Andere Optionen stehen aber auch zur Verfügung. Eine aktuelle Liste aller verfügbarer Kernels finden sie im Jupyter Wiki.

Prinzipiell können fast alle dieser Kernel in Jupyter verwendet werden, indem ddieLaufzeitumgebung angepasst wird. Bitte folgen sie der Dokumentation zur Installation anderer Kernels und fügen die notwendigen Befehle zum Dockerfile hinzu (Schritt 6.)

In den meisten Fällen wird der Standard IPython-Kernel verwendet, was keine weiteren Schritte erfordert.

3. Neues Git-Repository Erstellen

Wir empfehlen die Verwendung der RWTH Software Engineering Services für die Verwaltung von Jupyter Notebooks und die Definition neuer Laufzeitumgebungen.

Dies ermöglicht regelmäßige Updates für Jupyter und erlaubt den Studierenden, zu Notebooks beizutragen.

Sie können entweder ein bestehendes Git-Repository nutzen, dass für ihre Veranstaltung angelegt wurde, oder ein Neues erstellen, indem sie eine Fork unseres Beispielprofil anlegen.

Benutzen sie diesen Link, um direkt eine Fork des Beispielprofils zu erstellen.

Sobald die Erstellung ihrer Fork abgeschlossen ist, können sie eine lokale Kopie auf ihrem Gerät speichern:

git clone git@git.rwth-aachen.de:/stvogel/my-new-course.git
cd my-new-course

4. Jupyter Notebooks Vorbereiten

Ein neues Profil kann mit einer Sammlung von Notebooks gefüllt werden. Diese Notebooks werden bei jedem Login des Nutzers mit dem Git-Repository synchronisiert.

Dies erlaubt die Freigabe weiterer Notebooks im Laufe eines Semesters.

Um ihre Sammlung an Notebooks vorzubereiten, öffnen sie Jupyter auf ihrem lokalen Rechner.

Es öffnet sich ein neues Browserfenster mit dem Jupyter Webinterface. Hier sollte an dieser Stelle bereits die Liste von Dateien in ihrem Repository angezeigt werden. Sie können nun neue Notebooks anlegen und diese mit beliebigem Content füllen.

5. Python-Anforderungen Herausfinden

Einige Jupyter Notebooks könnten, abhängig von ihrem Inhalt, zusätzliche Python Pakete erfordern. Diese externen Abhängigkeiten werden für Gewöhnlich in einer requirements.txt oder environment.yml Datei abgelegt:

Für weitere Informationen stehen die folgenden Ressourcen zur Verfügung:

• Creating Conda environments
• PIP Requirements Files

6. Dockerfile Anpassen

Einige Profile (z.B. mit speziellen Jupyter Kernels) können zusätzliche Anpassungen der Laufzeitumgebung erfordern, die nicht von der Installation neuer Python Pakete abgedeckt werden können.

Um diese Fälle abzudecken, hat der Nutzer die Möglichkeit, das beinhaltende Dockerfile anzupassen und beliebige Befehle während der Erstellung der Umgebung auszuführen. Beachten sie, dass diese Befehle nur in der Docker Buildphase ausgeführt werden.

7. Jupyter Notebooks und Dockerfiles im Git Repository veröffentlichen

Nach Abschluss der Schritte 2.- 4. müssen die vorgenommenen Änderungen in einem Repository abgelegt und bei einem Git-Host (RWTH GitLab oder GitHub) veröffentlicht werden.

8. Antrag auf Öffnen eines neuen Jupyter Profils

Sie können über diesen Link anfordern, dass ihr Profil in das RWTHjupyter Cluster aufgenommen wird.

Der Link führt zu einem Formular für den Profilantrag im RWTH GitLab System. Bitte folgen sie der vorgegebenen Struktur. Im Normalfall dauert die Prüfung und Bearbeitung eines Antrags ein paar Tage. Sollten keine Probleme auftreten wird ihr Profil nach diesem Zeitraum auf dem Cluster zu finden sein.