Hallo
Ich habe auf meinem Rechner nun ein OBS-Portal installiert. Dabei geholfen hat mir ChatGPT. Die Antworten der KI habe ich teilweise angepasst sowie ergänzt und dann zu dieser Anleitung zusammengeführt, die ich hier gerne teile.
Schritt 1: Voraussetzungen installieren (Docker & Co.)
Zuerst installieren wir die Docker auf deinem Mac:
-
Docker Desktop: Das OpenBikeSensor-Portal läuft am einfachsten in Docker-Containern. Installiere Docker Desktop für Mac. Dies beinhaltet die Docker Engine und Docker Compose.
Lade Docker Desktop für macOS von der offiziellen Docker-Website herunter und installiere es. -
Öffne nach der Installation die Docker.app (im Programme-Ordner) und warte, bis Docker vollständig gestartet ist (das Docker-Symbol in der Menüleiste sollte angezeigt werden). Eventuell verlangt Docker beim ersten Start nach Administratorrechten – erlaube dies.
Überprüfung:
Terminal
docker --version
und
docker-compose --version
um zu prüfen, ob Docker korrekt installiert ist. Beide Befehle sollten Versionsnummern ausgeben, anstatt einen Fehler anzuzeigen. Falls docker-compose nicht gefunden wird, probiere docker compose version (Docker Compose ist bei neueren Docker-Versionen als Unterbefehl integriert).
Nun benötigt es Git:
Zum Herunterladen des Portal-Quellcodes benötigen wir Git. Prüfe im Terminal mit dem Befehl
git --version
ob Git installiert ist. Auf macOS kann beim ersten Aufruf von git ein Dialog erscheinen, der anbietet, die Xcode Command Line Tools zu installieren – stimme zu, falls dies erscheint.
Alternativ kannst du Git über Homebrew installieren:
brew install git
Nachdem Docker und Git verfügbar sind, können wir fortfahren.
Schritt 2: OpenBikeSensor-Portal Quellcode herunterladen
Als Nächstes laden wir den Quellcode des OpenBikeSensor-Portals von GitHub herunter. Öffne ein Terminal und wechsel in ein Verzeichnis, in dem du das Portal speichern möchest (z.B. den Desktop oder Ihren Projekte-Ordner):
cd Desktop
Lade das Projekt mit Git herunter
git clone https://github.com/openbikesensor/portal.git
Dieser Befehl erstellt einen Ordner portal mit den Projektdateien. Wechsele danach in dieses Verzeichnis:
cd portal
Schritt 3: Keycloak (Benutzerverwaltung) konfigurieren
Das OpenBikeSensor-Portal nutzt Keycloak als Authentifizierungs- und Benutzerverwaltungssystem. Keycloak läuft ebenfalls in einem Docker-Container. Bevor wir das Portal starten können, müssen wir Keycloak einrichten, damit sich später Nutzer anmelden können.
3.1 Keycloak-Container starten: Stelle sicher, dass Docker Desktop läuft. Führe via Terminal im Projektordner portal folgenden Befehl aus, um den Keycloak-Server im Hintergrund zu starten:
docker-compose up -d keycloak
Ich musst eine Anpassung in der docker-compose.yaml machen, da ich diese Fehlermeldung erhalten habe:
portal % docker-compose up -d keycloak
WARN[0000] /Users/XXXXX/portal/docker-compose.yaml: the attribute versionis obsolete, it will be ignored, please remove it to avoid potential confusion [+] Running 1/1 ✘ keycloak Error pull access denied for jboss/keycloak… 1.0s Error response from daemon: pull access denied for jboss/keycloak, repository does not exist or may require 'docker login’
Lösung: In der Datei docker-compose.yaml
image: jboss/keycloak
ersetzen mit
Dieser Befehl lädt (falls nötig) das Keycloak-Image herunter und startet den Container. Keycloak wird im Entwicklungs-Setup auf Port 3003 laufen. Warte einige Momente, damit Keycloak vollständig hochfährt
3.2 Keycloak-Admin-Konsole öffnen:
Öffne in einem Browser die URL http://localhost:3003/. Du solltest die Keycloak-Oberfläche sehen. Klicke auf „Administration Console“. Melde dich mit dem Standard-Admin-Konto an: Benutzername admin und Passwort admin
3.3 Realm für das Portal erstellen:
In Keycloak ist ein Realm eine Umgebung/ein Kontext für Benutzer und Clients. Bewege den Mauszeiger in der Admin-Konsole oben links auf den aktuellen Realm-Namen (standardmäßig „Master“). Klicke dann auf „Add realm“ (Realm hinzufügen). Vergib den Namen obs-dev für den neuen Realm exakt so (Groß-/Kleinschreibung beachten) und klicke auf Erstellen.
**3.4 Client für das Portal einrichten: **
Im neuen Realm obs-dev müssen wir einen Client für das Portal hinzufügen – dieser repräsentiert die Portal-Anwendung in Keycloak. Navigiere in der linken Seitenleiste zu „Configure → Clients“ und klicke rechts oben auf „Create“ (Erstellen). Trage als Client ID den Wert portal ein und klicke auf Save.
Nach dem Speichern siehst du die Einstellungen für den neuen Client. Im Reiter Settings ändere „Access Type“ auf confidential. Weiter unten findest du die Einstellung „Valid Redirect URIs“ – trage dort http://localhost:3000/login/redirect ein und klicke erneut auf Save. (Diese Redirect-URI ist wichtig, damit die Rückleitung nach dem Login korrekt funktioniert (Port 3000 gehört zur API-Komponente des Portals)).
3.5 Keycloak-Client-Secret kopieren und konfigurieren:
Wechsele beim Client portal zum Reiter „Credentials“. Hier siehst du ein Feld „Secret“ mit einem automatisch generierten Wert (eine lange zufällige Zeichenkette). Kopiere diesen Secret-Key in die Zwischenablage oder in eine Textdatei.
Öffne nun auf dem Mac die Datei portal/api/config.overrides.py in einem Texteditor (oder mit der App Brackets). Falls diese Datei noch nicht existiert (Standard), erstellen eine neue leere Datei mit diesem Namen im Ordner api. Füge dort folgende Zeile ein:
KEYCLOAK_CLIENT_SECRET = "kopierter Secret-Key“
Ersetze durch den in Keycloak kopierten Secret-Wert und speichere die Datei. Achte darauf, die Anführungszeichen um den Secret-Wert mit einzuschliessen. (Dieser Schritt hinterlegt das geheime Passwort, mit dem das Portal sich bei Keycloak authentifiziert.)
3.6 Standard-Benutzer anlegen:
Damit du dich m Portal anmelden kannst, legen wir nun in Keycloak einen Benutzer an. Klicke in der Keycloak-Admin-Konsole links auf „Manage → Users“ und dann rechts oben auf „Add user“. Vergib einen Benutzernamen, z.B. test, und trage eine E-Mail-Adresse ein und klicke auf Save. Anschließend wechsele zum Reiter „Credentials“ für den neuen Benutzer. Trage ein Passwort deiner Wahl ein (zweimal) und deaktiviere die Option „Temporary“, damit das Passwort permanent gilt. Klicke auf „Set Password“ zum Bestätigen.
(Du hast nun einen Benutzer (z.B. test) mit Passwort in Keycloak angelegt, der sich später im Portal anmelden kann.)
Zusammenfassung Keycloak: Wir haben Keycloak nun so konfiguriert, dass das Portal (Client portal im Realm obs-dev) Keycloak zur Authentifizierung nutzen kann. Der Client-Secret wurde im Portal hinterlegt, und ein Test-Benutzer wurde erstellt. Diese Keycloak-Einrichtung ist in der Regel nur einmal nötig. Die Einstellungen werden in der angebundenen Datenbank gespeichert, sodass sie auch nach einem Neustart der Container erhalten bleiben.
Schritt 4: PostgreSQL-Datenbank initialisieren
Das OpenBikeSensor-Portal speichert seine Daten in einer Datenbank (PostgreSQL-Datenbank mit PostGIS-Erweiterung (für Geodaten). Ein passender PostgreSQL-Container ist in der Docker-Compose-Datei definiert.)
Wir starten nun die Datenbank und richten das Schema ein:
4.1 Datenbank-Container starten: Führe im Projektordner (falls du diesen verlassen hast wechsele wieder rein mit
cd ~/XYZ/portal
und führe folgenden Befehl aus:
docker-compose up -d postgres
Dieser Befehl startet den PostgreSQL-Datenbankcontainer im Hintergrund. Warte einige Zeit (ca. 1-2 Minuten beim ersten Start), damit die Datenbank initialisiert wird.
4.2 Datenbankschema einrichten:
Jetzt importieren wir das Datenbankschema (Tabellen, Indizes usw.), das vom Portal benötigt wird. Führe im Terminal folgenden Befehl aus:
docker-compose run --rm api tools/upgrade.py
Dieser Befehl startet temporär den API-Service-Container und führt darin das Python-Skript tools/upgrade.py aus. Das Skript legt das komplette Schema der Datenbank an (es führt alle benötigten Migrationen aus und erstellt Funktionen für die Kartenkacheln). Nach erfolgreicher Ausführung siehst du keine Fehlermeldung und der Container beendet sich von selbst.
(Hinweis: Standardmäßig verwendet das Portal folgende Verbindungsdaten für die DB: Datenbankname obs, Benutzer obs, Passwort obs)
Schritt 5: OpenStreetMap-Daten importieren
Das OpenBikeSensor-Portal benötigt Strassen- und Geodaten aus OpenStreetMap (OSM), um hochgeladene Tracks auszuwerten und Karten anzuzeigen. Diese Daten müssen einmalig in die lokale Datenbank importiert werden. Im Entwicklungsbetrieb empfiehlt es sich, nur einen begrenzten Ausschnitt (z.B. Ihre Stadt oder Region) zu importieren, um die Datenmenge klein zu halten. Für produktive Installationen würde man einen größeren Datensatz (z.B. ganzes Bundesland oder Land) importieren.Wir durchlaufen nun den Importprozess für OSM-Daten. Er besteht aus drei Schritten
OSM-Datei (.osm.pbf) herunterladen (OSM-Daten werden als PBF-Dateien zur Verfügung gestellt.) Eine gute Quelle für regionale Extrakte ist Geofabrik (https://download.geofabrik.de/) Suche dort dein Land und deine Region heraus. Lade die entsprechende .osm.pbf-Datei herunter. Beispiel: Um Daten für das Bundesland Baden-Württemberg (Deutschland) zu laden:
wget -P local/pbf/ https://download.geofabrik.de/europe/germany/baden-wuerttemberg-latest.osm.pbf
Dieser Befehl lädt die Datei in den Ordner local/pbf/ innerhalb des Projektverzeichses.
Daten transformieren: Die rohen OSM-Daten müssen in ein internes Format umgewandelt werden. Dabei werden nur die benötigten Objekte (Straßen, Regionen etc.) extrahiert und geometrische Informationen vorbereitet, um später darauf zugreifen zu können . Diese Transformation erzeugt eine .msgpack-Datei, die dann importiert wird.
Führe dafür folgendes Kommando aus:
docker-compose run --rm api tools/transform_osm.py /pbf/baden-wuerttemberg-latest.osm.pbf /obsdata/baden-wuerttemberg-latest.msgpack
Ersetze den Dateinamen entsprechend. (Der erste Pfad /pbf/… verweist auf die heruntergeladene PBF-Datei im Container (dies entspricht local/pbf/ auf deinem Rechner), der zweite Pfad /obsdata/… gibt den Ausgabeort für die konvertierten Daten an (dies entspricht dem Ordner local/obsdata/)).
In unserem Beispiel wird die Datei baden-wuerttemberg-latest.msgpack im Ordner local/obsdata/ erzeugt. Dieser Schritt kann je nach Gebiet einige Sekunden bis Minuten dauern.
Daten in die Datenbank importieren:
Importiere nun die konvertierten Daten in die PostgreSQL-Datenbank:
docker-compose run --rm api tools/import_osm.py /obsdata/baden-wuerttemberg-latest.msgpack
Benutze auch hier den entspreche den Dateinamen. Dieses Kommando lädt die .msgpack-Datei und schreibt die enthaltenen Straßen- und Gebietsdaten in die Datenbank.
Nach diesen Schritten enthält die lokale PostgreSQL-Datenbank die benötigten OSM-Rohdaten zu Straßen und Gebieten für das Portal. Dies ermöglicht dem Portal z.B., hochgeladene Tracks Straßensegmenten zuzuordnen und Entfernungen zu Berechnen, ohne jedes Mal externe OSM-Dienste abfragen zu müssen.
Schritt 6: Portal starten (Backend, Frontend und Worker)
Jetzt sind alle Dienste konfiguriert und vorbereitet. Wir können das Portal selbst starten, (das aus drei Hauptkomponenten besteht: der API (Backend-Server), dem Frontend (Web-Oberfläche) und einem Hintergrund-Worker zur Verarbeitung von Track-Daten.)
Diese drei Komponenten werden ebenfalls durch Docker-Container repräsentiert.
Starte die Container mit folgendem Befehl (im Projektordner):
docker-compose up -d --build api worker frontend
(Dieser Befehl baut zunächst die Docker-Images für das API-Backend und das React-Frontend aus dem heruntergeladenen Quellcode (dies kann beim ersten Mal einige Minuten dauern, da z.B. Abhängigkeiten installiert werden)). Anschließend werden alle drei Container im Hintergrund gestartet. (Die Option --build stellt sicher, dass bei Änderungen im Code oder beim ersten Start alle Images neu gebaut werden.)
Hinweis: Bei künftigen Starts kannst du–build weglassen (sofern sich am Code nichts geändert hat, um den Start zu beschleunigen. )
Nach
docker-compose up -d
sollten nun alle notwendigen Container laufen. Du kannst mit
docker-compose ps
überprüfen, ob api, frontend, worker, postgres und keycloak im Status „Up“ sind.
Die wichtigen Ports sind
- Frontend: Port 3001
- Keycloak: Port 3003
Schritt 7: Portal im Browser aufrufen und Nutzung
Wenn alle Container laufen, kannst du das Portal nun verwenden:
Öffne einen Webbrowser und rufe http://localhost:3001/ auf. Du solltest die Startseite des OpenBikeSensor-Portals sehen.
Klicken auf „Login“. Melde dich ich dort mit dem in Schritt 3.6 erstellten Benutzer an (z.B. Benutzername test und dem festgelegten Passwort) an.
Beenden und Neustart
Mit diesem Befehl wird das Portal beendet:
docker-compose down
Neustart:
Docker.app starten und im Terminal diesen Befehl eingeben
docker-compose up -d
Die Daten, die du ins Portal lädts, sind nur auf deinem Rechner und nicht öffentlich zugänglich. Die Daten bleiben erhalten solange diese nichts auf dem entsprechenden Ordner im Ordner Portal gelöscht werden.