managarten/apps-archived/uload/docs/DEPLOYMENT_GUIDE.md

Deployment Guide für uLoad

🏗️ Architektur-Übersicht

Das Projekt verwendet eine Container-basierte Architektur mit:

• Frontend: SvelteKit Application
• Backend: PocketBase (eingebettete SQLite-Datenbank)
• Deployment: Docker + Coolify auf Hetzner VPS

🔄 Deployment-Strategie

1. Entwicklung (Local)

# Lokale PocketBase starten
cd backend && ./pocketbase serve

# Frontend starten
npm run dev

# Beides zusammen
npm run dev:all

2. Staging/Test

# Mit docker-compose testen
docker-compose up --build

3. Produktion (Coolify)

Setup in Coolify:

1. Neue Resource erstellen:

   • Type: Docker Compose
   • Source: GitHub Repository
   • Branch: main
   • Docker Compose File: docker-compose.prod.yml

2. Environment Variables setzen:

ORIGIN=https://ulo.ad
POCKETBASE_ADMIN_EMAIL=admin@ulo.ad
POCKETBASE_ADMIN_PASSWORD=<secure-password>

3. Persistent Storage:
   • Volume für PocketBase: /pb_data
   • Mountpoint: pocketbase-data:/pb_data

📦 Datenbank-Migrationen

Schema-Änderungen:

1. Neue Migration erstellen:

// backend/pb_migrations/TIMESTAMP_description.js
migrate(
	(db) => {
		// Änderungen hier
	},
	(db) => {
		// Rollback hier
	}
);

2. Migrationen werden automatisch beim Start angewendet

Wichtige Collections:

• users: User-Accounts mit Username, Preferences
• links: Kurz-Links mit Metadaten
• clicks: Analytics-Daten
• folders: Link-Organisation (neu)

🚀 Deployment-Prozess

Automatisch (empfohlen):

git add .
git commit -m "feat: neue Funktion"
git push origin main
# Coolify deployed automatisch

Manuell (Notfall):

1. In Coolify Dashboard
2. Application → Redeploy
3. Logs prüfen

🔐 Sicherheit

Produktions-Checklist:

• Sichere Passwörter in Coolify Secrets
• HTTPS aktiviert
• Rate Limiting konfiguriert
• Backup-Strategie aktiv
• Monitoring eingerichtet

Backup-Strategie:

# PocketBase Backup (läuft im Container)
docker exec <container-id> /pb/pocketbase backup

# Volume Backup
docker run --rm -v pocketbase-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/pocketbase-backup.tar.gz /data

🎯 Best Practices

1. Umgebungs-Trennung:

• Lokal: Eigene PocketBase-Instanz
• Staging: Docker-Compose Test
• Produktion: Isolierter Container in Coolify

2. Datenbank-Updates:

• Immer Migrationen verwenden
• Niemals direkt in Produktion ändern
• Backup vor großen Änderungen

3. Environment Variables:

// Verwendung in Code
const POCKETBASE_URL = import.meta.env.PUBLIC_POCKETBASE_URL || 'http://127.0.0.1:8090';

🐛 Troubleshooting

Problem: Datenbank-Schema nicht aktuell

# Migration manuell ausführen
docker exec <container-id> /pb/pocketbase migrate up

Problem: Container startet nicht

# Logs prüfen
docker logs <container-id>

# Health Check
curl https://ulo.ad/api/health

Problem: Verbindung zu PocketBase fehlgeschlagen

• Prüfe Environment Variables
• Verifiziere Docker Network
• Check Firewall Rules

📊 Monitoring

Health Endpoints:

• App Health: https://ulo.ad/health
• PocketBase: https://ulo.ad/api/health
• Admin Panel: https://ulo.ad/_/

Logs in Coolify:

1. Application → Logs
2. Filter: "error" oder "warning"
3. Zeitraum anpassen

🔄 Rollback-Strategie

Bei Problemen:

1. In Coolify: Previous Deployments → Rollback
2. Manuell:

git revert HEAD
git push origin main

📝 Maintenance

Regelmäßige Tasks:

• Wöchentliche Backups prüfen
• Monatliche Security Updates
• Quartalweise Performance Review
• Jährliche Dependency Updates

Update-Prozess:

# Dependencies updaten
npm update
npm audit fix

# PocketBase updaten
# Neue Version in docker-compose.prod.yml

# Testen
docker-compose -f docker-compose.prod.yml build
docker-compose -f docker-compose.prod.yml up

# Deployen
git push origin main