TL;DR

Hier findest du Dokumentation zum

• Schulstick (Quellen, Download, Installation, Booten, Starten per VM)
• und ein Quickstart-Tutorial, dass erklärt, wie Lerninhalte für den Schulstick erzeugt werden können.

Über diese Dokumentation

In diesem Repo entsteht die Dokumentation für das Schulstick Portal.

Die Dokumention wird automatisch von einer CI/CD-Pipeline gebaut und ist hier verfügbar.

Inhalte (in Arbeit)

• Zunächst wird ein Quickstart-Tutorial erstellt
  • Wir wollen den Quickstart so kurz wie möglich halten, aber so hilfreich wie möglich gestalten. Um das ermöglichen zu können, haben wir folgende Überlegungen:
    • Das Portal soll Convention over configuration umsetzen. Wir wollen minimalen Aufwand von den Tutorialserstellern (nur eine Markdown-Datei) und haben selber die geeigneten Defaults statt der Notwendigkeit zu zusätzlichen Konfigurationen.
    • Der Quickstart bewirbt und Dokumentiert endnutzerfreundlich einen Bestcase der Einfachheit. Er bindet uns gleichzeitig daran, genau nach diesem Anspruch zu Entwickeln.
    • Um den Quickstart so kurz wie möglich halten zu können und gleichzeitig alle Notwendigen Hinweise/Erklärungen/Problemlösungen bereitzustellen, arbeiten wir mit Links zu eigenen Ergänzungen. Wir liefen viele Referenzen auf ausführlichere eigene Dokumentation.

flowchart TD
  subgraph doc[Dokumentation in diesem Repo]
    Quickstart([Quickstart]) --> Nutzerdoku([ausführlichere Nutzerdokumentation])
    Nutzerdoku --> Techdoku{{technische Dokumentation}}
    Techdoku --> Spezifikation>Spezifikation]
  end
  Quickstart --> www[(vorhandene externe Quellen)]
  Nutzerdoku --> www
  Techdoku --> www
  Spezifikation --> www

• Die zusätzlich notwendigen ausführlicheren Dokumentationen / Spezifikationen werden ebenfalls in diesem Verzeichnis erarbeitet.

Der Quickstart stellt einerseits Anforderungen an die technische Umsetzung. Wir sind überzeugt, dass es sicht lohnt die Spezifikation an möglichst simple Minimalbeispiele anzupassen, weil sich genau das aus unseren Zielen ergibt. Dise bewusste Design-Entscheidung könnte als eine Art Versprechen / Claim / Anspruch an uns selbst verstanden und auch als Berbebotschaft verwendet werden.

flowchart TD
  Ziele((eigene Ziele)) --> Claim([Claim])
  Claim --> Quickstart([Quickstart])

• Um den Quickstart als Grundlage für die Umsetzung entsprechend umsetzen zu können, Enthällt dieses Repo auch eine Formulierung unserer Ziele und Versprechen…

• Um einheitliche Begriffe (und vielleicht einprägsamme „Markennamen“) zu haben, wird ein Glossar erstellt.

Schulstick

Der Schulstick ist eine freie Lern-, und Arbeitsplattform für lernende jeden Alters. Für unterschiedliche Zielgruppen existieren verschiedene Varianten.

Ein besonderer Wert des Schulsticks besteht darin, eine einheitliche Plattform für eine Vielzahl speziell angepasster und getesteter Tutorials zu bieten. Ziel ist es Nutzern (Schülern, Lehrkräften und Autodidakten) einen besonders zuverlässigen, niedrigschwelligen, frustfreien und effizienten Einstieg in neue Themen, Technologien und Softwarelösungen zu ermöglichen.

Lehrninhalte für den Stick sind freies Wissen und werden durch eine Community gemeisam erstellt und gepflegt.

Fertige USB-Sticks

Für SchülerInnen und Lehrkräfte stellen wir gerne USB-Sticks zur Verfügung, auf denen die Schulstick-Software installiert ist. Kontaktiert uns bei Bedarf oder anderen Fragen gerne unter info@schulstick.org oder nutzt unser Web-Formular.

