Page tree
Skip to end of metadata
Go to start of metadata

Info: For english setup instructions, please take a look at the HPI Schul-Cloud Git repository's READMEs, they are written in english.




Lokale Installation der HPI Schul-Cloud

Server & Client

Variante 1: Windows 10 lokal

Node-Installation mit npm und Git wird vorausgesetzt. Die empfohlenen Versionen stehen in den Readmes der Repositories. Für die Installation direkt unter C:/ werden Administratorrechte vorausgesetzt, ansonsten kann die Arbeitsumgebung auch im Benutzerverzeichnis (C:/Benutzer/[Nutzername]) erstellt werden.

  1. Lokalen Ordner erstellen und Server sowie Client von Github ziehen:

    1. cd /d C:/ && md SchulCloud && cd SchulCloud

    2. git clone https://github.com/schul-cloud/schulcloud-server 

    3. git clone https://github.com/schul-cloud/schulcloud-client

    4. git clone https://github.com/schul-cloud/nuxt-client
  2. Pakete installieren:

    1. cd schulcloud-server && npm install

    2. cd schulcloud-client && npm install

    3. cd nuxt-client && npm install
    4. npm i -g nodemon

    5. (schulcloud-server/config/secrets.json austauschen)
  3. Datenbank einrichten

    1. MongoDB installieren (Community Server) und bei Bedarf den GUI Viewer MongoDB Compass auswählen (alternativ kann auch Robo3T oder andere Tools genutzt werden), Neustarten

    2. Datenbankordner anlegen, z.B. C:/HPI_SchulCloud/DB

    3. MongoDB-Server starten

      1. Standalone: mongod.exe mit dbpath Parameter starten (Pfad zum DB Datenspeicher, MongoDB Pfad/Version anpassen) "C:\Program Files\MongoDB\Server\3.6\bin\mongod" --dbpath "C:\SchulCloud\DB"

        1. Wenn mongod.exe nicht gefunden wird, muss der Installationspfad/bin, beispielsweise c:\Program Files\MongoDB\Server\3.6\bin\ zu den Systemvariablen hinzugefügt werden. Nach dem Ändern der systemweiten PATH muss das CMD Fenster neugestartet werden.

        2. Erfolgreich gestartet, wenn die letzte Zeile waiting for connections on port 27017 enthält

      2. oder als Service (kann während der Installation ausgewählt werden)
    4. siehe Kapitel "Datenbank mit ersten Daten füllen"
  4. Anwendungen starten
    1. (CMD: Datenbank läuft ja schon, ansonsten Datenbank starten (siehe 3c))
    2. CMD: Im schulcloud-server Ordner npm run startd bzw. npm run debug starten
      1. Erfolgreich gestartet, wenn die letzte Zeile Schul-Cloud application started enthält und http://localhost:3030/ die FeathersJS Seite zeigt
      2. Zum Debuggen mit Webstorm npm run startdebug starten
    3. Nuxt starten
      1. CMD: Im nuxt-client Ordner npm run dev:nuxt starten
    4. Client starten
      1. CMD: Im schulcloud-client Ordner npx gulp watch-reload starten
      2. Erfolgreich, wenn 3 CMD Fenster offen sind und http://localhost:4000/ die HPI Schul-Cloud Startseite zeigt.
  5. Wenn die DB bereits mit den Beispieldaten befüllt wurde (siehe 3.d), funktionieren nun bereits die Logins (siehe Logins & Infos)

