Anleitung

⚠️

Der Dienst befindet sich aktuell in einer Testphase!

⚠️

Mit den folgenden Schritten kann eine JupyterLab-Umgebungen unter der Web-Adresse

https://jupyterlite.mintgruen.tu-berlin.de/sites/

öffentlich zugänglich oder mit Passwortschutz erstellt werden.

Um eine öffentliche JupyterLite-Seite über ein öffentliches GitLab-Projekt einrichten zu können, brauchst du lediglich

Zugang zu einem Projekt oder einer Untergruppe in der GitLab-Gruppe “JupyterLite”.

🔒 Soll die Seite darüber hinaus passwortgeschützt sein, benötigst du außerdem

ein GitLab-Projekt, dessen Sichtbarkeit auf “privat” oder “intern” gestellt ist und
eine Textdatei namens password im Wurzelverzeichnes deines Projektes mit dem entsprechenden Passwort in der ersten Zeile.

💡 In den FAQs sind Informationen aufgelistet, die bei Schwierigkeiten während der Einrichtung und Nutzung hilfreich sein können.

1. Nutzungsberechtigung anfragen

Schreibe eine E-Mail

von deinem E-Mail-Postfach der Technischen Universität Berlin
an JupyterLite <jupyterlite@innocampus.tu-berlin.de>
unter Angabe des gewünschten Namens für dein Projekt oder deine Gruppe.

Bitte beachte, dass wir Anfragen von externen E-Mail-Adressen nicht bearbeiten können.

Daraufhin wird dir ein eigenes Projekt oder eine eigene Untergruppe eingerichtet und du erhältst eine Benachrichtigung von GitLab per E-Mail, sobald die Einladung erfolgt ist.

💡 Sowohl der Projekt- als auch der Gruppenname sind Teil der URL.

2. Gruppe anpassen

Solltest du Zugang zu einer Untergruppe bekommen haben, kannst du diese nach deinen Bedürfnissen einrichten.

🔒 Die Sichtbarkeit der Gruppe bestimmt die maximal mögliche Sichtbarkeit von Projekten und damit auch, ob du überhaupt öffentliche JupyterLite-Seiten ohne Passwortschutz erstellen kannst. Standardmäßig ist die Sichtbarkeit deiner Gruppe auf “öffentlich” eingestellt und erlaubt damit Webseiten sowohl ohne als auch mit Passwortschutz.

3. Projekt auf GitLab einrichten

Hast du ein Projekt angefragt, kannst du es mit dem Folgen der Einladung an deine Anforderungen anpassen. Wurde für dich eine Gruppe erstellt, ist es dir nach dem Beitritt möglich, eigene Projekte oder Untergruppen zu erstellen. Es existiert ein Beispielprojekt, was du als Referenz oder Basis für dein Projekt nutzen kannst.

🔒 Soll deine JupyterLite-Seite mit einem Passwort geschützt werden, stelle die Sichtbarkeit deines Projektes auf “intern” oder “privat”. Standardmäßig ist ein dir gegebenes Projekt “öffentlich”.

💡 Der Projektname ist wie der Gruppenname ebenfalls Teil der URL.

4. Inhalte hinzufügen

In deinem Projekt kannst du über die folgende Ordnerstruktur

<gitlab-projekt>
 ├── files                     # statische Dateien
 │   ├── data.csv
 │   ├── introduction.ipynb
 │   └── ...
 ├── jupyter-lite.json         # Laufzeit-Konfiguration
 ├── overrides.json            # Einstellungen von Plugins
 ├── jupyter_lite_config.json  # wird ignoriert
 └── password                  # privates/internes Passwort

deine JupyterLite-Seite anpassen.

Dateien unter files/ finden sich in der Datei-Übersicht der JupyterLite-Seite wieder.

Über jupyter-lite.json können die Laufzeit-Einstellungen der JupyterLite-Seite angepasst werden.

Die overrides.json-Datei kann verwendet werden, um Plugin- und Erweiterungseinstellungen zu überschreiben.