Download

Die aktuellste Version des Schulsticks, die wir im Hackathon verwendet haben und zum Erstellen von Tutorials empfehlen, kann hier heruntergeladen werden. Unter der URL gibt es 2 Dateien zur Auswahl:

• Wer weiß, wie ein „*.img.gz“ entpackt wird, kann die 15GB große Datei herunter laden.
• Ansonsten kann die unkomprimierte „*.img“ Datei (25GB) nutzen.

Der letzte stabile Release und die offiziele Anleitung sind auf der Seite der FSFW-Dresden.

Künftig soll es auf auf der offiziellen Seite aktuelle und deutlich kleinere Images geben.

Den Schulstick starten

Folgende Anleitung setzt voraus, dass die „*.img“ Datei des Schulsticks (wie im letzten Schritt erklärt) heruntergeladen wurde. Die Datei wird im folgenden als $(SCHULSTICK_IMAGE).img bezeichnet. Nutze statt dessen bitte den Dateinamen und Pfad zu der tatsächlichen Datei.

Wir erklären hier zwei verschiedene Möglichkeiten, den Schulstick zu nutzen:

• Installieren der „*.img“ Datei auf einen USB Stick + Booten
• Start des Schulsticks in einer Virtuellen Machine (VM)

„Installation“ (einen USB-Stick mit der img-Datei bespielen)

Vorab für Linux-Benutzer, die folgenden Befehl verstehen, kann dieses Kapitel abgekürzt werden:

sudo dd if=$(SCHULSTICK_IMAGE).img of=/dev/$(USB-STICK) bs=4M status=progress 

Für alle, die sich auf der Kommandozeile (noch) nicht wohlfühlen, wird das grafische Programm Etcher empfohlen. Damit könnt ihr die komprimierte Image-Datei auswählen und auf den Stick „flashen“.

USB-Stick

Wir empfehlen USB-Sticks mit mindestens 16 Gigabyte Speicherplatz.

Der USB-Stick enthällt eine „Persistenz-Partition“, auf der Inhalte gespeichert werden, die auch nach einem Neustarten des Betriebssystems auf dem Stick weiter verfügbar sind. Diese Persistenz-Partition wird beim ersten Start automatisch so weit vergrößert, dass die gesammte auf dem Stick vorhandene Kapazität ausgenutzt wird.

Starten (Booten) des USB-Sticks

Wenn ihr einen Schulstick von uns bekommen oder wie oben beschrieben selber „installiert habt“, ist es jetzt Zeit ihn zu starten :)

1. Ihr steckt den Stick in einen USB-Anschluss eures Rechners
2. Ihr startet den Rechner bzw. ihr startet ihn neu („Reboot“)

Wenn ihr Glück habt, Startet jetzt der Schulstick oder ihr werdet gefragt ob ihr ihn starten wollt…

Wie sich euer Rechner beim Starten verhält, kann sehr unterschiedlich sein. Hier ein paar allgemeine Hinweise die hoffentlich in vielen Fällen helfen.

Wenn ihr nicht weiterkommt: fragt gerne eure Lehrer, euren Administrator oder uns.

• Möglicherweise öffnet sich ein „Boot-Menü“ indem ihr das „Boot-Medium“ auswählen könnt. Wählt hier bitte den „USB“-Stick aus.
  • Bei vielen Computern kann das „Boot-Menü“ beim starten über eine Taste geöffnet werden. Diese wird oft beim starten irgendwo klein in Englisch angezeigt.
• Bei manchen Computern muss die „Boot-Reihenfolge“ im „Bios“ geändert werden.
• In manchen Fällen muss im „Bios“ die Option „Secure-Boot“ deaktiviert werden.
• In manchen Fällen ist es wichtig, ob im „Bios“ „UEFI“ oder „Legacy-Boot“ ausgewählt wurde. Der Schulstick sollte eigentlich mit beiden Optionen funktionieren.
• Wie man auf eurem Computer ins Bios kommt, wird meistens beim Start angezeigt. Ansonsten steht es im Handbuch des Rechners bzw ihr findet dazu Informationen, wenn ihr nach dem Modell des Rechners oder der Version des Bios im Internet sucht… Viel Erfolg ;)