Variante 2: Windows 10 mit Docker (veraltet, Aktualisierung tbd)

  1. Docker für Windows installieren, ggf. Windows Neustart bis Docker in der CMD verfügbar ist (in der CMD/PS lassen sich nun Docker Befehle ausführen, z.B. docker info)
  2. Git Server-Branch 434-docker-for-local-development und Client-Branch hs/windows-docker-setup-update-apr2018 in ein neues Verzeichnis klonen:
    1. cd /d C:/ && md SchulCloud && cd SchulCloud

    2. git clone -b 434-docker-for-local-development https://github.com/schul-cloud/schulcloud-server 

    3. git clone -b hs/windows-docker-setup-update-apr2018 https://github.com/schul-cloud/schulcloud-client

  3. CMD im Ordner schulcloud-server öffnen und docker-compose build && docker-compose up starten. 
    1. Mogliche Fehler: MongoDB Connection error während events.js: möglicher Fix ist eine Ergänzung in der docker-compose.yml des Server:
      depends_on:
        - schulcloud-server-mongodb

    2. Verbindung zu http://localhost:3030/ müsste die FeathersJS Startseite zeigen
  4. CMD im Ordner schulcloud-client öffnen und docker-compose build && docker-compose up starten. Der Client müsste laufen und http://localhost:3100/ die Schulcloud Startseite zeigen. Änderungen an Dateien müssten den Client neustarten.
    1. Relevantes Wissen: Nodemon überwacht unter Windows in Docker im normalen Modus nicht ordentlich die Dateien. Nodemon muss im Legacy Modus (--legacy-watch) gestartet werden, damit Dateiänderungen auch den Neustart triggern.
    2. Nächstes Problem: Wenn Nodemon nun node neustartet, kann nun folgendes passieren:
      Starting inspector on [address] failed: address already in use, da der Port nicht schnell genug geschlossen werden kann vor dem Neustart.
      Github Thema1 und Thema2 besprechen Ansätze des Fix:
    3. Fix: In der package.json:

      "_comment": "#### INFO: nodemon legacy watch mode and exec adjustment for windows environments",
      "win-legacy-debug": "nodemon --delay 80ms --inspect=0.0.0.0:9310 --legacy-watch --watch controllers/ --watch helpers/ --watch views/ --ext js,hbs --exec 'npm run win-legacy-start'",
      "_comment": "#### INFO: nodemon restart with 1 ping to prevent inspect address in use error",
      "win-legacy-start": "ping localhost -c 1 > /dev/null 2>&1 && node --inspect=0.0.0.0:9310 ./bin/www",


      zusammen mit der docker-compose.yml Anpassung:
      command: npm run win-legacy-debug

      Somit startet Docker den win-legacy-debug Command (Nodemon mit --legacy-watch und --exec Anpassung), win-legacy-debug ruft win-legacy-start auf und hier wird mit einem lokalen Ping eine kurze Pause vor dem node Neustart erschummelt → funktioniert.
      Aktuell ist das so nur im Client verbaut, eventuell ist der Server dahingehend auch anfällig, nicht getestet.

Probleme mit der Docker-Umgebung

  • Problem: Änderungen im static Ordner werden u.U. nicht umgesetzt.
    Lösung: schulcloud-client Docker beenden und neustarten oder über eine extra CMD auf den client-Docker zugreifen (docker exec -it [ID] bash) und gulp Befehl ausführen. Damit werden static Inhalte neu verarbeitet und unter build abgelegt.
  • Problem: Manchmal werden static Änderungentrotz Docker-Neustart/gulp nicht ordentlich umgesetzt.
    Lösung: Hart: Die Datei .gulp-changed-smart.json löschen und gulp im Container erneut ausführen. Soft: Nur den entsprechenden Teil aus der .gulp-changed-smart.json löschen, der neu generiert werden soll, z.B. > vendor-scripts":"1524811165914 < für .js Dateien im /static/vendor Ordner. Notfalls diese Lösung + Container Neustart.

Variante 3: MacOS lokal

In dieser Variante wird aus reiner Willkür der Pfad ~/SchulCloud/ benutzt. Der Pfad kann beliebig gewählt werden und muss dann natürlich konsequent in den Befehlen mitgeändert werden.

