= Anleitung zur Administration und Verwendung einer _gitcamp_ - Schulinstanz :author: Thomas Niesenhaus include::kapitel-settings.adoc[] == Wichtige Begriffe und Rollen Dieses Dokument soll als Schritt-für-Schritt-Anleitung zum Einrichten, Verwalten und Verwenden einer _gitcamp_-Instanz an Ihrer Schule dienen. Zum besseren Verständnis werden im Folgenden häufig verwendete Begriffe und Nutzerrollen spezifiziert. * **Repository ("Repo")**: Der Ort, an dem Sie Ihren Code/ Ihre Dateien für ein Projekt einschließlich ihres Revisionsverlaufs speichern. * **Organisation**: Gruppe von Nutzern mit Zugriff auf gemeinsame Repos -> Klasse oder Kurs * **Team**: Eine Organisation kann aus mehreren Teams mit unterschiedlichen Zugriffsrechten bestehen (normalerweise: "owners" und "students") * **Schulverwalter_in**: Zuständig für die Schulinstanz. Kann als einzige Person neue Nutzer (Lehrer_innen oder Schüler_innen) anlegen, löschen, Passwörter zurücksetzen etc. * **Lehrerinnen und Lehrer**: Können neue Organisationen (Klassen) mit Teams und Organisations-Repos anlegen. * **Schülerinnen und Schüler**: Können eigene Repos anlegen, aber keine Organisationen (Klassen) oder Teams == Administration der _gitcamp_-Instanz === Nutzer_innen anlegen Das Anlegen von Nutzerinnen und Nutzern geschieht grundsätzlich durch Hochladen von ASV-Daten im CSV - Format. Im folgenden sehen Sie eine Beispieltabelle für Lehrkräfte. image::bilder/BilderAdministration/Admin1.png[] Und hier die entsprechende CSV-Datei als plain text: ---- "Gruppen";"Vornamen";"Nachname";"ID";"E-Mail" "7a";"Peter";"Muster";"43443fg-45354";"peter@muster.de" "7a, IMP8";"Ute";"Fischer";"43443fg-45354";"ute@fischer.de" "8b";"Lena";"Schmidt";"23432ab-98765";"lena@schmidt.de" "9c";"Jonas";"Meier";"56474cd-34678";"jonas@meier.de" "10a";"Sophie";"Keller";"76453ef-12345";"sophie@keller.de" "IMP8";"Max";"Bauer";"98345gh-56789";"max@bauer.de" "7b, 9c";"Laura";"Wagner";"34567ij-23456";"laura@wagner.de" ---- Die Schüler-CSV sieht im Grunde genau so aus. Lediglich das Attribut _Gruppen_ wird zu _Klasse_. Auf der Seite des Upload-Dialogs (s.u.) sind entsprechende Vorlagen hinterlegt. ==== Verarbeitung der Daten Diese Tabelle würde nach dem Upload als CSV-Datei folgendermaßen verarbeitet werden: - *Vor- und Nachname* wird importiert, aus _Vorname.Nachname_ wird der Username gebildet - Die *Emailadresse* wird entsprechend zugeordnet, falls vorhanden, ansonsten Vergabe einer Platzhalteradresse - *Klassen* - Zuordnung wird importiert, es werden automatisch entsprechende Klassen (Organisationen) mit Lehrern und Schülern gebildet Dies aus der CSV übernommenen Vor- und Nachnamen werden: * transponiert * Umlaute werden entfernt * doppelte Vornamen werden entfernt. Z.B.: aus "Ben Marlon MüllerHofholz" wird "Ben.MuellerHofholz" * Der Benutzer jedes Nutzers Users wird nach folgendem Schema erzeugt: Vorname.Nachname * Bei identischen Vornamen, Nachnamen und/oder Geburtsnamen jedoch unterschiedlicher ID wird an den generierten Nutzernamen eine fortlaufende Nummer angehängt. Beim Import von Nutzern aus der CSV-Datei werden diese bereits in die richtigen Klassen (Organisationen) eingepflegt. Nutzer, die sowohl in der CSV, als auch in der DB vorhanden sind, werden bei Bedarf neuen Klassen (Neues Schuljahr) oder zusätzlichen Organisationen (zB neue Lerngruppe) zugeordnet. Vorhandene Nutzer (DB + CSV) werden aus allen, nicht in der CSV zu diesem jeweiligen Nutzer hinterlegten Klassen gelöscht. ==== CSV - Upload Klicken Sie auf den Button _Benutzerverwaltung_ (oben rechts). Sie gelangen zur Übersichtsseite der Schulverwalter-Funktionen. image::bilder/BilderAdministration/Admin2.png[] Über _Zum CSV-Upload_ gelangen Sie nun zum Auswahldialog für den CSV - Upload: image::bilder/BilderAdministration/Admin3.png[] Wählen Sie nun jeweils Ihre CSV-Datei mit den zu erstellenden Lehrer_innen und Schüler_innen aus. Bei erfolgreicher Verarbeitung Ihrer Datei, erhalten Sie nach wenigen Sekunden eine Übersicht über alle importierten Schüler_innen und Lehrer_innen. *Achtung: Die CSV Dateien wird nur mit ";" als Trennzeichen erkannt und verarbeitet. Manche Tabellenkalkulationen speichern standardmäßig mit ",". Im Zweifelsfall entsprechende Einstellungen vornehmen bzw. die Datei im einfachen Texteditor öffnen und bearbeiten. Bitte im utf-8 Format abspeichern und alle Texte in der Datei in Hochkommas setzen.* === Passwörter ==== Initialpasswort Beim Import wird automatisch ein Initialpasswort generiert, welches bei der ersten Anmeldung geändert werden muss. Die Lehrkraft erhält per E-Mail eine Liste mit den Nutzerdaten der Klasse(n) in denen sie unterrichtet. Außerdem wird die Passwortliste unmittelbar nach dem Upload angezeigt. Es wird empfohlen, an dieser Stelle direkt einen Screenshot zu erstellen, da der Versand per Mail Stand 10/2024 nicht immer zuverlässig funktioniert hat. ==== Passwortreset Der Controller spielt je nach Lehrkraft die von ihr unterrichteten Klassen (Organisationen) in der GUI aus. Nach Auswahl der Klasse (Organisation) zeigt der Controller die Schülerinnen und Schüler der Klasse (Organisation) an. Nun kann die Lehrkraft in der jeweiligen Spalte der Schülerin oder des Schülers den Button „Passwort zurücksetzen“ anklicken. Anschließend wird der Lehrkraft ein temporäres Passwort angezeigt, welches bei der nächsten Anmeldung geändert werden muss. === Weitere Infos Weitere technische Informationen z.B. zu Löschroutinen und User-Quotas gibt es hier: xref:GitAdministrationKurzdokumentation.adoc[Kurzdokumentation IBBW]. == Organisationen und Teams Die _Organisation_ ist ein zentrales Element der _gitcamp_-Umgebung. Sie stellt eine Gruppe von Usern mit Zugriff zu gemeinsamen Repositories dar. Im Schulumfeld werden Organisationen verwendet um z.B. Klassen, Kurse und AG's abzubilden. Eine Organisation besteht aus mindestens einem _Team_. Das sind Untergruppen von Usern mit genau spezifizierten Zugriffs- und Erstellungsrechten innerhalb der Organisation. Nur Lehrer_innen dürfen Organisationen und Teams erstellen. Ob Schüler_innen Organisations-Repositories erstellen dürfen, lässt sich in den Team-Einstellungen spezifizieren. Standardmäßig ist dies nicht der Fall. Im Folgenden zeigt Ihnen die fiktive Nutzerin "Lilo Wagner" (Rolle: Lehrerin) schrittweise das Erstellen und Verwalten einer Organisation. Bitte beachten Sie, dass eine Organisation für Ihre Klasse / Ihren Kurs u.U. schon automatisch durch den Schulverwalter im Zuge des CSV-Uploads erstellt wurde (siehe oben). Wählen Sie über den "+"-Button oben rechts "Neue Organisation". image::bilder/BilderAdministration/Orgas1.png[] Wählen Sie einen geeigneten Namen für Ihre Organisation. image::bilder/BilderAdministration/Orgas2.png[] Die Sichtbarkeit Ihrer Organisation sollte in der Regel "begrenzt" (jeder eingeloggte User, also praktisch "schulweit") oder "privat" (nur für Orga-Mitglieder) sein. Nach der Erstellung sollte sich die Ansicht verändert haben. Wie links oben zu sehen, befinden wir uns nun in der Organisationsansicht. Über den kleinen Pfeil können Sie die Ansicht jederzeit zwischen allen Organisationen und Ihrer User-Ansicht wechseln. image::bilder/BilderAdministration/Orgas3.png[] Mit dem Button oben rechts gelangen Sie nun in die Detailansicht der Organisation: image::bilder/BilderAdministration/Orgas4.png[] Im folgenden Screenshot wurde der "Teams"-Tab ausgewählt. Erstellt man, eine Organisation, wird automatisch ein Team namens "Owners" erzeugt mit dem Erstellenden als einzigem Mitglied. Bei einer vom Schulverwalter per CSV_Upload automatisch erstellten Organisation gibt es im Normalfall außerdem bereits ein Team namens "Students" mit den entsprechend Schüler_innen. image::bilder/BilderAdministration/Orgas5.png[] Über den Button "Neues Team" kann man manuell ein weiteres Team erstellen. Dabei lassen sich umfangreiche Einstellungen bzgl. der Berechtigungen der Teammitglieder vornehmen. Diese sind gut beschrieben und sollten daher selbsterklärend sein. Ansonsten verweisen wir auf den entsprechenden Abschnitt der offiziellen Codeberg-Dokumentation: https://docs.codeberg.org/collaborating/create-organization/#teams . Über _Ansehen_ -> _Einstellungen_ ändern Sie diese Berechtigungen für ein bereits bestehendes Team. Dort können Sie das betreffende Team bei Bedarf auch löschen. Zum Abschluss fügen wir dem neu erstellten Team noch zwei Mitglieder hinzu. Auf der Organisationsseite gelangen wir beim neu erstellten Team "Schueler" über _ansehen_ auf folgender Seite: image::bilder/BilderAdministration/Orgas6.png[] Über das Textfeld werden nach Eingabe von mindestens zwei Zeichen entsprechende User vorgeschlagen, die man nun dem Team hinzufügen kann. Dabei findet man nur User, die unter _Einstellungen -> Profil_ die Benutzersichtbarkeit auf "öffentlich" geändert haben. Dazu klickt man zunächst auf den eigenen Avatar ganz oben rechts. == Repositories In den Repositories liegen Ihre Daten, also z.B. Ihr Quellcode oder Ihre Dokumentation. Dort geschieht auch die Versionsverwaltung für Ihr Projekt. Grundsätzlich gibt es zwei Arten von Repositories: - Repos für persönliche Projekte - Repos für Organisations-Projekte Ein persönliches Projekt wäre z.B. ein Tool, das eine Informatiklehrkraft entwickeln möchte oder ein Programmierprojekt eines Kursteilnehmenden. Organisationsrepos stellen beispielweise einer Klasse Programmier-Vorlagen samt Dokumentation zur Verfügung oder beinhalten gemeinsame Projektarbeiten von Teams aus Schüler_innen. So erstellen Sie ein neues Repository: image::bilder/BilderAdministration/Orgas7.png[] Dabei öffnet sich diese Seite: image::bilder/BilderAdministration/Orgas8.png[] Es gibt noch weitere Einstellungen, die im Normalfall nicht geändert werden müssen. Falls doch, sei erneut auf die offizielle Dokumentation verwiesen: https://forgejo.org/docs/latest/user/first-repository/ . _Besitzer_ kann entweder der User selbst oder eine Organisation sein. So erstellt man entweder ein privates oder ein Organisationsrepo. image::bilder/BilderAdministration/Orgas9.png[] Die folgende Seite zeigt nun ein leeres Repository und enthält den Link auf das selbige zur weiterverwendung in der Konsole oder einem sonstigen git-fähigen Tool. Außerdem steht ein Anleitung zur Verfügung, mit der man entweder ein neues oder ein bestehendes lokales Repository verknüpfen kann. Man kann auch im _gitcamp_ selbst neue Dateien erstellen und zu einem Repository hinzufügen. Auch wenn diese Funktion voraussichtlich eher selten zum Einsatz kommen wird, zeigen wir sie zum Abschluss kurz, um einen Blick auf die Versionshistorie einer Datei werfen zu können. Wir klicken auf _Neue Datei_ und füllen dann folgendermaßen aus: image::bilder/BilderAdministration/Orgas10.png[] Bestätigen wir nun weiter unten mit _Änderungen committen_, haben wir die erste Datei unseres Repos erstellt. Klicken Sie nun auf das Stift-Symbol, um die Datei zu ändern und fügen sie einen weiteren Satz hinzu. Nach erneutem _Commit_ sollte das Ganze in etwa so aussehen: image::bilder/BilderAdministration/Orgas11.png[] Klickt man nun auf die zweite, geänderte Version (oben), erhält man detaillierte Informationen, über die Änderungen im Vergleich zur Vorversion: image::bilder/BilderAdministration/Orgas12.png[]