Wenn der Schulstick erstmal bootet (startet) funktioniert hoffentlich alles. Lehnt euch bitte kurz zurück, es kann ein paar Minuten dauern. Bei Problemen, meldet euch gerne bei uns.

Start per VM

Erstellt euch gerne selber einen Stick oder holt ein einen bei uns ab.

Ein anderer Weg den Schulstick einfach zu testen ist, das Image in einer Virtuelen Machine zu starten.

Unter Linux empfehlen wir folgenden Befehl auf der Kommandozeile:

qemu-kvm -m 4G $(SCHULSTICK_IMAGE).img

Wobei die Variable $(SCHULSTICK_IMAGE).img mit dem Pfad zur im verherigen Schritt heruntergeldenen Datei ersetzt wird.

Lerninhalte Erstellen

Mit dem Wissen aus dieser Dokumentation ist es Lehrkräften möglich, für die eigenen Bedürfnisse angepasste Varianten des Schulsticks zu erstellen. Zum starten könnt ihr unserer Quickstart-Anleitung folgen.

eigene Ziele

• geeignete Lernplatform
  • einheitlich, stabil, testbar
  • frei
• gute Lernmaterialien
  • durch Community
  • eigene Inhalte weiter verbessern
• freie Zugänge zu Wissen („frei“ wie in Freibier und wie in Freiheit)
• eine Kultur (vor-/mit-/er)leben in der Wissen selbstverständlich geteilt wird
  • dafür simple, wirkmächtige Tools bereitstellen

selbstverständlich

• Freie Software und Freies Wissen
• Public Money <-> Public Code

Claim — Womit können wir werben? / Was ist unser Anspruch?

im folgenden Ideen, über die wir uns als Team noch einigen müssen:

• „Ihr gebt uns Lerninhalte in Form einfacher Markdowndateien — Wir sorgen dafür, dass sie auf unserer Plattform nutzbar sind.“

• „Wir ermöglichen es, dass einfach erstellte Lerninhalte gut mit stabil funktionierender Software verknüpft werden kann.“

• „Unsere Tools erlauben, Lerninhalte einfach mit der erklärten Software interagieren zu lassen.“

• 4 Freiheiten: „Verstehen, Verwenden, Verbessern, Verbreiten“

Quickstart

Dieser Quickstart zeigt, wie neue Kurse für den Schulstick erstellt werden.

Markdown

Kurse für den Schulstick werden in Markdown oder der Erweiterung LiaScript erstellt. Im folgenden verwenden wir den Editor LiaEdit. Mit ihm können alle unterstützen Funktionen genutzt werden.

Wenn in diesem Schritt etwas nicht funktioniert, kann aber auch jede andere Markdown-Editor verwendet werden.

LiaEdit

Wir empfehlen den Editor LiaEdit.

Als erstes müssen wir den Editor über diesen Link öffnen

Es sollte sich ein Browserfenster öffnen, dass etwa so aussieht:

Auf der linken Seite ist eine schwarzes Texteingabefeld. Dort hinein werden wir LiaScript oder anderes Markdown schreiben.

Auf der rechten Seite sehen wir zunächst einen kurzen Einführungtext, der die Benutzung des Editors erklärt.

Hallo Welt

Wir wollen jetzt unser erstes LiaScript-Dokument erstellen.

Dafür klicken wir in das schwarze Texteingabefeld und fangen an zu tippen. Als Beispiel verwenden wir folgenes:

# Mein erster Kurs

Hallo Welt

Die erste Zeile beginnt mit dem Zeichen #. Zeilen die so anfangen werden in Markdown als Überschrift verstanden.

Wichtig: LiaScript erwartet, dass unser Dokument mindestens eine Überschrift hat. Nur die Inhalte unterhalb der ersten Überschrift werden angezeigt.

Wir drücken jetzt die Tastenkombination Strg + s. Wenn auf deiner Tastatur keine Taste mit Strg beschriftet ist, dann bestimmt mit Ctrl.