Vorraussetzungen:

  • Homebrew installiert (https://brew.sh/)
  • Node installiert (z.B. via homebrew), Version beachten! (.nvmrc)
  1. Lokalen Ordner erstellen und Server sowie Client von Github ziehen:

    1. mkdir SchulCloud && cd SchulCloud

    2. git clone https://github.com/schul-cloud/schulcloud-server 

    3. git clone https://github.com/schul-cloud/schulcloud-client

  2. Pakete installieren:

    1. cd schulcloud-server && npm install

    2. cd schulcloud-client && npm install

    3. npm i -g nodemon gulp

    4. (schulcloud-server/config/secrets.json austauschen)
  3. Datenbank einrichten

    1. MongoDB installieren (Community Server)


      1. MongoDB GUI installieren falls gewollt. Robo3T als simple variante, Studio3T als experten variante
    2. Datenbankordner anlegen, z.B. mkdir ~/SchulCloud/db

    3. Mongod starten mit --dbPath auf den Datenbankordner gesetzt. z.B.: mongod --dbpath ~/Schulcloud/db oder wenn mit brew installiert als Service starten: brew services start mongodb-community@4.2

    4. Erfolgreich gestartet, wenn die letzte Zeile waiting for connections on port 27017 enthält

    5. Im schulcloud-server ordner: npm run setup oder für mehr Kontrolle Kapitel "Datenbank mit ersten Daten füllen" ansehen


  4. Anwendungen starten

    1. (Terminal: Datenbank läuft ja schon, ansonsten Datenbank starten (siehe 3c))
    2. Terminal: Im schulcloud-server Ordner npm run start
      1. Erfolgreich gestartet, wenn die letzte Zeile Schul-Cloud application started enthält und http://localhost:3030/ die FeathersJS Seite zeigt
    3. Client starten
      1. klassisch
        1. Terminal: Im schulcloud-client Ordner gulp watch starten
          1. Wenn Gulp ein "ReferenceError: internalBinding is not defined" Fehler schmeißt: npm i natives
        2. Terminal: Im schulcloud-client Ordner npm run watch starten
        3. Erfolgreich, wenn 4 Terminal Fenster offen sind und http://localhost:3100/ die Schulcloud Startseite zeigt.
      2. mit auto-reload
        1. Terminal: Im schulcloud-client Ordner gulp watch-reload starten
        2. Erfolgreich, wenn 3 CMD Fenster offen sind und http://localhost:3100/ die Schulcloud Startseite zeigt.
    4. Wenn die DB bereits mit den Beispieldaten befüllt wurde (siehe 3.d), funktionieren nun bereits die Logins (siehe Logins & Infos)

Datenbank mit ersten Daten füllen

Variante 1 (empfohlen):

Vorbereitung Windows: mongoimport.exe-Ordner muss in PATH stehen, z.B. C:\Program Files\MongoDB\Server\3.6\bin 

Der Befehl

`npm run setup` im schulcloud-server repository befüllt die Datenbank mit initialen Daten.


Variante 2:

Mit Studio 3T eine Verbindung zu 127.0.0.1:27017 aufbauen, nachdem die MongoDB Datenbank gestartet wurde (siehe Server&Client Setup)

  1. Rechtsklick auf die Verbindung → Import → JSON → alle Dateien aus schulcloud-server/backup/setup hinzufügen und die Target Database von allen auf schulcloud setzen
  2. Import laufen lassen, dabei werden eventuell Fehler gezeigt und nicht alle Datenbanken importiert
  3. Rechtsklick auf die schulcloud Datenbank → Import → JSON → noch einmal alle Dateien aus schulcloud-server/backup/setup hinzufügen und Import starten
  4. Den Vorgang 3 ggf. wiederholen, falls es immernoch Fehler gab

Feature Flags (Umgebungsvariablen)

Um bestimmte Funktionen zu (de-)aktivieren oder Einstellungen festzulegen, sind verschiedene Umgebungsvariablen zu setzen.

BereichNameBeschreibungStandardverhaltenMögliche Werte und Verhalten
Client
SW_ENABLED
Aktiviert Service-Worker-Caching im Client-
1
Client
FEATURE_TEAMS_ENABLED
Aktiviert Teams im Clientfalse
true/false
Client+Server
NOTIFICATION_SERVICE_ENABLED
Aktiviert Notifications-
1
Server
DB_URL, DB_PASSWORD, DB_USER
Legt die Datenbankverbindung fest, wird sonst je nach NODE_ENV aus der config ausgelesen. 


Server
NODE_ENV
Legt die Umgebung fest und die zu verwendende src/config/NODE_ENV.json
default
test, production

Notification

  1. git clone https://github.com/schul-cloud/node-notification-service.git
  2. cd node-notification-service && npm install
  3. Datei secure/config.sample.json kopieren zu config.json
  4. Port in der config/default.json anpassen (Standard sollte 3031 sein), sodass er dem notification Setting in der server/config/*.json entspricht
  5. npm start

//todo Cedric Evers → neuer Notification Service 

 

Kalender

Windows 10

  • https://github.com/schulcloud/schulcloud-calendar/ klonen, in das Verzeichnis gehen und npm install ausführen
  • PostgreSQL installieren (Passwort des Nutzers postgres merken!) und ggf. Umgebungsvariable für den PostgreSQL/bin (z.B. c:\Program Files\PostgreSQL\10\bin\) Ordner setzen. Test z.B. mit psql --version
  • Einrichtung
    • Via CMD:
      • Create a user node, without password: createuser -U postgres --superuser --login node
        Create a database named schulcloud_calendar: createdb -U postgres schulcloud_calendar
        and connect to it: psql -d schulcloud_calendar -U postgres
        Prompt will change to schulcloud_calendar=#
        Grant user with all permissions for the db: grant all privileges on database schulcloud_calendar TO node;
        Prompt should be: GRANT
        Install uuid-ossp (install info) extension: CREATE EXTENSION "uuid-ossp";
        prompt should be: CREATE EXTENSION

    • Via Webinterface: Im PostgreSQL Webinterface (default http://127.0.0.1:1192/) mit Server verbinden
      • Datenbank schulcloud_calendar erstellen
      • Nutzer node erstellen, Passwort node
      • Rechtsklick auf die schulcloud_calendar→ Properties → Security → Nutzer node hinzufügen, All Rechte geben
      • Ausführen: psql -d schulcloud_calendar -U postgres  oder psql schulcloud_calendar postgres 
      • dann: CREATE EXTENSION "uuid-ossp";
  • resetDb.sh ausführen (für den psql Aufruf muss der PostgreSQL/bin Ordner als Umgebungsvariable gesetzt sein oder der volle Pfad im Skript eingebaut werden)
    • Überprüfung: In der schulcloud_calendar Datenbank ist jetzt ein public schema mit mehreren Tabellen vorhanden
    • If you get errors or must enter PW or fe_sendauth: no password supplied errors on resetDb.sh execution, edit you pg_hba.conf (im Pfad des Datenspeichers) and (temporarily!) set METHOD to trust in all lines.
  • System Variablen setzten ( siehe src/config.js )
    • SCHULCLOUD_BASE_PATH default ist localhost:3030

    • SCHULCLOUD_ALL_USERS_FOR_UUID=http://localhost:3030/resolve/users/
    • SCHULCLOUD_ALL_SCOPES_FOR_TOKEN=http://localhost:3030/resolve/scopes/
    • api key hinzugekommen, Wert ist egal, wichtig ist das der gleiche Wert im Kalender auch gesetzt wird
      • CALENDAR_API_KEY muss im SERVER gesetzt werden
      • API_KEY muss im Kalender gesetzt werden

      • ( CALENDAR_API_KEY === API_KEY )
  • Im schulcloud-calendar Ordner npm start ausführen

Files

File Service

Content

Content Service

Lokales Mailing einrichten

Das Senden von E-Mails kann über 2 Arten eingerichtet werden: lokaler oder externer SMTP Server über einen Auth oder SMTP String. Der Code dafür muss in die ....-server/src/services/helpers/service.js:

interner SMTP/Auth:


nodemailer.createTransport({
   host: 'localhost',
   port: 25,
   secure: false, // true for 465, false for other ports
   auth: {
      user: hpi,
      pass: hpi,
      type: 'login'
   }
});
let sendMail = promisify(transporter.sendMail, transporter);
return sendMail({
   from: 'smtpmailer@gmail.com', // der SMTP Server muss das Senden von dieser Adresse über den SMTP String zulassen, die Adresse muss also zum Account gehören


externer SMTP:

transporter = nodemailer.createTransport("[SMTP STRING]"); // beispielhafter SMTP String: "smtps://loginname:password@smtp.gmail.com"
let sendMail = promisify(transporter.sendMail, transporter);
return sendMail({
   from: 'smtpmailer@gmail.com', // der SMTP Server muss das Senden von dieser Adresse über den SMTP String zulassen, die Adresse muss also zum Account gehören
   ...

neXboard

Damit neXboards lokal genutzt werden können, müssen zwei Umgebungsvariablen gesetzt werden: NEXBOARD_USER_ID und NEXBOARD_API_KEY

Diese sind nur HPI Schul-Cloud intern nutzbar, da neXboard lizenzpflichtig ist.

Logins & Infos

Login in die Schulcloud mit:

Rollen & Berechtigungen

Rollen & Berechtigungen



user/

parent/student/expert

teacher

inherit from user

superhero

inherit from user

demo/

demoStudent

demoTeacher

inherit from demo

helpdesk

inherit from user

administrator

inherit from user

teammemberteamexpert

teamleader

inherit from teammember

teamadministrator

inherit from teamleader

teamowner

inherit from teamadministrator

1"BASE_VIEW""ACCOUNT_CREATE""FEDERALSTATE_CREATE""BASE_VIEW""LESSONS_VIEW""HELPDESK_VIEW""ACCOUNT_CREATE""UPLOAD_FILES""UPLOAD_FILES""EDIT_ALL_FILES""INVITE_EXPERTS""DELETE_TEAM"
2"DASHBOARD_VIEW""COURSE_EDIT""FEDERALSTATE_EDIT""DASHBOARD_VIEW""SUBMISSIONS_SCHOOL_VIEW""HELPDESK_EDIT""ADMIN_VIEW""USE_ROCKETCHAT""USE_ROCKETCHAT""ADD_SCHOOL_MEMBERS""INVITE_ADMINISTRATORS"
3"TOOL_VIEW""LESSONS_VIEW""RELEASES_CREATE""TOOL_VIEW""TOOL_NEW_VIEW"
"HELPDESK_EDIT""LEAVE_TEAM""LEAVE_TEAM""CREATE_NEWS""REMOVE_MEMBERS"
4"HOMEWORK_CREATE""NEWS_CREATE""RELEASES_EDIT""CONTENT_VIEW"

"HELPDESK_VIEW""USE_LIBREOFFICE""USE_LIBREOFFICE""CREATE_TOPICS_AND_TASKS""RENAME_TEAM"
5"PASSWORD_EDIT""NEWS_EDIT""ROLE_CREATE""HOMEWORK_VIEW"

"SCHOOL_EDIT"

"CHANGE_TEAM_ROLES""DEFAULT_FILE_PERMISSIONS"
6"FOLDER_DELETE""SCHOOL_NEWS_EDIT""ROLE_EDIT""NEWS_VIEW"

"STUDENT_CREATE"




7"FOLDER_CREATE""STUDENT_CREATE""SCHOOL_CREATE""CALENDAR_VIEW"

"SUBMISSIONS_SCHOOL_VIEW"




8"FILE_DELETE""SUBMISSIONS_SCHOOL_VIEW""SCHOOL_EDIT""RELEASES_VIEW"

"SYSTEM_EDIT"




9"FILE_CREATE""TEACHER_CREATE""SUBMISSIONS_SCHOOL_VIEW""USERGROUP_VIEW"

"SYSTEM_CREATE"




10"FILE_MOVE""TOOL_CREATE"
"TOPIC_VIEW"

"USER_CREATE"




11"CALENDAR_EVENT_CREATE""TOOL_EDIT"
"SUBMISSIONS_VIEW"

"USERGROUP_CREATE"




12"ACCOUNT_EDIT""TOOL_NEW_VIEW"
"FILESTORAGE_VIEW"

"USERGROUP_EDIT"




13"CALENDAR_VIEW""TOPIC_CREATE"
"FILESTORAGE_CREATE"







14"CALENDAR_EDIT""TOPIC_EDIT"
"TEAM_VIEW"







15"CALENDAR_CREATE""USER_CREATE"









16"FEDERALSTATE_VIEW""USERGROUP_CREATE"









17"HELPDESK_CREATE""USERGROUP_EDIT"









18"TOPIC_VIEW"










19"LINK_CREATE"










20"TOOL_VIEW"










21"NEWS_VIEW"










22"NOTIFICATION_VIEW"










23"NOTIFICATION_EDIT"










24"NOTIFICATION_CREATE"










25"PWRECOVERY_VIEW"










26"PWRECOVERY_EDIT"










27"PWRECOVERY_CREATE"










28"RELEASES_VIEW"










29"ROLE_VIEW"










30"USERGROUP_VIEW"










31"COURSEGROUP_CREATE"










32"COURSEGROUP_EDIT"










33"SYSTEM_VIEW"










34"USER_VIEW"










35"USER_EDIT"










36"HOMEWORK_VIEW"










37"HOMEWORK_EDIT"










38"HOMEWORK_CREATE"










39"COMMENTS_VIEW"










40"COMMENTS_CREATE"










41"COMMENTS_EDIT"










42"SUBMISSIONS_VIEW"










43"SUBMISSIONS_CREATE"










44"SUBMISSIONS_EDIT"










45"FILESTORAGE_VIEW"










46"FILESTORAGE_EDIT"










47"FILESTORAGE_CREATE"










48"CONTENT_VIEW"










49"CONTENT_NON_OER_VIEW"










50"FILESTORAGE_REMOVE"










51"TEAM_VIEW"










52"TEAM_EDIT"










53"TEAM_CREATE"










Einrichtung von Visual Studio Code (VS Code)

Link zur eigenen Seite

Einrichtung von Debugging mit Webstorm

Es gibt zwei verschiedene Wege, mit Webstorm die lokale HPI Schul-Cloud Instanz zu debuggen:

Debugger an laufende Prozesse attachen

  1. Der jeweilige Prozess (Client / Server / ...) muss mit dem --inspect:[port] Parameter gestartet werden. Die Startanweisungen stehen jeweils in der package.json des jeweiligen Projekts, beispielsweise:
    1. Client: "debug": "nodemon --inspect=9310 --watch controllers/ --watch helpers/ --watch views/ --ext js,hbs ./bin/www",
    2. Server: "startdebug": "nodemon --inspect=5959 src/",
  2. Anschließend in Webstorm: 
    1. Run → Edit Configurations...  oder Run → Debug... → Edit Configurations... 
    2. Hinzufügen → Attach to Node.js/Chrome
    3. Host ist jeweils localhost  und Port ist der in der package.json für inspect eingegebene
  3. Debugging starten: Während der gewünschte Dienst läuft, mit dem Debug-Button (der grüne Käfer ) starten und in der Konsole der Dienstes sollte nun Debugger attached. erscheinen.

Tests lokal ausführen


Windows

Git Bash (oder vergleichbar) wird vorausgesetzt!

git bash in npm als standard shell konfigurieren:

Shell @ schulcloud-server >

npm config set script-shell "C:\\Program Files\\git\\bin\\bash.exe"

Test-Datenbank leeren, Seed-Daten einfügen, Tests ausführen & Coverage berechnen

Shell @ schulcloud-server >

npm run test

Nur Tests ausführen

Shell @ schulcloud-server >

npm run mocha

Einzelne Tests spezifizieren

Windows


Einmal:

Shell @ schulcloud-server >

set NODE_ENV=test&& node_modules\.bin\mocha test/services/.../foo.test.js --exit

Bei jeder Code-Änderung:

Shell @ schulcloud-server >

nodemon --exec \"set NODE_ENV=test&& node_modules\.bin\mocha test/services/.../foo.test.js --exit\"

Postman

  • Im Browser den Schulcloud Client öffnen und mit dem Account einloggen von dem aus getestet werden soll.
  • Unter Cookies das JWT Token herauskopieren.
  • Postman öffnen
  • Autorisation auf bearer token umstellen und das Token einfügen
  • Auswählen ob GET, FIND, POST etc
    • bei POST oder anderem mit parametern gibt es nun einen "body" tab
    • key und value eintragen für alles was übergeben werden muss
      • einfache möglichkeit: im client die Route auslösen
      • im Network manager den content herauskopieren als url decoded
      • in Postman unter url encoded einfügen (Bulk edit)
      • dann zurück in Key edit wird der kram angezeigt und ist da
  • Die URL von der Route eintragen
  • send
  • Rückmeldung der Route wird angezeigt

Mailversand mit MailSlurper lokal testen

http://mailslurper.com/

  1. MailSlurper lokal mit Standardkonfiguration starten
  2. In `config/secrets.js` folgende Daten ersetzen:

    config/secrets.js
    {
      "smtp": "smtp://localhost:2500",
      "sendmail": {
        "host": "localhost",
        "port": 2500
      },
    ...
    }
  3. Unter `http://localhost:8080/` können nun alle versandten Mails angesehen werden.