managarten/apps/uload/docs/features/pocketbase/POCKETBASE-DEV-SETUP-PLAN.md

PocketBase Development Setup - Implementierungsplan

🎯 Ziel

Vollständige Trennung von Development und Production Datenbanken, ähnlich wie bei Redis.

📋 Aktuelle Situation

Probleme:

• ❌ Beide Umgebungen nutzen Production DB (https://pb.ulo.ad)
• ❌ Gefahr von Testdaten in Production
• ❌ Keine lokale Entwicklungsumgebung
• ❌ Hardcoded Production URLs im Code
• ❌ Inkonsistente Environment-Variable-Nutzung

Vorhandene Ressourcen:

• ✅ PocketBase Binary bereits in backend/ vorhanden
• ✅ npm run backend Script existiert
• ✅ Lokale DB-Dateien in backend/pb_data/
• ✅ Schema-Migrations in backend/pb_migrations/

🛠 Implementierungsplan

Phase 1: Lokale PocketBase einrichten (15 Min)

1. PocketBase starten

   cd backend
   ./pocketbase serve
   

   • Läuft auf http://localhost:8090
   • Admin UI: http://localhost:8090/_/

2. Admin Account erstellen

   • Beim ersten Start wird Admin-Account angelegt
   • Credentials sicher speichern

3. Schema von Production kopieren

   # Export von Production (manuell über Admin UI)
   # Import in lokale Instanz
   

Phase 2: Environment Variables korrigieren (10 Min)

1. .env.development anpassen

   # PocketBase Configuration (Local Development)
   PUBLIC_POCKETBASE_URL=http://localhost:8090
   POCKETBASE_URL=http://localhost:8090
   
   # PocketBase Admin (for local development)
   POCKETBASE_ADMIN_EMAIL=admin@localhost
   POCKETBASE_ADMIN_PASSWORD=localdevpassword123
   

2. .env.production erstellen

   # PocketBase Configuration (Production)
   PUBLIC_POCKETBASE_URL=https://pb.ulo.ad
   POCKETBASE_URL=https://pb.ulo.ad
   

Phase 3: Code-Anpassungen (20 Min)

1. src/lib/pocketbase.ts

   import { dev } from '$app/environment';
   
   // Automatic environment detection
   const POCKETBASE_URL =
   	import.meta.env.PUBLIC_POCKETBASE_URL || (dev ? 'http://localhost:8090' : 'https://pb.ulo.ad');
   

2. Hardcoded URLs entfernen

   • src/routes/p/[username]/+page.server.ts:16
   • src/lib/scripts/update-links-collection.js:6
   • src/routes/api/verify/+server.ts:15

3. CSP Headers anpassen

   • src/hooks.server.ts - Dynamische CSP basierend auf Environment

Phase 4: Daten-Migration (30 Min)

1. Test-Daten erstellen

   # Script für Sample-Daten
   npm run seed:dev
   

2. Production Snapshot (optional)

   • Export wichtiger Test-Links
   • Anonymisierte User-Daten
   • Keine echten Produktionsdaten!

3. Migrations synchronisieren

   # Alle Migrations lokal ausführen
   cd backend
   ./pocketbase migrate up
   

Phase 5: Development Workflow (10 Min)

1. Start-Scripts optimieren

   {
   	"scripts": {
   		"dev": "npm run dev:frontend",
   		"dev:frontend": "vite dev",
   		"dev:backend": "cd backend && ./pocketbase serve",
   		"dev:all": "concurrently \"npm:dev:backend\" \"npm:dev:frontend\"",
   		"dev:setup": "npm run dev:backend:setup && npm run dev:seed"
   	}
   }
   

2. Docker Alternative (optional)

   # docker-compose.dev.yml
   services:
     pocketbase:
       image: ghcr.io/pocketbase/pocketbase:latest
       ports:
         - '8090:8090'
       volumes:
         - ./backend/pb_data:/pb_data
   

Phase 6: Testing & Validation (15 Min)

1. Connection Tests

   • Verify localhost:8090 responds
   • Check Admin UI access
   • Test API endpoints

2. Feature Tests

   • Create link
   • Register user
   • Authentication flow
   • Stripe webhooks (mit lokaler URL)

3. Data Isolation

   • Verify no production data access
   • Check environment variables
   • Test fallback mechanisms

🚀 Quick Start (Nach Implementierung)

# 1. Backend starten
npm run dev:backend

# 2. In neuem Terminal: Frontend starten
npm run dev:frontend

# Oder alles zusammen:
npm run dev:all

⚠️ Wichtige Überlegungen

Daten-Synchronisation

• NICHT Production-Daten lokal spiegeln
• Nur Schema/Structure synchronisieren
• Test-Daten separat verwalten

Secrets Management

• Lokale Admin-Credentials nur für Dev
• Keine Production-Secrets in .env.development
• Stripe Test-Keys für lokale Entwicklung

Backup Strategy

• Lokale DB regelmäßig committen? (ohne sensible Daten)
• Schema-Änderungen als Migrations tracken
• Production Backups separat

📊 Vergleich: Vorher vs Nachher

Aspekt	Vorher	Nachher
Dev Database	Production (pb.ulo.ad)	Lokal (localhost:8090)
Test-Daten	In Production!	Isoliert lokal
Performance	Netzwerk-Latenz	Instant (lokal)
Sicherheit	Risiko für Prod-Daten	Vollständig getrennt
Offline-Arbeit	Nicht möglich	Voll funktionsfähig

🔄 Migration Checkliste

• Lokale PocketBase starten
• Admin Account erstellen
• Schema importieren
• Environment Variables anpassen
• Code von hardcoded URLs befreien
• Test-Daten erstellen
• Alle Features lokal testen
• Team-Dokumentation aktualisieren
• CI/CD Pipeline anpassen

🎉 Vorteile nach Implementierung

1. Sicherer - Keine Produktionsdaten-Gefährdung
2. Schneller - Lokale DB ohne Netzwerk-Latenz
3. Flexibler - Experimente ohne Konsequenzen
4. Offline-fähig - Arbeiten ohne Internet
5. Team-freundlich - Jeder hat eigene DB

📚 Nächste Schritte

1. Entscheidung treffen: Sofort umsetzen oder planen?
2. Team informieren über Änderungen
3. Migration durchführen
4. Dokumentation für Team erstellen
5. CI/CD anpassen für neue Struktur