Sobald wir gleichzeitig die Tasten Strg und s gedrückt haben, sollte sich die rechte Hälfte des Fensters ändern und so aussehen:

eigene Inhalte

Wir können jetzt beliebig oft etwas ändern und mit Strg + s sehen wie LiaScript es darstellt.

Du kannst dich jetzt hier frei ausprobieren.

Mehr Infos zu LiaScript

Kurse im Portal auf dem Lernstick einbinden

Um selbstgeschriebenen Markdown-Dateien als Kurs im Portal auf dem Lernstick verfügbar zu machen, mussen wir die erstellte Datei herunterladen und in einem Ordner ablegen, wo das Portal es erwartet.

In LiaEdit klicken wir oben rechts auf „Menu“ und wählen aus dem Abschnitt „Download to“ den Eintrag „README.md“. Indem wir mit Rechtsklick auf „README.md“ klicken, geht ein Kontextmenü des Browsers auf das uns „Speichern unter“ anbietet.

Wir legen den neuen Ordner ~/.local/share/learning-portal/courses/draft/mein_quckickstart_tutorial/erste_lektion an und speichern darin die Markdown-Datei. Der Dateiname ist egal, muss aber auf „.md“ enden.

Portal neu starten

Wir können das Portal aus dem Startmenü auswählen und sollten unseren neuen Kurs sehen.

Fertig :)

Später werden wir lernen, wie mit zusätzlichen Konfigurationsdateien weitere Funktionen des Portals genutzt werden können.

Glossar

workingname „Schulstick“ -> braucht noch einen Name

• gibt viel andere tolle Varianten / Usecases als nur „Schule“ (usb-live-linux variants)

Lernstick

• sagt aus, was es ist
• aber ist etablierte Marke aus der Schweiz. Wir wollen keine Konkurenz sein und Konflikte vermeiden.

Kurssammlung

• ist eine Sammlung von Kursen
• ist eine Ordnerstruktur

„Kurse“

• ein Kurs besteht aus einer oder mehreren Lektionen
• der Begriff wird so auch von Liascript verwendet

„Lektionen“ (engl. units)

• Sind die Bestandteile von „Kursen”

Frage: Wie mappt das auf Ordner und einzelne *.md?

Im Code derzeit „Unit“ genannt

• sehr mehrdeutiger Name. Aber was wäre besser?

„Tutorial“, „Lerninhalte“, „Lernpakete“, "Lektionen"

• Ist als Synonym erlaubt
• Aber als bei Verwendung immer klar machen, dass es sich um „Kurse“ handelt

Markdown

Markdown ist eine leicht zu erlernende Auszeichnungssprache.

Die für den Schulstick erstellten Kurse werden in Markdown oder ihrer Erweiterung Liascript erstellt.

Wer nicht weiß, wie Markdown aussieht, kann sich als Beispiel die Datei anschauen, aus der die hier gerade angezeigte Seite erstellt wurde. Wie man sieht, handelt es sich bei Markdown um ein leicht lesbares Textformat, dessen „Ausgangsform“ schon recht ähnlich zur gewünschten „Zielform“ ist.

Markdown zu lernen ist einfach und geht schnell. Die wenigen nötigen Auszeichnugen werden hier beschrieben.

Zum erlernen kann der Online-Markdown-Editor Hedgedoc empfohlen werden. In ihm ist es möglich in Echtzeit nebeneinander die Ausgangsform zu editieren und die darus erstellte Zielform zu sehen. Hedgedoc erlaubt auch das gleichzeitege Editieren durch mehrere Benutzer.

LiaScript

Kurse des Schulsticks werden in einer Markdownerweiterung mit dem Namen LiaScript erstellt.

Zum Erstellen unseres ersten Tutorials reicht es vollkommen aus, einfaches Markdown ohne die zusätzlichen Möglichkeiten von LiaScript zu schreiben.

Wer in seinen Tutorials (später) LiaScript nutzen möchte, kann hier Beispiele finden.

Es gibt einen Online-Editor mit dem Namen LiaEdit, in dem nebeneinander die Ausgangsform geschrieben und die Zielform betrachtet werden kann. Das verlinkte Beispiel öffnet die offizielle LiaScript-Dokumentation, welche selbst in LiaScript geschrieben ist.

