Dieses Projekt beinhaltet alle Informationen und den Quellcode rund um die Digitalisierung des Anmeldeprozesses für Kinder der Stadt Weimar in Thüringen für Sommerferien-Aktivitäten im Rahmen des gemeinnützigen Ferienpass-Projektes.
Das Projekt wurde ursprünglich von Studierenden der Bauhaus-Universität Weimar im Rahmen eines Projektseminars von 10/2017 bis 04/2018 entwickelt.
Die Ergebnisse dieser Arbeiten sind in den folgenden zwei Microservices abgebildet:
https://github.com/digital-bauhaus/Ferienpass-Anmeldung
https://github.com/digital-bauhaus/Ferienpass-Admin
Das vorliegende Projekt dient dazu die Ergebnisse des Studenten-Projektes, welches in einer Alpha-Phase 2018 getestet wurde, produktionsreif zu machen.
Dazu steht der gesamte Quellcode als OpenSource zur Verfügung und bietet somit allen Interessierten die Möglichkeit mitzuentwickeln. So geschehen z.B. im Mai 2019 im Rahmen eins Hackathons.
2020 wurde das Projekt erstmals erfolgreich für die digitale Anmeldung zum Ferienpass eingesetzt.
Über das Projekt wurde mehrfach berichtet: BAUHAUS.JOURNAL ONLINE 2018-01-16 & Thüringer Allgemeine 2018-01-17 & Thüringische Landeszeitung 2018-01-17 & Focus Online & codecentric.de & final celebration, Focus Online & Thüringer Allgemeine 2018-07-14 & Thüringer Allgemeine 2020-06-16
Die Anmeldungsseite steht direkt auf der Startseite zur Verfügung (lokal http://localhost:8088/), die Administrationsfunktionen liegen tiefer und finden sich ab http://localhost:8088/login.
Ausschnitt aus dem Anmeldeformular (Beispieldaten):
Anlegen einer Veranstaltung im Verwaltungsbereich (Beispieldaten):
Übersicht über alle Veranstaltungen im Verwaltungsbereich (Beispieldaten):
Der Login unter https://ferienpass.herokuapp.com/login ist nun abgesichert - die Credentials werden lokal über die application.properties konfiguriert, im PR bzw. Produktivdeployment über Umgebungsvariablen in Heroku:
# application.properties
spring.security.user.name=test
spring.security.user.password=foo
# Heroku Environment Variables
SPRING_SECURITY_USER_NAME=xyz
SPRING_SECURITY_USER_PASSWORD=xyz
Die Mails für die erfolgreiche Anmeldung werden nun mit Hilfe des Heroku-Addons Sendgrid verschickt. Im genutzten Free-Tier sind 12.000 freie Mails inbegriffen pro Monat.
Der Test dafür benötigt lokal eine manuell zu setzende Umgebungsvariable SENDGRID_API_KEY=korrekterKey mit dem korrekten Key (den Key am besten aus der Heroku-Configvar beziehen!) - z.B. innerhalb der Run Configurations der IDE.
Innerhalb von TravisCI wird auch die Environment Variable benötigt.
Der Inhalt der Mail wird über die Datei mailtext.txt beschrieben.
Die bisherige Microservice-Struktur wird zugunsten einer vereinfachten Weiterentwicklung und Wartung aufgegeben und in einen Mini-Monolithen bzw. Microlithen überführt.
+-------------------+ +--------------------+
| | | |
| | | |
| | | |
| Anmeldung | | Verwaltung |
| (Vue.js) | | (Vue.js) |
| | | |
| | | |
+-------------------+ +--------------------+
| |
+---------v-----------------------v----------+
| |
| |
| |
| Spring Boot Backend (REST API) |
| |
| |
| |
+--------------------------------------------+
|
v
+---------------------------+
| |
| Postgres-DB |
| (lokal H2 in-memory) |
| |
+---------------------------+
Die beiden fachlichen Frontends sind dabei als gemeinsames Vue-Projekt umgesetzt: Modul/Unterordner frontend.
Das Spring Boot Backend befindet sich im Modul/Unterordner backend.
- Java
- npm (optional, für lokale Frontend-Entwicklung)
MacOS
> brew cask install java
> brew install npmWindows
> choco install jdk
> choco install npmLinux
> apt-get install jdk
> apt-get install npmWir nutzen den maven-wrapper. Dadurch wird keine eigene Maven-Installation benötigt.
Unter Linux und Mac kann der maven-wrapper so eingesetzt werden
./mvnw <maven command here>
Unter Windows erfolgt der Aufruf mit
mvnw.cmd <maven command here>
Im Folgenden gehen wir immer von Aufrufen unter Linux aus.
Der folgende Befehl baut das frontend-Projekt und kopiert die dabei entstehenden Artefakte in den resources-Ordner des backend-Projektes. Dadurch kann es direkt vom eingebetteten Tomcat-Server des Spring Boot Backends ausgeliefert werden.
> .mvnw clean installBackend-Server starten
> .mvnw --projects backend spring-boot:runDieser läuft dann auf Port 8088 und stellt dort die REST-API und die Frontends bereit.
REST-API:
http://localhost:8088/api
http://localhost:8088/swagger-ui.html
Anmeldungs-Frontend:
http://localhost:8088/#/
Verwaltungs-Frontend:
http://localhost:8088/#/Veranstaltungen/
Für die lokale Entwicklung des Frontends ist es einfacher die entsprechenden Targets aus der package.json des frontend-Moduls zu verwenden.
Dafür muss zuerst (wie oben beschrieben) der Backend-Server gestartet werden, damit die REST-API zur Verfügung steht.
Danach kann mit folgendem Befehl ein lokaler Entwicklungsserver auf Port 8080 gestartet werden, der u.a. Hot-Reload unterstützt.
cd frontend
npm run serve
Anmeldungs-Frontend:
http://localhost:8080/#/
Verwaltungs-Frontend:
http://localhost:8080/#/Veranstaltungen/
Weitere Informationen in der README des frontend-Moduls.
Tests werden automatisch bei jedem Push auf den Feature-Branches oder den master durch TravisCI ausgeführt und es finded ein automatischer Deploy auf Heroku statt, wenn der TravisCI build erfolgreich durchgelaufen ist.
Entwickelt werden soll mit Hilfe von Feature-Branches und Pull-Requests - der master-Branch ist als "Produktions-ready" immer baufähig zu halten.
- Clone: lokal das Repository clonen per
git clone https://github.com/digital-bauhaus/Ferienpass.git - No Merge Commits: lokal das Erstellen von Merge-Commits unterbinden mit der Einstellung:
git config --global pull.rebase preserve - Focus on Issues: auf GitHub ein Issue auswählen oder neu erstellen
- Create Branch: dann einen neuen Branch erstellen nach dem Muster
feature/#issueNummer-issue-titel, z.B.feature/#2-kostenplichtige-anmeldung - lokal pullen und entwickeln
- Do Tests run? Vor dem Commit sicherstellen, dass alle Tests laufen und die Anwendung baut
- Commit message! Beim Commit darauf achten, dass der Kommentar die GitHub-Issue-Nummer enthält, z.B.
#4 Neuer Button erstellt - Pushen
Wenn dein Feature fertig ist:
Pull Request auf GitHub erstellen
Review App:
Hinweis: Aktuell sind die Review-Apps deaktiviert, da Dependabot sehr viele PRs für Version-Updates erzeugt und es scheinbar nicht möglich ist Review-Apps in Heroku spezifisch automatisch zu erstellen (siehe #175).
Heroku erstellt nun automatisch eine Review-App für diesen Pull-Request (Access für die Pipeline bitte bei jonashackt anfragen):
Heroku erstellt eine eigene URL für die Anwendung, unter der sie getestet werden kann. Die URL kann über Open App in browser über den kleinen Button neben der App geöffnet werden:
PR prüfen
Auf GitHub werden alle Commits, die Builds sowie die Heroku-Deployments vollständig im Pull Request dargestellt:
Wenn alles passt, kann das Featuer in den master-Branch gemergt werden per Merge pull request. Danach landed der Stand automatisch auf Staging bzw. Produktion!
Delete Feature-Branch:
Direkt auf GitHub im Pull Request sollte man den Feature Branch gleich noch löschen! Dann wird auch auf Heroku die Review App wieder weggeräumt (und verursacht keine Kosten!).
local master FTW:
Lokal nun wieder auf den master-Branch wechseln und das Projekt neu pullen, der alte Feature-Branch sollte nun auch lokal gelöscht sein.
Die pre-produktive / produktive Anwendung kann unter der folgenden URL aufgerufen werden: