managarten/apps/uload/docs/features/pocketbase/pocketbase-local-setup.md

PocketBase Local Development Setup

✅ Was wurde implementiert

1. Environment Separation

• Development: http://localhost:8090 (lokal)
• Production: https://pb.ulo.ad (Coolify)
• Automatische Umgebungserkennung basierend auf dev Flag

2. Code-Änderungen

• ✅ .env.development - Lokale PocketBase URL
• ✅ .env.production - Production PocketBase URL
• ✅ src/lib/pocketbase.ts - Dynamische URL-Auswahl
• ✅ src/routes/p/[username]/+page.server.ts - Environment-basierte URL
• ✅ src/lib/scripts/update-links-collection.js - Flexible URL
• ✅ src/routes/api/verify/+server.ts - Dynamische Redirect URL
• ✅ src/hooks.server.ts - CSP Headers für beide Umgebungen

3. Sicherheit

• Keine hardcoded Production URLs mehr
• Vollständige Trennung von Dev/Prod Daten
• Lokale Entwicklung ohne Internetverbindung möglich

🚀 Quick Start

1. PocketBase starten

# Terminal 1: Backend
cd backend
./pocketbase serve

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

2. Admin Account erstellen

1. Öffne http://localhost:8090/_/
2. Erstelle Admin Account (nur beim ersten Mal)
3. Merke dir die Credentials

3. Schema importieren

Option A: Manuell über UI

1. Login als Admin
2. Settings → Import/Export
3. Load from JSON → backend/pb_schema.json
4. Review → Confirm

Option B: Automatisch (wenn Collections existieren)

# Schema ist bereits in backend/pb_migrations/
cd backend
./pocketbase migrate up

4. Test-Daten erstellen

# Seed Script ausführen
node scripts/seed-local-db.js

Erstellt:

• 2 Test-User (test@localhost, demo@localhost)
• 4 Test-Links (normal, protected, expired, limited)
• Sample Click-Daten

5. App starten

# Terminal 2: Frontend
npm run dev

# Oder alles zusammen:
npm run dev:all

📝 Test-Credentials

Users

Email: test@localhost
Password: test123456

Email: demo@localhost
Password: demo123456

Links

• http://localhost:5173/test1 - Normaler Link
• http://localhost:5173/test2 - Mit Click-Limit (100)
• http://localhost:5173/protected - Password: secret123
• http://localhost:5173/expired - Abgelaufener Link

Admin

URL: http://localhost:8090/_/
Email: [deine Admin Email]
Password: [dein Admin Password]

🔍 Verification

1. Environment Check

# In Browser Console sollte stehen:
🔧 PocketBase URL: http://localhost:8090
🔧 Environment: development
🔧 Dev mode: true

2. API Health

curl http://localhost:5173/health
# sollte zeigen: "pocketbase": "running"

3. Feature Tests

• User Registration
• Login/Logout
• Link erstellen
• Link redirect
• Password-geschützte Links
• Click-Tracking

🛠 Troubleshooting

PocketBase startet nicht

# Port bereits belegt?
lsof -i :8090

# Process beenden
kill -9 [PID]

# Neu starten
cd backend && ./pocketbase serve

"Collection not found" Fehler

1. Schema importieren (siehe oben)
2. Oder Collections manuell erstellen:
   • users (auth)
   • links
   • clicks
   • accounts

Environment Variables nicht geladen

# .env.development muss existieren
cat .env.development

# Sollte enthalten:
PUBLIC_POCKETBASE_URL=http://localhost:8090

CORS Fehler

PocketBase erlaubt standardmäßig alle Origins in Development. Falls Probleme: Admin UI → Settings → API Rules

📊 Development vs Production

Aspekt	Development	Production
PocketBase URL	http://localhost:8090	https://pb.ulo.ad
Datenbank	Lokal (SQLite)	Cloud (Coolify)
Auth	Test-Accounts	Echte User
Stripe	Test-Keys	Live-Keys
Redis	localhost:6379	Coolify Redis
SSL	Nein (HTTP)	Ja (HTTPS)
CSP	Relaxed	Strict

🔄 Daten-Synchronisation

Schema Updates von Production holen

# 1. Export aus Production (Admin UI)
# 2. Speichern als backend/pb_schema.json
# 3. Lokal importieren

Migrations erstellen

cd backend
./pocketbase migrate create "add_new_field"
# Edit migration file
./pocketbase migrate up

🎯 Best Practices

1. Niemals Production-Daten lokal speichern
2. Separate Test-Accounts verwenden
3. Schema-Änderungen als Migrations tracken
4. Regelmäßig lokale DB zurücksetzen

# Lokale DB reset
rm backend/pb_data/*.db
cd backend && ./pocketbase serve
# Schema neu importieren

🚢 Deployment

Beim Deployment nach Production:

1. Environment wird automatisch erkannt
2. Production URLs werden verwendet
3. Keine Code-Änderungen nötig!

# Build für Production
npm run build

# Preview Production Build lokal
npm run preview
# Nutzt automatisch Production-Config!

📚 Weitere Ressourcen

• PocketBase Docs
• Admin UI Guide
• API Rules
• Migrations