Hinweis: Im Gegensatz zu Hedgedoc, werden bei LiaEdit die Änderungen nicht sofort in der Zielform angezeigt. Zum Übersetzen muss jedes mal die Tastenkombination Strg+s gedrückt werden.

Hinweis: LiaScript zeig nur Inhalte an, wenn sie unterhalb einer Überschrift sind.

Vocabulary

@see Glossar

We reintroduce some terms from the glossar here, to make them more visible and help non german speakers to understand the structure.

• Course Collection: A course collection is a collection of one or more courses.
• Course: A course is a collection of lessons
• Lesson: A lesson is a single unit of content.
• OER: Open Educational Resources are resources that are free to use and distribute.
• Learning Portal: The Application that provides the user interface and the functionality to browse, search and play the courses.
• Schulstick: The debian based Live system, with preinstalled, preconfigured and ready to use applications and OER materials.

Courses Origin

OER materials for the learning portal can be hosted in individual repositories and contain one or more courses, which themself consist of one or more lessons.

This Learning Portal repository contains some example courses within the OER-materials folder.

Preinstalled courses packaged for the Schulstick are located in /usr/share/learning-portal/courses/examples

It is by no means required to package your courses into debian packages. But if you do so, you should place them into /usr/share/learning-portal/courses/[course_collection_name]

For a hypotetic collection of blender courses a lesson of one of the courses would be stored under:

/usr/share/learning-portal/courses/org_gitlab_artist_blender/sculpture-course/unit01

Reserved collection names

The following collection names are reserved and should not be used for your own courses:

• examples - used for example courses from the learning portal repository
• draft
• private
• unpublished

the draft, private and unpublished collections are used to store courses that are not yet published.

Course collection name

Conventionally course_colection_name should be something likeorg_gitlab_user_repo to prevent naming clashes

User added courses

Users can create their own courses by placing them in $HOME/.local/share/learning-portal/courses/draft|private|unpublished and they will automatically be added to the course list.

Or they can download courses and corse collections (manually or by using the portal app) them to $HOME/.local/share/learning-portal/courses/[course_collection_name]

Course Format and Folder Structure

flowchart
    A[course-collection-name] --> B[course.yml]
    A --> C[preview.png]
    A --> D[lesson-name]
    D --> E[lesson.yml]
    D --> F[preview.png]
    D --> G[content.md]

Because we follow a convention over configuration approach, the course folder structure is as follows, but can be reconfigured in the course.yml file in order to support different content types or a completely different folder structure.

LiaScript

LiaScript is a markdown-based authoring framework for creating interactive learning experiences. If nothing else is specified in the course.yml file, LiaScript will be used to render the course.

course-best-practice/ (free naming)
├── course.yml (optional course metadata)
├── preview.png (optional course preview image)
├── lesson-01/ (lesson folder, can be named freely)
│   ├── lesson.yml (optional lesson metadata)
│   ├── preview.png (optional lesson preview image)
│   └── content.md (lesson content name unless specified otherwise in lesson.yml)
├── lesson-02/
│   ├── lesson.yml 
│   ├── preview.png 
│   └── content.md 
└── ...

A minimal example of course collection would look like this:

course-name/
├── lesson-name/
│   └── content.md

A more concrete example:

Blender-beginner/ 
├── course.yml 
├── preview.png 
├── 01-navigation/ 
│   ├── lesson.yml 
│   ├── preview.png 
│   └── content.md 
├── 02-modeling/
│   └── ...
├── 03-materials/
│   └── ...
├── 04-lighting/
│   └── ... 
└── ...

Blender-game-development/
├── course.yml 
├── preview.png 
├── 01-scene-setup/
│   ├── lesson.yml 
│   ├── preview.png 
│   └── content.md
├── 02-animations/
│   ├── lesson.yml 
│   ├── preview.png 
│   └── content.md
└── ...
Blender-Godot-Integration/
├── course.yml 
├── preview.png 
├── 01-scene-setup/
│   └── ...
├── 02-import-blender-models/
│   └── ...
└── ...

