Skip to content

Lokales Setup & Installation

Die Entwicklungsumgebung von TreeQuest ist flexibel und bietet einen hybriden Ansatz. Das Backend kann vollständig in Docker ausgeführt werden oder lokal in einer Python-Umgebung (wobei nur die PostGIS-Datenbank in Docker läuft). Die Frontend-App wird lokal über Expo Go auf dem Smartphone, im Browser oder in einem Android Emulator getestet.

1. Voraussetzungen

Bitte stelle sicher, dass folgende Tools auf deinem System installiert sind:

  • Docker & Docker Compose (V2)
  • Node.js 24 LTS (mit npm 11)
  • Python 3.14 (für lokales Backend-Setup)
  • Expo Go App (auf dem mobilen Gerät) oder ein Android Emulator (z.B. über Android Studio)
  • Ein Expo Account (für EAS Cloud-Builds, siehe Abschnitt 4)

2. Backend starten

Option A: Vollständiger Docker Stack (Empfohlen für App-Entwickler)

Dies ist der einfachste Weg, um das komplette Backend (inkl. Datenbank und ML-Modell) zu starten.

# Im Projekt-Root-Verzeichnis ausführen
docker compose up -d

Beim Start wartet das Backend auf PostgreSQL, führt Alembic-Migrationen aus, füllt die Datenbank mit Testdaten und lädt beim ersten Mal das ML-Modell herunter (~350 MB).

Logs prüfen: 

docker compose logs -f backend

(Warte, bis "Application startup complete" erscheint.)

Um die Datenbank nach einem Wipe manuell neu aufzubauen: 

docker compose exec backend alembic upgrade head
docker compose exec backend python seed.py

Option B: Lokale Python API + Docker PostGIS (Für Backend-Entwickler)

Dies ermöglicht schnellere Code-Reloads und einfacheres Python-Debugging.

  1. Nur die Datenbank in Docker starten: 

    docker compose up -d db

  2. Virtuelle Python-Umgebung einrichten: 

    cd backend
python3.14 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

# PyTorch (CPU-Version für Mac/Linux/Windows kompatibel)
pip install torch==2.10.* torchvision==0.25.* --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt

  3. Umgebungsvariablen setzen: 

    export DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/treequest
export SECRET_KEY=dev-secret-key-change-in-production
export UPLOAD_DIR=./uploads
export SKIP_ML_LOAD=true # Überspringt den ML-Download für schnelleres Starten beim reinen API-Dev

  4. Migrationen anwenden und Server starten: 

    alembic upgrade head
python -c "from seed import seed_if_empty; seed_if_empty()"
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

3. Frontend starten

Die Mobile-App verbindet sich automatisch mit dem lokalen Backend.

cd frontend
npm ci
npx expo start

Testen auf einem echten Smartphone (Expo Go)

  1. Lade dir die Expo Go App aus dem App Store / Play Store herunter.
  2. Stelle sicher, dass dein Handy und Laptop im selben WLAN sind.
  3. Scanne den im Terminal angezeigten QR-Code mit der Kamera (iOS) oder direkt in der Expo Go App (Android).

Testen im Android Emulator

Wenn du lieber am Computer testest, kannst du einen Android Emulator nutzen: 1. Installiere Android Studio und richte ein Virtual Device (AVD) ein. 2. Starte den Emulator über Android Studio. 3. Drücke im laufenden npx expo start Terminalfenster die Taste a. 4. Expo installiert die Expo Go App automatisch auf dem Emulator und startet TreeQuest.

Testen im Web-Browser

Für schnelle UI-Tests ohne native Kamera/GPS-Features kannst du die App als Web-Anwendung starten: 

npm run web

Falls das Frontend das Backend nicht findet, kann die IP-Adresse in frontend/.env manuell erzwungen werden: 

EXPO_PUBLIC_API_BASE_URL=http://<DEINE-LOKALE-WLAN-IP>:8000

4. Expo Account für EAS Builds

Um die App für den produktiven Einsatz oder als eigenständige .apk / .aab (Android App Bundle) zu kompilieren, wird der Expo Application Services (EAS) Build-Service genutzt. Dafür wird kein lokales Android Studio benötigt, da der Build in der Cloud stattfindet.

Voraussetzungen für einen Build: 1. Erstelle einen kostenlosen Account auf expo.dev. 2. Logge dich im Terminal in deinen Account ein: 

npx eas login
3. Starte den Build-Prozess für Android: 
npx eas build --platform android --profile preview
(EAS lädt den Code hoch, baut das Projekt in der Cloud und gibt am Ende einen Download-Link für die fertige App zurück.)

5. Echtdaten importieren (Optional)

TreeQuest kann mit einem echten Baumkataster-Datensatz (z.B. München) gefüttert werden:

  1. Lade die GeoPackage-Datei nach backend/data/124028_baeume.gpkg.
  2. Führe das Import-Skript aus: 
    DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/treequest \
python3 backend/scripts/import_geodata.py