Lokale Entwicklung — From Scratch

Vollständige Anleitung zur Einrichtung der lokalen Entwicklungsumgebung.

Schnellstart mit Dev-Script

# Alle Services auf einmal starten (Windows Terminal mit Tabs)
.\dev-start.ps1

# Nur Backend + Frontend (ohne Docs und Horizon)
.\dev-start.ps1 -NoDocs -NoHorizon

Das Script prüft Voraussetzungen, legt .env automatisch an falls fehlend, und öffnet alle Services in separaten Windows Terminal Tabs.

Voraussetzungen

Tool	Mindestversion	Prüfen
PHP	8.2	php --version
Composer	2.x	composer --version
Node.js	20	node --version
npm	10	npm --version
Git	beliebig	git --version
MySQL	8.0	lokal oder via Docker
Redis	7	lokal oder via Docker

Docker Alternative

Statt MySQL und Redis lokal zu installieren, kann docker-compose up -d db redis mailpit genutzt werden um alle Infrastruktur-Services zu starten. Voraussetzung: Docker Desktop installiert.

---

Schritt 1 — Repository klonen

git clone https://github.com/marcelstingl/venturo.git
cd venturo

---

Schritt 2 — Backend einrichten

cd backend

# 1. PHP-Abhängigkeiten installieren
composer install --ignore-platform-reqs

# 2. Umgebungsvariablen kopieren
cp .env.example .env

# 3. .env anpassen (DB-Zugangsdaten, API-Keys)
# Öffne .env und passe mindestens an:
#   DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD
#   REDIS_HOST
#   ANTHROPIC_API_KEY (für KI-Agenten)

# 4. Application Key generieren
php artisan key:generate

# 5. Datenbank migrieren
php artisan migrate

# 6. Datenbank befüllen (Starter-Daten)
php artisan db:seed

# 7. Storage-Link anlegen
php artisan storage:link

# 8. Backend starten
php artisan serve --port=8080

Backend läuft unter: http://localhost:8080

---

Schritt 3 — Frontend einrichten

# Neues Terminal öffnen
cd frontend

# 1. Node-Abhängigkeiten installieren
npm install

# 2. Umgebungsvariablen kopieren
cp .env.local.example .env.local

# 3. Frontend starten (Vite Dev-Server mit HMR)
npm run dev

Frontend läuft unter: http://localhost:5173

---

Schritt 4 — Docs einrichten (optional)

# Neues Terminal öffnen
cd docs

npm install
npm run docs:dev

Docs laufen unter: http://localhost:5174

---

Infrastruktur via Docker (optional)

Wenn MySQL und Redis lokal nicht installiert sind:

# Vom Root-Verzeichnis (venturo/)
docker compose up -d db redis mailpit

# Status prüfen
docker compose ps

Service	URL
MySQL	localhost:3306
Redis	localhost:6379
Mailpit (SMTP)	localhost:1025
Mailpit (Web-UI)	http://localhost:8025

---

Verfügbare Services (lokal)

Service	URL	Beschreibung
Frontend	http://localhost:5173	Vue.js Dev-Server (HMR)
Backend API	http://localhost:8080/api/v1	Laravel API
Mailpit	http://localhost:8025	E-Mail-Catcher (kein echtes Versenden)
Horizon	http://localhost:8080/horizon	Queue-Dashboard
MySQL	localhost:3306	Datenbank
Redis	localhost:6379	Cache + Queue

---

Nützliche Befehle

# Backend (im backend/ Verzeichnis)
php artisan migrate:fresh --seed   # DB komplett neu aufsetzen
php artisan queue:work             # Queue-Worker starten
php artisan horizon                # Horizon starten (mit Dashboard)
php artisan tinker                 # REPL für Laravel
php artisan route:list             # Alle Routen anzeigen
php artisan test                   # Tests ausführen

# Frontend (im frontend/ Verzeichnis)
npm run build                      # Produktions-Build
npm run preview                    # Build lokal vorschauen

# Docs (im docs/ Verzeichnis)
npm run docs:build                 # Statischen Build erstellen
npm run docs:preview               # Build lokal vorschauen

# Docker (im Root-Verzeichnis)
docker compose up -d               # Alle Services starten
docker compose down                # Alle Services stoppen
docker compose down -v             # Inkl. Datenbankdaten löschen
docker compose logs -f backend     # Backend-Logs live

---

Häufige Probleme

php artisan migrate schlägt fehl → MySQL läuft nicht. Starte docker compose up -d db oder den lokalen MySQL-Dienst.

SQLSTATE[HY000] [2002] Connection refused → DB_HOST in .env auf 127.0.0.1 statt localhost setzen.

Horizon startet nicht → Redis läuft nicht. Starte docker compose up -d redis.

composer install schlägt wegen ext-pcntl fehl → Auf Windows normal. Nutze composer install --ignore-platform-reqs.

Frontend zeigt Network Error bei API-Calls → Backend läuft nicht auf Port 8080. php artisan serve --port=8080 ausführen.