Eine jupyter_lite_config.json wird ignoriert, da sie Kompilierungseinstellungen enthält, die dem Dienst bereits vorliegen.

🔒 Ist die Sichtbarkeit deines Projektes auf “intern” oder “privat” gestellt, benötigst du außerdem eine Passwort-Datei im Wurzelverzeichnis deines Projektes. Diese Datei muss mit password benannt werden, ist eine einfache Textdatei (ohne “.txt”-Endung) und enthält dein Passwort auf der ersten Zeile. Bei öffentlichen Projekten wird sie ignoriert.

🔒 Als Nutzername wird der Name des GitLab-Projektes verwendet.

5. Seite erzeugen und abrufen

Durch einen neuen Commit auf dem Standardbranch “main” wird die zum Projekt gehörende JupyterLite-Seite unter

https://jupyterlite.mintgruen.tu-berlin.de/sites/<gruppe>/<gitlab-projekt>

nach der Kompilierung zur Verfügung gestellt. Dieser Vorgang wird über einen Webhook realisiert und dauert in der Regel nur ein paar Sekunden.

🔒 Ist dein Projekt nur “privat” oder “intern” sichtbar, wirst du beim Aufruf deiner JupyterLite-Seite nach Zugangsdaten gefragt. Gib als Nutzernamen den Namen deines Projektes und das Passwort aus der in Schritt 4 angelegten Passwort-Datei password an.

💡 Die Schreibweise von <gruppe>/<gitlab-projekt> kann der URL zu deinem GitLab-Projekt

https://git.tu-berlin.de/jupyterlite/<gruppe>/<gitlab-projekt>

entnommen werden.

💡 Die Ausgabe des aktuellen Kompilierungsvorgangs ist unter

https://jupyterlite.mintgruen.tu-berlin.de/sites/<gruppe>/<gitlab-projekt>/build-log.html

einsehbar und eventuell für die Fehlersuche hilfreich.

FAQ

Was ist JupyterLite?

JupyterLite ist eine Distribution von JupyterLab. Durch die Verwendung von Pyodide, einer Portierung von Python zu WebAssembly, ist eine Entwicklungs- und Programmierumgebung möglich, welche vollständig lokal im Browser läuft. Das beinhaltet sowohl die Ausführung des Codes als auch das Speichern bearbeiteter Dateien. Der Server stellt lediglich die erforderlichen Daten zum Download zur Verfügung.

JupyterLite befindet sich derzeit in aktiver Entwicklung. Der Funktionsumfang ist im Vergleich zu JupyterLab eingeschränkt.

Warum JupyterLite?

Pro:

🟢 kein Installationsprozess
🟢 lokal im Browser, keine externen Server
🟢 kein Account-Management

Contra:

🟡 in früher Entwicklungsphase, eingeschränkter Funktionsumfang
🟡 Limitierungen durch den Browser
🔴 fragile Speicherlösung für lokal bearbeitete Dateien

Wir empfehlen daher die Nutzung von JupyterLite, wenn eine JupyterLab-Umgebung

ohne besondere Hardware- und Software-Anforderungen auskommt,
nicht für Projekte von besonderer Wichtigkeit oder Komplexität wie beispielsweise Abschlussarbeiten genutzt wird und
lokale Änderungen regelmäßig über Downloads gesichert werden können,

wie es zum Beispiel bei Einführungen ins Programmieren der Fall ist.

Es wurde eine neue Version der JupyterLite-Seite veröffentlicht. Wie komme ich an die neuen Daten?

Lokal bearbeitete Dateien werden in der Browser-internen IndexedDB abgespeichert und beim Aufruf der Seite wieder daraus geladen. Um eine neue Version einer Datei vom Server zu erhalten, muss die lokal bearbeitete Datei umbenannt oder gelöscht werden. Der Download erfolgt danach in der Regel automatisch.

Falls der automatische Download nicht funktioniert und die alten Versionen angezeigt werden, helfen eventuell manuelles Neuladen der JupyterLite-Seite oder gar das Löschen der dazugehörigen Browserdaten. Letzteres löscht allerdings alle vorgenommenen Änderungen!

