Willkommen im Beiboot-Repo! Dieses Repository beinhaltet ein begleitendes Projekt, welches im Modul Web Technologien des Studiengangs Medieninformatik (Master) mit Schwerpunkt Weaving the Web im Sommersemester 2022 an der Technischen Hochschule Köln entwickelt wird. Weitere Informationen können der Beiboot Beschreibung sowie den Issues des Projekts entnommen werden.
Übersicht
Team
- Autor: Melvin Weiershäuser
- Reviewer: Luca Stamos, Stefan Steinhauer
Workflow
Der für das Projekt genutzte Workflow ist hier dokumentiert.
Die folgende Anleitung führt durch das lokale Starten des Projekts und gibt dabei unterschiedliche technologische Optionen.
Um das Backend starten zu können, wird eine Environment-Datei benötigt. Die benötigte Datei muss mit ".env" benannt sein und kann über folgenden Link bezogen werden:
Backend-Environment: https://th-koeln.sciebo.de/s/54wNHInDE8zvNtZ
Der Zugriff ist geschützt und mit dem Passwort, welches im Kurs Web Technologien 2022 vereinbart wurde (siehe Zugangsdaten im Miro-Board), zulässig. Die erworbene Datei muss im Ordner "backend" hinterlegt werden.
Das Projekt nutzt einen Converter, der relevante Daten aus der vorgegebenen JSON-Datei extrahiert und diese im vorgesehenen Datenformat an das Backend übergibt. Das Backend muss dazu beim Projekt-Setup konfiguriert und der Converter einmalig ausgeführt werden. Um den Aufwand beim Projekt-Setup optional zu minimieren, kann zu Demonstrationszwecken eine vorkonfigurierte Datenbank-Datei im Backend eingepflegt werden, bevor das Projekt aufgesetzt wird. Diese kann über folgenden Link bezogen werden:
Backend-Environment: https://th-koeln.sciebo.de/s/bj3PGumo0OE97YR
Der Zugriff ist geschützt und mit dem Passwort, welches im Kurs Web Technologien 2022 vereinbart wurde (siehe Zugangsdaten im Miro-Board), zulässig. Die erworbene Datei muss im Ordner "backend/.tmp" hinterlegt werden und mit "data.db" benannt sein.
Wird die Vorkonfiguration nicht genutzt ist es erforderlich, das Projekt nach dem Aufsetzen zu konfigurieren (siehe Projekt konfigurieren)!
Das Projekt kann nun entweder in containerisierter Form via Docker oder zur lokalen Entwicklung gestartet werden.
Docker
Zum Starten mit Docker wird Docker Desktop benötigt.
Führe im Projektordner folgenden Befehl aus:
docker-compose up -dAnschließend erreichst du die Anwendung wie folgt:
Frontend: http://localhost
Backend: http://localhost:1337/admin
Sofern du keine Vorkonfiguration genutzt hast, fahre nun damit fort, das Projekt zu konfigurieren.
Entwicklung
Für die lokale Entwicklung wird eine Node.js-Installation (Version 14 oder 16) mit npm benötigt.
Beim Frontend handelt es sich um eine Angular Single Page Application (SPA), welche die Daten vom Backend bezieht und darstellt.
Führe im Ordner frontend folgende Schritte aus.
Abhängigkeiten installieren
npm installAngular-App starten
npm startÖffne nun den Browser unter http://localhost:4200.
Das Backend ist ein Strapi-Backend, welches die Daten über eine flexible Schnittstelle bereitstellt.
Führe im Ordner backend folgende Schritte aus.
Abhängigkeiten installieren
npm installStrapi starten
npm run developDie Strapi Admin-Oberfläche ist nun im Browser unter http://localhost:1337/admin erreichbar.
Das Projekt sollte nun lokal gestartet sein. Damit die Anwendung genutzt werden kann, müssen jedoch einige Konfigurationen eingerichtet und Daten transformiert werden.
Öffne im Browser die URL http://localhost:1337/admin. Lege dort einen Admin-Account an, um Strapi verwalten zu können. Anschließend öffnet sich das Dashboard.
Navigiere nun zum Punkt "Settings" und wähle unter "Users & Permissions Plugin" den Reiter "Roles" aus. Klicke dort auf die Role "Authenticated". Unter Permissions klappst du nun die Einstellungen für "Artwork" auf und setzt ein Häkchen bei "find" und "findOne". Speichere dies über den Button "Save".
Gehe nun zum "Content Manager" und wähle den Collection Type "User". Lege einen neuen User an und gib ihm die Rolle "Authenticated". Merke dir die Zugangsdaten: Mit diesen kannst du dich später in der Anwendung einloggen und auf die Meisterwerke zugreifen!
Der Converter dient dazu, relevante Daten aus der vorgegebenen JSON-Datei zu extrahieren und diese im vorgesehenen Datenformat an das Backend zu übergeben. Dadurch erleichtert er das Überführen der JSON-Datei in die Datenbank. Um den Converter nutzen zu können, wird eine Node.js-Installation mit npm benötigt. Alternativ lassen sich für das lokale Testen manuelle Einträge anlegen.
Lege zur Nutzung des Converters über die Strapi Admin-Oberfläche temporär ein API-Token an, um den Converter in Strapi zu authentisieren. Wähle dazu in den Einstellungen unter "Global Settings" den Reiter "API Tokens" und lege ein neues Token (Name egal) an, welches den Token type "Full access" erhält. Speichere und lege dir das resultierte Token sicher ab. Du wirst es noch brauchen!
Führe nun im Ordner converter folgende Schritte aus.
Abhängigkeiten installieren
npm installQuelle einfügen
Beschaffe die vorgegebene JSON-Datei und füge sie in diesem Ordner ein. Die Datei muss mit "cda-paintings-2022-04-22.de" benannt sein. Sie sollte bei der Versionierung von Git ignoriert werden.
Environment konfigurieren
Lege eine Datei ".env" an und setze die API-URL des Ziel-Backends (z. B. "http://localhost:1337") sowie das zuvor erzeugte API-Token. Auch diese Datei sollte bei der Versionierung von Git ignoriert werden. Die Datei sollte wie folgt aussehen:
BASE_URL="http://localhost:1337"
API_TOKEN="<token>"
Converter ausführen
Stelle sicher, dass das Backend vorher gestartet und die Environment richtig konfiguriert ist. Der Converter konvertiert dann die Daten und legt sie als Einträge im Backend an.
npm startAPI-Token löschen
Da der Converter einmalig ausgeführt werden muss, wird das API-Token nun nicht mehr benötigt. Aus Sicherheitsgründen empfiehlt es sich daher, dieses nun in den Strapi-Einstellungen wieder zu entfernen.
Das Deployment erfolgt mit Docker über den Docker Hub, indem die Images der Anwendungen in folgende Repositories hochgeladen werden:
- Frontend: https://hub.docker.com/repository/docker/mweiershaeuser/beiboot-frontend
- Strapi: https://hub.docker.com/repository/docker/mweiershaeuser/beiboot-backend
Die Images werden anschließend mit Docker Compose aus dem Docker Hub geladen und gestartet, sodass sie unter den folgenden Adressen erreichbar sind:
- Frontend: https://beiboot.melvinweiershaeuser.de
- Strapi: https://beiboot-backend.melvinweiershaeuser.de
Das Frontend kann alternativ auch über GitHub Pages bereitgestellt werden:
Alternatives Frontend-Deployment via GitHub Pages
Erreichbar unter: https://mi-classroom.github.io/mi-web-technologien-beiboot-ss2022-mweiershaeuser
Es wird der Ordner docs des Branches gh-pages genutzt.
Führe folgende Schritte im Ordner frontend für ein Deployment durch:
npm run build:gh-pagesCommitte und pushe anschließend den generierten docs Ordner auf dem gh-pages Branch.
Für den Deployment-Prozess mit Docker sind folgende Schritte durchzuführen:
Führe jeweils die folgenden Befehle aus:
Frontend
cd frontend
docker build -f frontend.Dockerfile -t mweiershaeuser/beiboot-frontend .Backend
Bevor ein Image des Backends gebaut wird, muss die Datei ".dockerignore" im Ordner "backend" ausgetauscht werden. Entferne dazu vorübergehend die vorhandene Datei und benenne die Datei "production.dockerignore" in ".dockerignore" um. Denke daran, dies nach dem Build wieder rückgängig zu machen!
cd backend
docker build -f backend.Dockerfile -t mweiershaeuser/beiboot-backend .Für diesen Schritt benötigst du Berechtigungen für das Repository und musst mit dem berechtigten Account bei deiner lokalen Docker-Instanz eingeloggt sein.
Frontend
cd frontend
docker push mweiershaeuser/beiboot-frontendStrapi
cd backend
docker push mweiershaeuser/beiboot-backendWurden die Images im Repository hochgeladen, kannst du die Anwendungen auf einem Server starten. Kopiere dazu die Datei docker-compose.production.yaml in das Arbeitsverzeichnis auf deinem Server, lege außerdem falls noch nicht vorhanden die Ordner "db" und "assets/uploads" an und führe dort folgenden Befehl aus:
docker compose -f docker-compose.production.yaml up -dAnschließend sollten die Docker-Container starten und auf folgenden Ports erreichbar sein:
- Frontend: 8060
- Backend: 8061
Der Server kann nun entsprechend der individuellen Gegebenheiten konfiguriert werden, um die auf den Ports laufenden Anwendungen in der Regel mit einem Web-Server über Domain und TLS-Verschlüsselung erreichbar zu machen.
Anschließend wird/wurde Strapi analog zur Anleitung für das lokale Setup konfiguriert.
Die wichtigsten Entscheidungen des Projekts wurden in Form von Architectural Decision Records (ADRs) festgehalten und sind hier zu finden.
Zum Modul Web Technologien gibt es ein begleitendes Projekt. Im Rahmen dieses Projekts werden wir von Veranstaltung zu Veranstaltung ein Projekt sukzessive weiter entwickeln und uns im Rahmen der Veranstaltung den Fortschritt anschauen, Code Reviews machen und Entwicklungsschritte vorstellen und diskutieren.
Als organisatorischen Rahmen für das Projekt nutzen wir GitHub Classroom. Inhaltlich befassen wir uns mit der Entwicklung einer kleinen Web-Anwendung für die Bearbeitung von Bildern. Hierbei steht weniger ein professioneller Konzeptions-, Entwurfs- und Entwicklungsprozess im Vordergrund, sondern vielmehr die sukzessive Weiterentwicklung einer Anwendung, das Ausprobieren, Vergleichen, Refactoren und die Freude an lauffähigem Code.