Workshop: Einführung in Architektur und Technologie

Alwin Egger edited this page Nov 24, 2016 · 9 revisions

Dokumentation

OpenOlitor-Versionen

Doku nach Menupunkten

Doku nach Masken

Doku nach Abläufen

Doku globale Bedienungselemente

Doku Konfigurations-Checkliste

Technische Dokumentation

Documentation (fr)

[Docu selon rubriques de menu]

[Docu selon masques]

Docu en fonction des processus de travail

[Docu des éléments globaux d'utilisation]

Docu check-list de configuration

[Docu des composantes du serveur]

[Docu des composantes Web]

Documentation (en)

Technical documentation

Clone this wiki locally

Ziel

Ziel des Workshops ist es einen Einblick in die technische Umsetzung von OpenOlitor zu geben. Wir erklären die genutzten Werkzeuge, die vorhandenen Komponenten, die verwendete Technologie und zeigen anhand einiger Beispiele, wie OpenOlitor funktioniert. Zudem wollen wir vermitteln, wo die einfachsten Anknüpfpunkte zur aktiven Mitarbeit an OpenOlitor bestehen und wie die Abläufe zur Qualitätssicherung aussehen.

Ablauf

Folgender Ablauf ist geplant. Unten stehen einige Details zu den Inhalten der einzelnen Programmpunkte.

  1. Begrüssung / Vorstellungsrunde
  2. Kurzpräsentation von sunu und OpenOlitor: Motivation, was bisher geschah, aktueller Stand, geplante Aktivitäten
  3. Einführung zu OpenOlitor: Wie präsentiert sich die Web-Applikation? (Kurzer Einblick auf Demo-Seite)
  4. Werkzeuge und Komponenten: Was befindet sich wo?
  5. Plattform: PaaS - Cloud Foundry
  6. Web-Technologie: AngularJS und Co.
  7. Backend-Technologie: Scala, Events
  8. Einige Kernfragen/Konzepte
  9. Projektbeteiligung, Qualitätssicherung
  10. TODOs auf technischer Ebene

Infos & Links zu den Programmpunkten

3. Einführung zu OpenOlitor

OpenOlitor kann auf einer Demo-Installation getestet werden wwwdemo.openolitor.ch.

4. Werkzeuge & Komponenten

Sämtlicher Code steht auf Github zur Verfügung. Die Applikation haben wir in verschiedene Komponenten unterteilt:

Komponente Technologien Link
Admin-Portal AngularJS, CSS, HTML /OpenOlitor/openolitor-client-admin
Kundenportal-Portal AngularJS, CSS, HTML /OpenOlitor/openolitor-client-kundenportal
Fronted Core AngularJS, CSS, HTML /OpenOlitor/openolitor-client-core
Server Scala: Akka, Spray /OpenOlitor/openolitor-server
PDF-Tools-Server Java: Spring; LibreOffice /OpenOlitor/openolitor-tools-pdf

Zudem setzen wir einige Dienste und Werkzeuge ein, welche uns das Leben erleichtern:

Dienst/Werkzeug Aufgabe Link
Crowdin Übersetzungen (kann auch mit Poedit gemacht werden) translate.openolitor.org
Travis Continuous Integration travis-ci.org/OpenOlitor/
Jenkins Continuous Integration (Wenn gewünscht: (Continuous) Deployment Tegonal intern
Atom & Ensime IDE (JavaScript, Scala) atom.io ensime.github.io
Scala-IDE Eclipse basierte IDE (Scala) scala-ide.org

5. Plattform

OpenOlitor wird für die Schweizer Vertragslandwirtschafts-Initiativen auf der Cloud-Plattform der Swisscom ausgeführt. Diese nutzt die OpenSource Technologie-Plattform Cloud Foundry. Alle Komponenten sind demnach vorbereitet bei Swisscom oder jedem anderen Cloud Foundry Anbieter mit nur wenigen Schritten Installiert zu werden.

Grundsätzlich kann OpenOlitor aber auch auf anderen Cloud-Plattformen installiert werden. Auch eine unabhängige Installation auf einer selber unterhaltenen Server-Infrastruktur ist möglich. Folgende Server-Komponenten sind notwendig:

Komponenten Mögliche Produkte
Web-Server Apache Server, nginx
Java-VM Laufzeitumgebung für Java von Oracle oder OpenJDK
SQL-Datenbank MariaDB / MySQL und PostgreSQL sind unterstützt. Grundsätzlich aber jede SQL-Datenbank mit funktionierendem Java-Treiber möglich. Allerdings nicht ohne Code-Anpassungen.
S3-Storage Swisscom und Andere bieten S3 kompatible Speicher an. Es gibt verschiedene OpenSource Implementationen, bspw. /scality/S3

6. Web-Technologie

Das Web-Frontend basiert auf dem AngularJS Framework (Version 1.5.x). Da im Frontend-Bereich das grösste Bedürfnis nach individuellen Anpassungen liegt, haben wir hier eine Technologie gewählt, welche viele schon kennen und einfach zu erlernen ist.

Hier eine kurze Auflistung der hauptsächlich genutzten Frameworks:

Framework Zweck Link
grunt Build-Tool gruntjs.com
bower Abhängigkeiten verwalten bower.io
AngularJS Java-Script Framework AngularJS
Bootstrap CSS Framework getbootstrap.com
GNU gettext Extraktion von zu übersetzenden Texten www.gnu.org/software/gettext/

Die Applikation wird mit gebaut und hilft die Abhängigkeiten zu verwalten.

6.1. Build & Deployment

Um den Client lokal zu builden und zu starten, sind nur wenige Schritte notwendig. Die Dokumentation dazu befindet sich hier.

Die Installation auf einer Cloud-Infrastruktur ist hier beschrieben (muss noch ausgebaut werden).

Das Deployment kann mit wenig Aufwand automatisiert werden. Wir haben unsere Jenkins-Tasks so eingerichtet, dass nach dem erfolgreichen Build die gewünschten Server-Instanzen neu installiert werden.

7. Backend-Technologie

Für das Backend nutzen wir die Programmiersprache Scala. Diese resp. die darauf aufbauenden Frameworks sind für reaktive Web-Applikationen optimiert. Da der kompilierte Code auf der Java Virtual Machine ausführbar ist, kann auch diese OpenOlitor-Komponente auf allen gängigen Plattformen betrieben werden. Wir haben also keine Abhängigkeit von einem bestimmten Betriebsystem.

Hier eine kurze Auflistung der hauptsächlich genutzten Frameworks:

Framework Zweck Link
Akka Event-Handling akka.io
Spray Anbieten der Rest-API spray.io
scalikejdbc OR-Mapping scalikejdbc.org
Apache ODF Toolkit ODF Manipulation incubator.apache.org/odftoolkit

7.1. Build & Deployment

Um den Server lokal zu builden und zu starten, ist leicht komplizierter, da auch Abhängigkeiten wir DB und S3-Storage bereit gestellt werden mssen. Die Dokumentation dazu befindet sich hier.

Die Installation auf einer Cloud-Infrastruktur ist hier beschrieben (muss noch ausgebaut werden).

Das in 6.1 beschriebene automatische Deployment mittels Jenkins funktioniert natürlich genauso für die Server-Komponente.

8. Einige Kernfragen/Konzepte

8.1. Security

Grundsätzliches: Die Web-Applikation und Rest-APIs sind alle per SSL geschützt. Passwörter werden nicht Plain-Text sondern gehasht abgelegt.

8.2. Authentisierung / Autorisierung

Ein umfassende Berechtigungserteilung für jede Funktion mit einer Pflege von Benutzern, Rollen, Berechtigungen ist gegenwärtig nicht vorgesehen. Es existieren verschiedene Rollen: Administrator, Kunde, ...

9. Projektbeteiligung, Qualitätssicherung

Hier müsste nach etwas mehr zur Organisationsstruktur von OpenOlitor stehen und den vorgesehenen Prozessen...

Werkzeug Beschrieb, Ablauf
Dokumentation Wir vollumfänglich im diesem Github-Wiki gepflegt, ist aber noch dürftig. Wikis müssen noch zusammengeführt werden (siehe TODOs)
Issue Management Fachliche aber auch technische Anforderungen können in Github erfasst und verfolgt werden.
Code Review Wir speisen neuen Code mittels Pull-Requests ein. Das heisst, jede Änderungen wir von mind. einer zusätzlichen Person validiert. Externe Commiter können die OpenOlitor-Repositories klonen, Code einfügen und dann ebenfalls Pull-Request machen.
(Unit) Tests Core Komponenten verfügen über Unit-Tests. Diese werden beim Build ausgeführt, auch bspw. auf Jenkins. Schlägt ein Test fehl, wird nicht installiert. Nie.

10. TODOs auf technischer Ebene & Betrieb

Wie in jeden Projekt gibt es einige Dinge, welche wir aus verschiedenen Gründen (Zeitaufwand, Verfügbarkeit von Komponenten, ...) noch nicht gemacht haben. Bei Anderem haben sich im Projektverlauf die Voraussetzungen verändert, so dass wir in Zukunft Anpassungen vornehmen werden müssen.

TODO Beschrieb
Naming der Entitäten auf Englisch Wir hatten nicht erwartet, dass sich so rasch eine internationale Community für OpenOlitor interessiert
Englisch als Basissprache für Übersetzungen (UI)? Dito oben
Trennen von Batch Processing von Rest-API So könnte der Server-Komponente durch Vervielfachung der Nodes effizient skaliert werden. Ist erst bei vielen >10 Mandanten notwendig.
Migration von Spray zu akka-http Die Welt dreht sich weiter und Frameworks verändern sich...
Migration auf nur ein Wiki Zurzeit haben wir verschiedene Wikisa aktiviert in den Repos der unterschiedlichen Komponenten. Diese sollten in einem Wiki zusammengefasst werden.

Es gibt sicher noch weitere TODOs. Neue Wünsche oder Anfroderungen können gerne ins Github Issue Management eingetragen werden.