Ich bekomme einen Fehler “401 - Authorization Required”. Was bedeutet das?

Die JupyterLite-Seite ist passwortgeschützt und die im Browser gespeicherten Zugangsdaten sind falsch. Rufe die Seite erneut auf, aber diesmal unter Angabe von (willkürlichen) Zugangsdaten in der URL:

https://<zufälliger-nutzername>:<zufälliges-passwort>@jupyterlite.mintgruen.tu-berlin.de/sites/<gruppe>/<gitlab-projekt>

Entweder ist die Authentifizierung erfolgreich oder du wirst erneut nach den korrekten Daten gefragt.

Welche Pakete sind in der Kompilierungsumgebung vorhanden?

Im Folgenden ist der Inhalt der requirements.txt zu sehen, welcher zur Bereitstellung der Kompilierungsumgebung auf dem Server genutzt wird. Wenn dir eine Jupyter-Erweiterung fehlt, schreibe eine E-Mail an JupyterLite <jupyterlite@innocampus.tu-berlin.de> und deine Anfrage wird geprüft.

Bitte beachte, dass andere Pakete wie numpy, welche nicht Teil von Jupyter-Erweiterungen sind, nicht durch die Kompilierung in deine JupyterLite-Seite integriert werden können. Diese müssen nach dem Aufruf der JupyterLite-Seite in der Konsole oder einem Notebook importiert werden.

Sollten die installierten Pakete nicht deine Anforderungen erfüllen, gibt es auch die Möglichkeit, das statische Webhosting-Angebot der ZECM zu nutzen.

# Core modules (mandatory)
jupyterlite-core==0.4.1
jupyterlab~=4.2.5
notebook~=7.2.2


# Python kernel (optional)
jupyterlite-pyodide-kernel==0.4.2

# JavaScript kernel (optional)
jupyterlite-javascript-kernel==0.3.0

# Language support (optional)
jupyterlab-language-pack-fr-FR
jupyterlab-language-pack-zh-CN

# P5 kernel (optional)
jupyterlite-p5-kernel==0.1.0

# JupyterLab: Fasta file renderer (optional)
jupyterlab-fasta>=3.3.0,<4
# JupyterLab: Geojson file renderer (optional)
jupyterlab-geojson>=3.4.0,<4
# JupyterLab: guided tour (optional)
# TODO: re-enable after https://github.com/jupyterlab-contrib/jupyterlab-tour/issues/82
# jupyterlab-tour
# JupyterLab: dark theme
jupyterlab-night
# JupyterLab: Miami nights theme (optional)
jupyterlab_miami_nights

# Python: ipywidget library for Jupyter notebooks (optional)
ipywidgets>=8.1.3,<9
# Python: ipyevents library for Jupyter notebooks (optional)
ipyevents>=2.0.1
# Python: interative Matplotlib library for Jupyter notebooks (optional)
ipympl>=0.8.2
# Python: ipycanvas library for Jupyter notebooks (optional)
ipycanvas>=0.9.1
# Python: ipyleaflet library for Jupyter notebooks (optional)
ipyleaflet

# Python: plotting libraries (optional)
plotly>=5,<6
bqplot

Ich habe ein Problem mit dem Dienst. Wo bekomme ich Hilfe?

Log-Einträge der Kompilierung sind unter

https://jupyterlite.mintgruen.tu-berlin.de/sites/<gruppe>/<gitlab-projekt>/build-log.html

einsehbar. Diese sind eventuell hilfreich für den Fall, dass deine JupyterLite-Seite nicht wie erwartet funktioniert.

Solltest du darüber hinaus Hilfe benötigen, schreibe eine E-Mail an JupyterLite <jupyterlite@innocampus.tu-berlin.de> mit deinem Anliegen.

Wie kann ich meine Seite löschen?

Schreibe bitte eine E-Mail

von deinem E-Mail-Postfach der Technischen Universität Berlin
an JupyterLite <jupyterlite@innocampus.tu-berlin.de>

und du erhältst eine Bestätigung, sobald deine Seite entfernt wurde.