====== Jupyter / JupyterHub ======
Die GWDG bietet [[https://jupyter-cloud.gwdg.de|JupyterHub]] für interessierte Benutzer*innen von Python, Julia oder R an.
===== Nutzungsvoraussetzungen =====
Jeder Nutzer mit einem gültigen [[de:services:general_services:customer_portal:account_info|GWDG Full Account]].
===== Für wen ist der Dienst geeignet? =====
Dieser Dienst richtet sich besonders an Benutzer*innen in der Lehre zur Verwendung in Kursen, Seminaren etc. und an einzelne Benutzer*innen, die Dinge in den jeweiligen Programmiersprachen ausprobieren und testen möchten.
Für größere Einsätze, in denen mit großen Datensätzen, großen Modellen, oder parallelen Berechnungen gearbeitet wird, empfiehlt sich die Nutzung des [[https://info.gwdg.de/docs/doku.php?id=en:services:application_services:jupyter:hpc|JupyterHub des SCC]].
===== Was ist Jupyter / Jupyter-Hub? =====
Juyter bietet die Möglichkeit im Browser interaktiv mit Python, Julia oder R zu arbeiten. Quellcode kann dabei in einem Editor im Browser eingegeben, ausgeführt und überarbeitet werden. Diese Schritte passieren in einem s.g. "Notebook". Jedes Notebook hat einen s.g. "Kernel" der den Typ des Notebooks bestimmt, also ein Python-, Julia- oder R--Notebook.
Jupyter-Hub ist das Portal, an dem sich Benutzer*innen anmelden, wo laufende Notebooks verwaltet oder neue gestartet werden.
Bitte beachten Sie, dass Jupyter auch auf dem [[https://info.gwdg.de/docs/doku.php?id=en:services:application_services:jupyter:hpc|SCC]] betrieben werden kann, falls höhere Berechnungsressourcen benötigt werden.
===== Wie wird Jupyter / Jupyter-Hub verwendet? =====
==== Voraussetzungen ====
Da Speicherung und Berechnung serverseitig passieren, muss keine Software installiert oder weitere Voraussetzungen erfüllt sein. Es muss lediglich ein moderner Browser zur Verfügung stehen. Für die Anmeldung an dem Dienst wird ein [[de:services:general_services:customer_portal:account_info|GWDG Full Account]] benötigt.
==== Notebook-Image auswählen ====
Nach erfolgreicher Anmeldung erscheint eine Option zum Auswählen des Notebook-Images, mit dem der Notebook-Server gestartet werden soll:
* GWDG default image (based on jupyter/datascience-notebook)
* Dies war bisher und ist das Standard-Image.
* Python Stack w/ TensorFlow (jupyter/tensorflow-notebook)
* Python and R Spark Jupyter Notebook (jupyter/all-pyspark-notebook)
* Data Science Jupyter Notebook (jupyter/datascience-notebook)
Das Notebook-Image stellt die Umgebung des Notebook-Server zur Verfügung, insbesondere die vorinstallierte Software.
Obwohl das GWDG default image stark erweitert ist und auf dem regulären Data Science Notebook des Jupter-Projekts basiert, ist ein Image des Jupyter-Projekts möglicherweise in einigen Fälle besser geeignet als einfachere oder spezialisierte Umgebung.
Ungeachtet des ausgewählten Images bleibt das Heimatverzeichnis des Benutzer und die Daten darin unverändert und stehen immer zur Verfügung.
Das Notebook-Image kann nur geändert werden, wenn der Notebook-Server gestoppt ist und neu gestartet wird. Der Notebook-Server beendet sich nicht durch Abmeldung oder Schließen des Browsers, allerdings tritt dann nach einer Weile ein Timeout ein, der den Server beendet. Der Server kann aber direkt beendet werden über das Menü File -> Hub Control Panel -> "Stop my server". Dies stoppt tatsächlich den Server und die Funktion "Start my server" startet diesen erneut, so dass ein Image ausgewählt werden kann.
=== Changelog Notebook-Images ===
Ein einfaches Changelog mit [[en:services:application_services:jupyter:version-history|Änderungen (en)]] an dem "GWDG default image" ist verfügbar.
==== Starten eines Notebooks ====
Nach erfolgreicher Anmeldung kann auf der Übersichtsseite über das Dropdown-Menü oben links unter "File - New" ein neues Notebook gestartet werden. Früher genutzte oder bereits gestartete Notebooks und ihre zugehörigen Dateien finden sich in der Liste linkerhand.
Detaillierte Informationen zur Benutzeroberfläche: https://jupyterlab.readthedocs.io/en/stable/index.html
==== Beenden und Verwalten von Notebooks ====
Ein aktives Notebook kann über das Menü "File - Close and shutdown notebook" oder durch schließen des Browser-Fensters/Tabs geschlossen werden. Das eigentliche Notebook bleibt in den letzten Zustand erhalten und kann über die Übersichtsseite wieder gestartet und die Arbeit daran fortgesetzt werden.
Gelöscht wird das Notebook durch Rechtsklick "Delete" des Eintrags in der Listenansicht.
===== Benutzung =====
* ⚠ **Bitte beachten Sie**, dass alle Verzeichnisse außer dem Home-Verzeichnis flüchtig sind und beim Schließen des Notebook-Servers verloren gehen.
* Pro Benutzer*in ist eine Quota von maximal 50 GB Speicher und 10 GB RAM festgelegt.
* jupyter-cloud.gwdg.de ist nicht für kontinuierliche Berechnungen über mehrere Tage geeignet.
==== Notebook startet nicht mehr / Kernel verbindet sich nicht nach Paketinstallation oder Update ====
Sollte nach einem Upgrade von Paketen / Installation neuer Pakete / Installation eines neuen Kernel kein Notebook mehr startbar sein, bzw. der Kernel verbindet sich nicht mehr, kann es helfen den Ordner '.local' umzubenennen, um neu zu starten. Bitte beachten Sie, das hierbei alle Custom-Kernel und lokal nachinstallierte Pakete deaktiviert werden:
* File - New - Terminal
* mv -v .local/ .local.gwdg-disable
* Anschließend Notebook Server neustarten über: File - Hub Control Panel - Stop My Server
==== Installation zusätzlicher Python Module ====
Zusätzliche Python Module können über das Terminal und den Python package manager "pip" installiert werden. Hierzu muss über das Menü "New" -> "Terminal" ein Terminal geöffnet werden. Anschließend wird mit pip install --user ein neues Modul in das Home-Verzeichnis installiert.
=== Installation von größeren Python Modulen und Disk Space ===
Die Installation von größeren Python Modulen wie z.B. "tensorflow" kann mit einer Fehlermeldung "No space left on device" abbrechen, da pip bei der Verarbeitung größerer Module den Platz unter "/tmp" ausschöpft. Die folgenden Schritte legen ein neues Verzeichnis für temporäre Daten im wesentlich größeren Benutzerverzeichnis an, welches pip dann für diese Installation benutzt:
mkdir -v ~/.user-temp
TEMP=~/.user-temp pip install --user
Der Präfix mit TEMP lässt pip diesen Ort für dieses eine Installation für temporäre Daten verwenden.
**mamba** ist eine alternative Implementierung des **conda** Paketmanagers. Sie sind austauschbar, die Verwendung von **mamba** wird empfohlen.
https://github.com/mamba-org/mamba
Es gibt Situationen, wie dem Aktivieren von Environments, wo in den Beispielen trotzdem **conda** verwendet wird, weil es in Tests so funktioniert hat. Ggf. hat die Mamba-Dokumentation in solchen Situationen andere Empfehlungen. Die u.s. Beispiele funktionieren, sind aber möglicherweise nicht optimal.
==== Installation zusätzlicher Pakete per Conda/Mamba in einem eigenen Environment ====
Die Verwaltung von Softwarepaketen und Environments mit Conda erfolgt in einer Terminal-Sitzung des Notebook-Servers. Dazu muss nach der Anmeldung am Dienst eine Terminal über ''New -> Terminal'' gestartet werden.
Bevor mit "conda" oder "mamba" gearbeitet wird, sollten die Conda-Funktionen geladen werden (Punkt am Anfang beachten!):
. /opt/conda/etc/profile.d/conda.sh
=== Erstellen eines neuen Environments ===
Im Folgenden wird ein neues, einfaches Conda/Mamba-Environment ''wikidoku'' erstellt, beispielhaft das Python-Modul ''jinja2'' installiert und das Environment für das Notebook verfügbar gemacht.
Erstellen und Aktivieren des Environments:
mamba create -y --prefix ./wikidoku
conda activate ./wikidoku
Als nächstes wird beispielhaft das Paket ''jinja2'' installiert. An dieser Stelle kann nun beliebig Software aus beliebigen Conda-Channels installiert werden.
mamba install -y jinja2
Das nun aktivierte Environment wird dem Notebook-Server bekannt gemacht. ''--name'' und ''--display-name'' können frei gewählt werden, letzteres wird später in der Auswahl des Notebooks angezeigt. Der zweite Befehl listet alle bekannten Environments auf. Abschließend wird das Environment verlassen.
python3 -m ipykernel install --user --name wikidoku --display-name "Python (wikidoku)"
jupyter kernelspec list
mamba deactivate
Sollte die Installation des Kernels mit der Fehlermeldung abbrechen ''/usr/bin/python: No module named ipykernel'', dann muß zuerst das ''jupyter''-Module in dem aktuellen Environment installiert werden:
python3 -m pip install jupyter
=== Auswählen eines Environments ===
== Neustart des Notebook-Servers ==
Wurde ein neues Environment erstellt, muß zunächst der Notebook-Server neu gestartete werden. Dazu alle offenen Terminals und Notebooks schließen und in der Jupyter-Übersicht oben rechts auf ''Control Panel'' klicken. Mit ''Stop My Server'' den Notebook-Server anhalten und mit ''Start My Server''wieder starten.
Über ''New ->'' kann nun ein neues Notebook mit dem neue Environment gestartet werden. Bei einem vorhandenen Notebook kann nach dem Öffnen der Kernel gewechselt werden über das Menü ''Kernel -> Change Kernel''.
=== Installieren anderer Kernel in einem Conda/Mamba-Environment ===
Die Installation eines eigenständigen Python-Kernels nur für das aktuelle Environment ist möglich. Hier wird beispielhaft die Installation eines alten python-2.7-Kernels gezeigt.
Ein neues Environment wird nach den o.g. Schritten erzeugt und aktiviert.
Danach erfolgt die Installation der Kernels, des ''jupyter''-Moduls für den Kernel und abschließend wird der neue Kernel für den Notebook-Server aktiviert:
mamba install -y python=2.7
python -m pip install jupyter
python -m ipykernel install --user --name oldpython --display-name "Python 2.7 (oldpython)"
Der neue Kernel steht nun in neu-gestarteten Notebooks (s.o.) in der Kernel-Auswahl zur Verfügung.
Die aktuelle Kernel-Version kann in einem Notebook überprüft werden mit den folgendem Code:
import sys
print (sys.version)
=== Environment entfernen ===
Um ein Environment zu entfernen, wird es vom Notebook-Server abgemeldet und dann die zugehörigen Dateien gelöscht (optional, aber empfohlen).
jupyter kernelspec list
jupyter kernelspec remove wikidoku
rm -rf ./wikidoku
==== Installation zusätzlicher R Pakete ====
1) mkdir -p ~/R/library; mkdir ~/tmp
2) create a file "/home/jovyan/.Renviron" with 2 lines:
"R_LIBS_USER=/home/jovyan/R/library" and "TMPDIR=/home/jovyan/tmp"
3) R
4) source("https://bioconductor.org/biocLite.R")
5) biocLite()
This is because R downloads and installs packages to and from the default tmp directory,
from which it cannot execute files. Using a tmp directory inside the home directory solves
this problem.
How to install packages from Github (in R):
1) library(devtools)
2) options(unzip = "internal")
3) install_github("repo/package")
==== Transfer von Daten in das Unix/Linux-Heimatverzeichnis ====
Um den Zugriff auf größere Datenmengen auf jupyter.gwdg.de zu erleichtern, kann das Unix/Linux-Heimatverzeichnis hinzugezogen werden. Hierfür werden Daten mit dem Tool rsync transferiert. Nachfolgend ein Beispiel, das auf die jeweilige Umgebung angepasst werden muss:
Zunächst muss über das jupyter-Menü ein neues Terminal geöffnet werden: „New“ → „Terminal“
ls mynotebooks/
myfile.txt
rsync -av ~/mynotebooks/ bbrauns@login.gwdg.de:/usr/users/bbrauns/mynotebooks/
sending incremental file list
./
myfile.txt
sent 145 bytes received 44 bytes 75.60 bytes/sec
total size is 12 speedup is 0.06
Ggf. muss der jeweilige ssh-private-key in das .ssh/ Verzeichnis in jupyter-cloud hinterlegt werden. Ebenso muss der zugehörige ssh-public-key auf login.gwdg.de vorhanden sein.
Für den Zugriff auf die Daten im Unix/Linux-Heimatverzeichnis von einem Windows-Rechner siehe: [[de:services:storage_services:file_service:samba:start|Samba Server]]
==== Zusätzlichen kernel mit pipenv bereitstellen ====
Open a new jupyter terminal via the menu “New” → “Terminal”
pip install pipenv --user
mkdir myproject
cd myproject
export PATH=~/.local/bin/:$PATH
pipenv --python /usr/bin/python3.6 #needed because of conda
pipenv install ipykernel networkx
pipenv shell
ipython kernel install --user --name=projectname
* Stop and restart server via control panel
* Afterwards "projectname" is usable as new kernel
==== Zusätzlichen julia kernel installieren ====
** !Experimentell! **
(Terminal, Home Verzeichnis)
Ggf. .julia und .julia_history Verzeichnis löschen für sauberen Neuanfang.
mkdir .julia_bin
wget https://julialang-s3.julialang.org/bin/linux/x64/1.0/julia-1.0.1-linux-x86_64.tar.gz
tar -xvzf julia-1.0.1-linux-x86_64.tar.gz
cd julia-1.0.1/bin/
./julia
(Julia REPL)
ENV["JUPYTER"]="jupyter"
import Pkg
Pkg.add("IJulia")
using IJulia
exit()
(Server neustarten)
==== Zusätzliche julia Pakete installieren mit extra Kernel ====
** !Experimentell! **
Das verwendete jupyter docker stacks image hat die Variable JULIA_DEPOT_PATH auf den Pfad /opt/julia gesetzt. Dieser ist allerdings flüchtig, da nur das Home Directory persistent gehalten wird. Es wird folgend ein neuer julia kernel installiert, der sein Paket-Verzeichnis im Home Directory hat:
Start terminal
Temporarily change julia package directories:
export JULIA_DEPOT_PATH=/home/jovyan/.julia-depot
export JULIA_PKGDIR=/home/jovyan/.julia-depot
Create directory for custom packages and new julia kernel:
> mkdir /home/jovyan/.julia-depot
> julia
julia > # switch to pkg with ']' character
pkg > add IJulia # switch back to julia with CTRL+C
julia > using IJulia
installkernel("My-Julia-kernel", env=Dict("JULIA_DEPOT_PATH"=>"/home/jovyan/.julia-depot"))
Restart notebook server
Create new notebook with "My-Julia-kernel" kernel
Add package example:
using Pkg
Pkg.add("DataFrames")
==== Wir kann ich als Tutor*In größere Datensätze mit Anderen teilen ? ====
[[https://docs.gwdg.de/doku.php?id=en:services:application_services:jupyter:public-folder|Hier geht es zur englischsprachigen Beantwortung dieser Frage.]]
==== LaTeX-Pakete , TeX Live ====
In dem Notebook ist eine Basisinstallation von [[http://www.tug.org/texlive/|Tex Live]] installiert, zusätzliche das Paket "texlive-science" mit mehren Bibliotheken für mathematisch-naturwissenschaftliche Funktionen. Dies wird u.a. von [[https://matplotlib.org/|Matplotlib]] benötigt.
=== tlmgr ===
Für die installation zusätzlicher TeX-Pakete steht der Paketmanager [[https://tug.org/texlive/tlmgr.html|tlmgr]] im "User Mode" zur Verfügung.
Vor der erstmaligen Benutzung ist dieser aber kurz einzurichten, u.a. muss ggf. die Quelle der Pakete auf die korrekte TeX-Version gesetzt werden, wenn das TeX-Live-Projekt auf eine neuere Version gewechselt ist, als im Notebook aktuell zur Verfügung steht.
Im Folgenden die Schritte zur Einrichtung von "tlmgr" und der beispielhaften Installation eines Pakets:
tlmgr init-usertree
tlmgr --usermode install siunitx
tlmgr repository add https://ftp.tu-chemnitz.de/pub/tug/historic/systems/texlive/2021/tlnet-final
tlmgr option repository https://ftp.tu-chemnitz.de/pub/tug/historic/systems/texlive/2021/tlnet-final
tlmgr repository list
tlmgr --usermode install siunitx
Zuerst wird "tlmgr" initialisiert, dann versucht ein Paket zu installieren, danach basierend auf der Fehlermeldung das richtige Archiv für "tlmgr" gesetzt und die Installation wiederholt.