Ferienpass

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.

Historie

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

Nutzung

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): veranstaltung-anlegen

Übersicht über alle Veranstaltungen im Verwaltungsbereich (Beispieldaten): veranstaltungen-uebersicht

Login

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

Bestätigungsmails

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.

Contribute

Aufbau

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.

Prerequisites

Java
npm (optional, für lokale Frontend-Entwicklung)

MacOS

> brew cask install java
> brew install npm

Windows

> choco install jdk
> choco install npm

Linux

> apt-get install jdk
> apt-get install npm

Local Setup

Wir 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.

build project

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 install

run project

Backend-Server starten

> .mvnw --projects backend spring-boot:run

Dieser 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/

local frontend development

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.

Continuous Integration and Deployment

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.

Dev-Workflow

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

Feature ready? --> Pull Request!

Wenn dein Feature fertig ist:

Pull Request auf GitHub erstellen

create-pull-request

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 https://github.com/digital-bauhaus/Ferienpass/issues/175).

Heroku erstellt nun automatisch eine Review-App für diesen Pull-Request (Access für die Pipeline bitte bei jonashackt anfragen):

heroku-pipeline

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:

heroku-review-app-link

PR prüfen

Auf GitHub werden alle Commits, die Builds sowie die Heroku-Deployments vollständig im Pull Request dargestellt:

github-pr

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.

Staging / Production

Die pre-produktive / produktive Anwendung kann unter der folgenden URL aufgerufen werden:

https://ferienpass.herokuapp.com/#/

digital-bauhaus / Ferienpass

readme