Lesson folder names can be freely chosen, but the alphabetical order is used to determine the display order of the lessons.

MDBook

MDBook is a markdown-based authoring framework for creating books.

We also support MDBook, but it is not the default renderer.

The mdbook renderer will be chosen if the renderer field in the course.yml file is set to mdbook or if a SUMMARY.md file is present in the course folder.

A minimal example course folder for mdbook would look like this:

course-name/
├── SUMMARY.md
├── chapter-01/
│   └── content.md

title: Bereitstellen neuer Tutorials für den Schulstick

Schulstick Tutorials

Der Schulstick ist eine freie Lern-, Spiel- und Arbeitsplattform für Lernende jeden Alters. Für unterschiedliche Zielgruppen existieren verschiedene Varianten. Im Weiteren geht es um die Variante Schulstick. Alle weiteren Varianten enthalten alles, was der Schulstick enthält.

Ein besonderer Wert des Schulsticks besteht darin, eine einheitliche Plattform für eine Vielzahl speziell angepasster und getesteter Tutorials zu bieten. Ziel ist es Nutzern (Schülern, Lehrkräften und Autodidakten) einen besonders zuverlässigen, niedrigschwelligen, frustfreien und effizienten Einstieg in neue Themen, Technologien und Softwarelösungen zu ermöglichen.

Lerninhalte für den Stick sind freies Wissen und werden durch eine Community gemeinsam erstellt und gepflegt. In der FAQ werden Fragen beantwortet, wie alle, die das Projekt unterstützen wollen, unkompliziert mithelfen können.

Die folgende Anleitung erklärt alle nötigen Schritte um:

1. Zu verstehen wie die Tutorials aufgebaut sind
2. Ein neues Tutorial anzulegen
3. Tutorials im Lernportal auf dem Schulstick zu testen
4. Inhalte (z.B. Lektionen oder ganze Kurse) zu veröffentlichen

Aufbau von Tutorials

Wir sammeln und pflegen Tutorials in einem gemeinsamen Verzeichnis auf Github.

Keine Angst, für keinen der Schritte aus dieser Anleitung ist Wissen über Git notwendig. Um eine einfache Anleitung zu erstellen, müssen nur drei Dateien erstellt und uns zugesendet werden.

Hier ein einfaches Beispiel eines Tutorials:

Der Ordner enthält die nötigen 3 Dateien:

• intro.md
• metadata.yml
• preview.png

Die folgenden Abschnitte erklären für jede der Dateien, was sie beinhalten, wie sie erstellt und getestet werden können.

Für fortgeschrittene Anwendungsfälle kann ein Tutorial noch weitere Dateien enthalten. Diese werden im folgenden mit erklärt; da die Dateien aber nicht zwingend benötigt werden, können die zugehörigen Kapitel aber für das Erstellen des ersten Tutorials gerne übersprungen werden.

intro.md

Diese Datei beinhaltet die eigentlichen Inhalte.

Die Datei ist in der Auszeichnungssprache Markdown geschrieben.

LiaScript

metadata.yml

Die in Markdown/LiaScript geschriebene Datei (intro.md) ist ausreichend um eine Anleitung unabhängig vom Schulscript zu schreiben.

lesson.yml enthält alle Metadaten welche vom Schulstick-Portal benötigt werden, um zusätzliche Funktionen zu ermöglichen. Sie wird künftig optional sein.

Wir werden in einem späteren Abschnitt beschreiben, wie die Datei einfach erstellt/angepasst/getestet werden kann und welche Werte in ihr erlaubt sind.

Zunächst ist es für uns wichtig zu wissen, dass die Datei metadata.yml, welche für jedes Tutorial vorhanden sein muss, folgende beiden Zeilen enthält:

markdownFile: "intro.md"
previewImage: "preview.png"

Der Wert hinter dem Schlüsselwort markdownFile benennt die Markdown/LiaScript-Datei, welche den Anfang des Tutorials beinhaltet.

preview.png

