Installationsanleitung¶

• Installationsanleitung
  • Systemvorraussetzungen
  • CPU
  • Memory
  • Harddrive
  • Bandwidth
  • Empfohlene Umgebung
  • Unterstützte Umgebung
  • Client
• Installation
  • Vorbereiten der Installation
  • Installation von Abhängigkeiten
  • Verzeichnisrechte
  • Einfache Verzeichnisrechte
  • Ruby Gems
  • Datenbank erstellen
  • Cron
• Konfiguration
  • Hauptkonfigurationsdatei
  • Datenbank initialisieren
  • Assets vorbereiten
  • Startscripte erstellen
    • Applikationsserver
    • Message queue
  • Webproxy einrichten
  • Virtuellen Host einrichten
    • Apache
    • Nginx
  • SSL einrichten
  • Installation abschliessen
    • Grundlegende Systemeinstellungen
    • Administratorzugang anlegen
    • Oberste Organisationseinheit anlegen
    • Setup abgeschlossen

Systemvorraussetzungen¶

CPU¶

Wir empfehlen eine mittlere 4 Kern CPU

Memory¶

Der Speicherbedarf ist abhängig von Nutzer und Zugriffszahlen und kann bei Installationen für eine größere Anzahl von Schulen steigen. Wir empfehlen mindestens 4 GB RAM

Harddrive¶

Das VSB selber benötigt max. 500 MB Platz im laufenden Betrieb. Für Datenbank und Dateien sollten 200 GB zur verfügung stehen. Abhängig von der Anzahl der geführten Schulen ist auch hier ein höherer Speicherbedarf zu erwarten.

Bandwidth¶

Mindestens 100 Mbit/s WAN anbindung

Empfohlene Umgebung¶

Debian GNU Linux 8 / Ubuntu 16.04 LTS
ruby2.4
postgresql-9.6
ImageMagick 7+
wkhtmltopdf 0.12.4+

Unterstützte Umgebung¶

Server
Server OS: any Linux
Ruby: ruby2.2+ evtl. JRuby 9.x (not well tested)
postgresql-9.4+
wkhtmltopdf 0.12.4+
ImageMagick 6+

Client¶

Desktop: Windows 7+, MacOS X 10.7+, Linux
Web Browser: IE11+, Microsoft Edge, Firefox 14+, Chrome 18+

Installation¶

Dieser Abschnitt beschreibt die Installation des virtuellen Schulboards. Ein Upgrade wird am Ende des Dokumentes beschrieben.

Es wird davon ausgegangen, das Sie einen Ansprechpartner bei er Universität zu Köln für die Installation der Software haben. Die Installation erfordert eine Registrierung durch Ihren Ansprechpartner. Ohne Registrierung ist die Installation nicht nutzbar, da die Kommunikation mit dem Schulboardnetzwerk verweigert wird.

Bitte erfragen Sie von Ihrem Ansprechpartner eine Registrierung für die Domain, unter der Sie das Virtuelle Schulboard hosten wollen. Sie bekommen dann folgende Informationen:

VSB_ID
VSB_API_KEY
CSB_API_KEY

Nach Durchführung aller Schritte ist das System für die erstmalige Konfiguration über das Webinterface bereit.

Vorbereiten der Installation¶

Das für die Installation benötigte Archiv kann heruntergeladen werden. Downloads
Der vorgeschlagene Installationsort ist /opt/vschoolboard. Dieses Verzeichnis ist im folgenden das Arbeitsverzeichnis, wenn nicht anders angegeben. Alle vorkommen von <version> müssen durch die oben angegebene Version ersetzt werden. Der Benutzer <user> ist der Benutzer, unter dem der Ruby Applicationserver ausgeführt werden wird.

Entpacken Sie das Archiv folgendermaßen:

$user> sudo -i
$root> mkdir /opt/vschoolboard; cd /opt/vschoolboard
$root> tar -xzf vsb-<version>.tar.gz

Benutzerdaten und Anwendung werden getrennt.

Führen Sie folgende Befehle aus:

$root> mv ./src ./vsb; rm vsb-*.tar.gz 
$root> mkdir -p ./data/uploads; ln -s /opt/vschoolboard/data/uploads  /opt/vschoolboard/vsb/public/uploads 

Um ein unkontrolliertes Anwachsen des Speicherbedarfs zu vermeiden, empfiehlt es sich eine Logrotationsdirektive einzurichten.

Führen Sie folgendes aus:

$root> echo "/opt/vschoolboard/vsb/log/*.log {
   daily
   missingok
   rotate 7
   compress
   delaycompress
   notifempty
   copytruncate
 }