Das Schulstick-Portal zeigt in der Liste der vorhandenen Tutorials jeweils ein Vorschaubild. In unserem Fall preview.png. Die Datei muss unter dem Name existieren, wie sie in metadata.yml unter dem Schlüsselwort previewImage benannt wurde.

Bitte suche für dein Tutorial ein geeignetes Bild heraus oder erzeuge ein eigenes. Wenn ein vorhandenes Bild verwendet wird, bitte beachte, dass es unter einer freien Lizenz steht.

optionale Erweiterungen

Die bisher betrachteten 3 Dateien sind ausreichend um ein minimales Tutorial zu erstellen.

Wenn du direkt beginnen magst, kannst du gerne direkt im Kapitel weiterlesen.

Der Vollständigkeit halber — falls du später nachschauen magst oder wenn es dich gleich interessiert — im folgenden noch die optionalen Konfigurationsoptionen für das Schulstick-Portal…

Aufteilung und Verlinkung von Tutorials und Lektionen

Wenn dein Tutorial sehr lang wird, kann es nützlich sein, das Tutorial in separate Dateien für unterschiedliche Lektionen zu unterteilen.

Die Lektionen eines Tutorials können untereinander verlinkt werden. Als Linkziel wird dafür die relative Pfadangebe der verlinkten .md-Datei angegeben.

Skripte

Motivation

Das Portal soll es ermöglichen, dass Tutorials als eng miteinander verknüpfte Kombination aus Anleitung und Anwendung bzw. Anwendungsumgebung interagieren können. Für viele Lerninhalte wird es ausreichen, wenn eine (oder mehrere) GUI-Anwendungen am Anfang einer Lektion geöffnet werden.

In einigen Fällen ist jedoch gewünscht, dem Ersteller des Tutorials mehr Kontrolle über erforderliche Umgebungen zu ermöglichen, als ein bereits vorinstalliertes Softwarepaket in seiner Originalversion zu starten. Manche Anwendungen müssen mit bestimmten Plugins, Konfigurationsdateien, sonstigen Argumenten oder in einer bestimmten Version vorhanden sein. Ein großer Mehrwert des Bereitstellens der Tutorials auf dem Schulstick ist die Möglichkeit, dass der Ersteller der Lerninhalte genau die später vom Nutzer verwendete Version der Software testen und für die entsprechende Version korrekte Screenshots einbinden kann. Wenn Software über die Zeit aktualisiert wird, kann nicht vom Kernteam des Schulsticks erwartet werden, dass immer alle Tutorials im Detail überprüft werden, ob in den Anleitungen Anpassungen nötig geworden sind. Daher ist es wünschenswert, das Wissen der Inhalteersteller zu nutzen, um zu gewährleisten, dass Anwendungen und Anleitungen aufeinander abgestimmt sind.

Hooks

Entwickelnde von Tutorials, die sich etwas besser mit Linux auskennen, können im Ordner ihrer Lektionen shell-Skripte ablegen, und bekommen folgende Möglichkeiten sich ins System „einzuhaken“:

• ./scripts/run.sh
• ./scripts/run_test.sh
• ./scripts/install.sh
• ./scripts/install_test.sh

run.sh

Wenn die Datei ./scripts/run.sh im Lektionsordner existiert, wird anstatt der in metadata.yml benannten Anwendung das Shell-Skript ausgeführt.

Auf diese Weise bekommt der Ersteller des Tutorials die Möglichkeit, GUI-Anwendungen und Komandozeilen-Umgebungen nach dem Bedürfnis des Tutorials zu starten. Das Skript läuft mit den Berechtigungen des Portal-Nutzers.

Mittels run.sh kann bei Bedarf z.B. der LiaScript-CodeRunner gestartet werden, welcher Code aus interaktiven LiaScript-Kursen evaluieren kann.

run_test.sh

Wenn die Datei ./scripts/run_test.sh existiert, wird diese beim Lektionsstart immer vor der eigentlichen Anwendung (bzw. run.sh) ausgeführt.