/opt/vschoolboard/vsb/log/*.std* {
   daily
   missingok
   rotate 7
   compress
   delaycompress
   notifempty
   copytruncate
 }"  >>  /etc/logrotate.conf

Installation von Abhängigkeiten¶

Abhängig von der Umgebung gibt es verschiedene Möglichkeiten die Abhängigkeiten zu installieren. Nach Möglichkeit sollte immer der Paketmanager verwendet werden.

Führen Sie folgendes aus:

$root> apt-get update
$root> apt-get install ruby2.3 ruby2.3-dev
$root> gem install bundler
$root> apt-get install postgresql-9.5 libpq-dev wkhtmltopdf imagemagick 

Verzeichnisrechte¶

Die Verzeichnisberechtigungen für den Applikationsserver und den Webproxy sollten angepasst werden. Die korrekten Berechtigungen sind mit den Standardberechtigungen schwer umzusetzen. Daher können die Berechtigungen optional, wenn bereits erweiterte ACL‘s verwendung finden, damit eingerichtet werden.
Folgende Berechtigungen sind notwendig und auch ausreichend.

Einfache Verzeichnisrechte¶

In diesem Szenario gilt:
<group> ist die gruppe, der der Proxy-Webserver angehört. Der Benutzer, unter dem der App-Server ausgeführt wird, muss dieser Gruppe auch angehören. Benutzer <user> ist der Benutzer, der die Installation und später auch Updates durchführt.

Einfache Verzeichnisrechte geben dem Webproxy mehr Rechte als er benötigt.

Für einfache Verzeichnisrechte führen Sie aus:

$root> mkdir -p ./vsb/log ./vsb/tmp ./vsb/tmp/pids
$root> chown -R <user>:<group> ./
$root> chmod -R 750  ./
$root> chmod -R 770 ./data
$root> chmod -R 770 ./vsb/log
$root> chmod -R 770  ./vsb/tmp

Ruby Gems¶

$user> cd ./vsb
$user> bundler install --deployment

Datenbank erstellen¶

Erstellen Sie die Datenbank für das Schulboard. Es empfiehlt sich regelmäßige Backups des Datenbestandes durchzuführen. Informationen hierzu finden Sie unter https://www.postgresql.org/docs/9.6/static/backup.html
Die Daten im Verzeichnis /opt/vschoolboard/data sollten ebenfalls regelmäßig gesichert werden.

$user> sudo -i
$root> su - postgres
$postgres> psql -c "CREATE USER vschoolboard WITH PASSWORD '************';" 
$postgres> psql -c "CREATE DATABASE vschoolboard WITH OWNER 'vschoolboard' ENCODING 'utf8';" 
$postgres> exit

Cron¶

Um den Administrationsaufwand gering zu halten, werden regelmäßige Wartungsaufgaben automatisiert. Hierfür muss ein Crontabeintrag vorgenommen werden. Bestimmen Sie zunächst den Pfad für den Ruby-Paketmanager „bundler“. <bundle executable> bezieht sich auf diesen Pfad.

Führen Sie folgendes aus:

$root> exit
$user> whereis bundle
$user> crontab -e

Folgende Einträge machen:

# m h  dom mon dow   command
0 0 * * * cd ~/opt/vschoolboard && RAILS_ENV=production <bundle executable> exec rake vsb:cron['daily']
0 0 * * 1 cd ~/opt/vschoolboard && RAILS_ENV=production <bundle executable> exec rake vsb:cron['weekly']
0 0 1 * * cd ~/opt/vschoolboard && RAILS_ENV=production <bundle executable> exec rake vsb:cron['monthly']
0 0 * 1 * cd ~/opt/vschoolboard && RAILS_ENV=production <bundle executable> exec rake vsb:cron['annually']

Konfiguration¶

Im folgenden wird die Applikation und der Applikationsserver konfiguriert und das Datenbankschema initialisiert. Die Applikation wird zunächst einmal nur auf dem localhost durch den Applicationserver bereitgestellt. Später wird ein existierender Webserver als reverse-proxy eingerichtet, um den öffentlichen Zugriff zu ermöglichen.

Hauptkonfigurationsdatei¶

In der Regel muss nur diese Datei eingerichtet werden.
Im Verzeichnis /opt/vschoolboard/vsb: kopieren Sie zunächst das Template:

$user> cp config/local_env.tmpl.yml config/local_env.yml 
$user> vi config/local_env.yml

$user> rake secret

Es gibt weitere Konfigurationsdateien, die aber in der Regel nicht angepasst werden müssen. Führen Sie folgendes aus:

$user> cp config/environments/production.tmpl.rb config/environments/production.rb 
$user> cp config/puma/production.tmpl.rb config/puma/production.rb
$user> cp config/database.tmpl.yml config/database.yml

Datenbank initialisieren¶

Führen Sie folgendes aus um die Datenbank zu initialisieren:

$user> RAILS_ENV=production rake vsb:initialize

Assets vorbereiten¶

Führen Sie folgendes aus um die statischen Inhalte zusammenzustellen:

$user> RAILS_ENV=production rake assets:precompile

Startscripte erstellen¶

Es werden init scripte für den Applicationserver und die MessageQueue erstellt. Die MessageQueue wird als abhängigkeit für den AppServer definiert, daher ist für den Start der Applikation letztlich nur ein init-script verantwortlich.

<user> ist in den Startscripten der Benutzer, unter dem der Applicationserver laufen soll. Achten Sie darauf, dass er der Gruppe angehört, die Verzeichnisberechtigungen hat.

Applikationsserver¶

Erstellen Sie ein Startscript:

$user> sudo -i
$root> vi /etc/systemd/system/vschoolboard-app.service

Mit folgendem Inhalt:

 [Unit]
 Description=Application Server virtuelles Schulboard
 Requires=vschoolboard-mq.service

 [Service]
 Type=oneshot
 ExecStart=/opt/vschoolboard/vsb/srvctl.sh start production 
 ExecStop=/opt/vschoolboard/vsb/srvctl.sh stop
 RemainAfterExit=yes
 User=<user>

 [Install]
 WantedBy=multi-user.target

Message queue¶

Erstellen Sie ein Startscript:

$root> vi /etc/systemd/system/vschoolboard-mq.service

Mit folgendem Inhalt:

 [Unit]
 Description=Message Queue virtuelles Schulboard

 [Service]
 Type=simple
 ExecStart=/opt/vschoolboard/vsb/mqctl.sh start production
 ExecStop=/opt/vschoolboard/vsb/mqctl.sh stop production
 User=<user>

 [Install]
 WantedBy=multi-user.target

Aktivieren Sie die Startscripte:

$root> systemctl enable vschoolboard-app.service
$root> systemctl enable vschoolboard-mq.service

Webproxy einrichten¶

Zur Einrichtung eines reverse-proxy können verschiedene Webserver zum Einsatz kommen. Die Einrichtung wird am Beispiel Apache beschrieben. Sollte der Proxy nicht auf dem selben System laufen wie der Application Server, muss der Application Server an eine Netzwerkadresse binden, die der Proxy erreichen kann.

$user> vi config/puma/production.rb 

Hier den Eintrag bind 'tcp://127.0.0.1:9292' entsprechend anpassen. Dies ist auch nötig, wenn der Port 9292 bereits in Verwendung ist.

Virtuellen Host einrichten¶

Apache¶

Erstellen Sie einen virtuellen Host:

$root> vi /etc/apache2/sites-available/001-vschoolboard.conf

Und tragen Sie ein:

<VirtualHost *:80>
    DocumentRoot /opt/vschoolboard/vsb/public
    ServerName <schulboard-domain>
    ServerSignature Off
    ProxyRequests Off
    <Proxy *>
        Order Allow,Deny
        Allow from all
    </Proxy>
    <Location /assets>
      ProxyPass !
      Require all granted
    </Location>
    ProxyPass / http://127.0.0.1:9292/ retry=0 timeout=5
    ProxyPassReverse / http://127.0.0.1:9292/
    ProxyVia On
</VirtualHost>

Die Konfiguration aktivieren:

$root> a2ensite 001-vschoolboard.conf
$root> a2enmod proxy
$root> a2enmod proxy_http
$root> service apache2 restart

Nginx¶

Besipielkonfiguration für Nginx

upstream puma_vschoolboard {
  server http://127.0.0.1:9292
}

server {
  server_name <domain>;
  listen 80;
  root /opt/vschoolboard/vsb/public;
  underscores_in_headers on;

  location / {
    try_files $uri/index.html $uri.html $uri @ruby;
  }

  location @ruby {
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP  $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_redirect off;
    proxy_read_timeout 300;
    proxy_pass http://puma_vschoolboard;
  }
}

SSL einrichten¶

Die Anwendung sollte ausschliesslich per SSL erreichbar sein. Die Einrichtung ist nicht mehr Gegenstand dieser Dokumentation. Siehe z.B: https://httpd.apache.org/docs/2.4/ssl/

Installation abschliessen¶

Die Installation ist abgeschlossen. Starten Sie jetzt den App-Server und rufen sie das Schulboard im Browser auf:

$root> systemctl start vschoolboard-app.service

Sollten Sie die Meldung „Registrierung noch nicht durchgeführt“ erhalten, kontaktieren Sie Ihren Ansprechpartner. Ansonsten können Sie den einmaligen Setup-Prozess durchführen.

Die folgenden Schritte werden nacheinander über das Web-UI abgearbeitet, nach dem Abschluss des Setups ist dieses nicht mehr verfügbar.

Grundlegende Systemeinstellungen¶

Geben Sie den Namen dieser Installation an. Der Name wird beim Login und in der Menüleiste angezeigt.
Wählen Sie das Bundesland für diese Installation. Dies bestimmt, welche Regelsätze für den Ablauf von Fördermassnahmen verwendet werden.

Administratorzugang anlegen¶

Der Administrator bekommt unabänderliche Berechtigungen um Einrichtungen und Personen anzulegen.

Oberste Organisationseinheit anlegen¶

Tragen Sie hier die Einrichtung ein, der alle anderen Bildungseinrichtungen in dieser Installation untergeordnet sein werden.

Setup abgeschlossen¶

An dieser Stelle ist das Setup abgeschlossen und nicht mehr verfügbar. Sie sehen jetzt die gerade angelegt Einrichtung. Nutzen Sie die weitere Dokumentation für administrative Benutzer um das System weiter einzurichten und Mitarbeiter und Lehrer und Bildungseinrichtungen zu erstellen.