Dieses Skript hat den Zweck unmittelbar vor der Laufzeit zu testen, ob alle Erwartungen des Tutorial-Erstellers erfüllt sind. Beispielsweise kann überprüft werden, ob eine Anwendung in der erwarteten Version installiert ist oder ob Systemeinstellungen und auf dem System vorhandene Ressourcen den Ansprüchen genügen.

Wenn das Skript vorhanden ist, muss es sich wie folgt verhalten:

• Das Skript sollte möglichst zügig terminieren
• Der Exit-Code muss bei Erfolg 0 sein, in diesem Fall wird die Anwendung wie vom Nutzer erwartet gestartet.
• Der Exit-Code darf bei erkannten Problemen die Exit-Codes gemäß dem Standart von Nagios-Plugins zurückgeben.
• Ausgabe an stdout muss sich auf knappe, für die Zielgruppe des Tutorials verständliche Warnungen/Fehlermeldungen beschränken. Das Portal kann diese in einem Dialog an den Nutzer durchreichen.
• Ausgaben an stderr darf (beliebige) Debug-Ausgaben beinhalten. Sie werden dem Endnutzer vom Portal nicht durchgereicht.

install.sh

Während die ersten beiden Skripte zur Laufzeit und mit Benutzerprivilegien liefen, ermöglichen install.sh und install_test.sh ähnliche Funktionalität zum Zeitpunkt der Installation durch einen Nutzer mit Administratorrechten.

install.sh kann bei Bedarf Konfigurationsdateien (wie z.B. udev-Regeln) erstellen oder den Nutzer zu einer weiteren Benutzergruppe hinzufügen.

install_test.sh

Im Vergleich zu install.sh sollte install_test.sh nie die Systemkonfiguration manipulieren, sondern ausschließlich zur Installtionszeit testen.

Ausgabe und Return-Codes sollten sich genau wie bei run_test.sh verhalten.

Sicherheitsüberlegungen

Diese Skripte führen vom Tutorialersteller generierten und von der Community gereviewten Code auf dem System des Nutzers aus. Skripte und ihre Änderungen sollten daher von der Community genauso gründlich wie der Schulstick selbst überprüft werden. Für Tutorials mit Skripten wird ein Review-Prozess empfohlen, bei dem vor dem Mergen, mindestens ein Approval eines anderen vertrauten Nutzers erteilt wurde.

run.sh und run_test.sh laufen mit Nutzerprivilegien. Das Schadenspotential wird ähnlich eingeschätzt, wie jenes, welches Ersteller von Tutorials mittels bösartigen Inhalten in ihren Anleitungen verursachen können. Das erlauben wohl definierter und überprüfter Hooks kann einen Sicherheitsvorteil bieten, wenn sie einen Beitrag leisten, dass Tutorials höheren Standarts genügen müssen. Der Mechanismus der Hooks sollte genutzt werden, um dubiose Installationsanleitungen in den Tutorials konsequent zu verbieten. Dies betrifft insbesondere das Laden von Code aus Drittquellen.

install.sh und install_test.sh stellen einen Sicherheitskompromiss zu gunsten der Umsetzbarkeit, Wartbarkeit und Qualität von Inhalten dar. Idealerweise würde anstelle von install.sh alle benötigte Funktionalität ausschließlich vom Ersteller der Distribution („Schulstick“) ermöglicht und durch eine unprivilegierte Ausführung von install_test.sh getestet werden. Eine solche Umsetzung ist mittelfristig denkbar. Bis dahin können install.sh und install_test.sh eine deutliche Vereinfachung der Erstellung neuer Lerninhalte ermöglichen. Wenn vom Ersteller der Distribution install.sh und install_test.sh aller Lerninhalte reviewed werden, kann das Schadenspotential durch böswillige Ersteller von Inhalten als niedrig eingeschätzt werden.

Neue Tutorials erstellen

Tutorials im Lernportal auf dem Schulsstick testen

Inhalte veröffentlichen

FAQ

Etwas funktioniert nicht — Wo kann ich Fehler melden und um Korrektur oder Hilfe bitten?

Ich habe einen Fehler gefunden — Wie kann ich etwas berichtigen und meine erste Änderung veröffentlichen?

Features auf verschiedenen Umgebungen