Lager Guru - Runbook

Operatives Handbuch für Verwaltung und Troubleshooting der Lager Guru Anwendung.

Sprache wählen: 🇩🇪 Deutsch | 🇬🇧 English | 🇧🇬 Български

Inhaltsverzeichnis

Anwendung starten
Status prüfen
Troubleshooting
Datenbank wiederherstellen
Service Worker Cache
VAPID Keys
Logs
Netzwerkzugriff

Anwendung starten

Docker Deployment (Production)

bash

# 1. Navigation zum Projekt
cd /path/to/lager-guru

# 2. .env Datei erstellen (falls nicht vorhanden)
cat > .env << EOF
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
EOF

# 3. Anwendung starten
docker compose up -d --build

# 4. Status prüfen
docker compose ps
docker compose logs -f lager-guru

Lokale Entwicklung

bash

# 1. Abhängigkeiten installieren
npm install

# 2. .env.local Datei erstellen
cat > .env.local << EOF
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
EOF

# 3. Dev-Server starten
npm run dev

# 4. Oder für Production Preview
npm run build
npm run preview -- --host --port 8080

Status prüfen

Health Check

bash

# Health Endpoint prüfen
curl http://lager-guru.internal/health.html

# Oder im Browser
open http://lager-guru.internal/health.html

Health Endpoint prüft:

✅ Statische Assets (HTML, CSS, JS)
✅ Supabase-Verbindung (falls konfiguriert)
⚠️ Auto-Refresh alle 30 Sekunden

Docker Status

bash

# Container-Status prüfen
docker compose ps

# Logs prüfen
docker compose logs --tail=100 lager-guru

# Ressourcen prüfen
docker stats

Datenbankverbindung

bash

# Supabase-Verbindung über CLI prüfen
psql "postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres" -c "SELECT version();"

# Oder über Supabase CLI
supabase status

Troubleshooting

Problem: Weißer Bildschirm / Anwendung lädt nicht

Ursachen:

Service Worker Cache ist korrupt
JavaScript-Fehler in der Konsole
Supabase-Anmeldedaten sind falsch

Lösung:

bash

# 1. Browser-Cache löschen
# Chrome: DevTools → Application → Clear Storage → Clear site data

# 2. Service Worker abmelden
# Chrome: DevTools → Application → Service Workers → Unregister

# 3. Hard Refresh
# Ctrl+Shift+R (Windows/Linux) oder Cmd+Shift+R (Mac)

# 4. Konsole auf Fehler prüfen
# F12 → Console Tab

Problem: Realtime funktioniert nicht (keine automatischen Updates)

Ursachen:

Realtime ist für Tabellen nicht aktiviert
RLS-Richtlinien blockieren den Zugriff
Netzwerk/Firewall blockiert WebSocket-Verbindungen

Lösung:

sql

-- 1. Prüfen, ob Tabellen in Publication sind
SELECT * FROM pg_publication_tables WHERE pubname = 'supabase_realtime';

-- 2. Tabellen hinzufügen, falls fehlend
ALTER PUBLICATION supabase_realtime ADD TABLE public.shipments;
ALTER PUBLICATION supabase_realtime ADD TABLE public.zones;
ALTER PUBLICATION supabase_realtime ADD TABLE public.user_roles;

-- 3. RLS-Richtlinien prüfen
SELECT * FROM pg_policies WHERE tablename = 'shipments';

Problem: Push-Benachrichtigungen funktionieren nicht auf iOS

Ursachen:

VAPID-Keys fehlen
Keine Edge Function zum Senden von Push-Benachrichtigungen
iOS erlaubt keine Benachrichtigungen (Einstellungen → Benachrichtigungen)

Lösung:

Prüfen, ob VAPID-Keys vorhanden sind:

bash

# In .env prüfen
grep VITE_WEB_PUSH_PUBLIC_KEY .env

Neue VAPID-Keys generieren (siehe Abschnitt VAPID Keys)
Prüfen, ob Edge Function existiert:
bash
```
supabase functions list
```
1
iOS-spezifisch:
- PWA muss installiert sein (Zum Home-Bildschirm hinzufügen)
- HTTPS-Domain ist erforderlich
- Benachrichtigungen müssen in iOS-Einstellungen erlaubt sein

Problem: Nginx gibt 403 Forbidden zurück

Ursachen:

IP-Adresse ist nicht in Allowlist
Nginx-Konfiguration ist falsch

Lösung:

bash

# 1. Nginx-Konfiguration prüfen
cat deploy/nginx.conf | grep -A 5 "allow"

# 2. IP-Adresse zur Allowlist hinzufügen
# deploy/nginx.conf bearbeiten:
#   allow YOUR_IP_ADDRESS;
#   allow 10.0.0.0/8;
#   allow 192.168.1.0/24;

# 3. Container neu starten
docker compose restart lager-guru

Problem: Build schlägt in Docker fehl

Ursachen:

Umgebungsvariablen fehlen
Node-Module-Probleme
Festplattenspeicher

Lösung:

bash

# 1. .env-Datei prüfen
cat .env

# 2. Festplattenspeicher prüfen
df -h

# 3. Docker-Cache löschen
docker system prune -a

# 4. Ohne Cache neu bauen
docker compose build --no-cache

# 5. Logs prüfen
docker compose build 2>&1 | tee build.log

Datenbank wiederherstellen

Backup-Prozess

bash

# 1. Umgebungsvariablen setzen
export DB_HOST=your-db-host
export DB_USER=your-db-user
export DB_NAME=your-db-name
export DB_PASSWORD=your-db-password

# 2. Backup starten
./scripts/backup-db.sh

# 3. Backup-Datei prüfen
ls -lh backups/lager-guru/

Wiederherstellungsprozess

bash

# 1. Backup-Datei finden
ls -lh backups/lager-guru/

# 2. Von Backup wiederherstellen
pg_restore \
  -h $DB_HOST \
  -U $DB_USER \
  -d $DB_NAME \
  --clean \
  --if-exists \
  backups/lager-guru/lager-guru-YYYYMMDD_HHMMSS.dump

# 3. Ergebnis prüfen
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT COUNT(*) FROM public.shipments;"

Point-in-Time Recovery (Supabase)

Wenn Sie Supabase Managed Database verwenden:

Dashboard → Database → Backups
Backup-Snapshot auswählen
Auf neue Datenbank oder Zeitpunkt wiederherstellen
Connection String in Anwendung aktualisieren

Notfall-Wiederherstellung

bash

# 1. Anwendung stoppen
docker compose down

# 2. Datenbank wiederherstellen
pg_restore -h $DB_HOST -U $DB_USER -d $DB_NAME backup.dump

# 3. Migrationen prüfen
supabase migration list
supabase migration up

# 4. Anwendung neu starten
docker compose up -d

Service Worker Cache

Service Worker Cache löschen

Über Browser DevTools:

Chrome DevTools öffnen (F12)
Application → Service Workers
"Unregister" für alle Workers klicken
Application → Storage → Clear site data
Hard Refresh (Ctrl+Shift+R)

Über Code (wenn Zugriff vorhanden):

javascript

// In Browser-Konsole
navigator.serviceWorker.getRegistrations().then(function(registrations) {
  for(let registration of registrations) {
    registration.unregister();
  }
});

Service Worker-Update erzwingen

bash

# 1. Version in vite.config.ts ändern
# workbox: { ... }

# 2. Neu bauen
npm run build

# 3. Neu bereitstellen
docker compose up -d --build

Gecachte Dateien prüfen

bash

# In Browser-Konsole
caches.keys().then(function(names) {
  for (let name of names) {
    caches.delete(name);
  }
});

VAPID Keys

VAPID Keys generieren

bash

# web-push installieren (falls nicht vorhanden)
npm install -g web-push

# Neue Keys generieren
npx web-push generate-vapid-keys

Ausgabe:

Public Key:  [öffentlicher Schlüssel]
Private Key: [privater Schlüssel - NICHT teilen!]

VAPID Keys konfigurieren

1. Frontend (.env):

bash

VITE_WEB_PUSH_PUBLIC_KEY=[öffentlicher Schlüssel]

2. Backend/Edge Function:

bash

# In Supabase Edge Function oder Backend
VAPID_PUBLIC_KEY=[öffentlicher Schlüssel]
VAPID_PRIVATE_KEY=[privater Schlüssel]
VAPID_EMAIL=mailto:admin@yourcompany.com

VAPID Keys prüfen

bash

# In .env prüfen
grep VITE_WEB_PUSH_PUBLIC_KEY .env

# Im Build prüfen
docker compose exec lager-guru env | grep VITE_WEB_PUSH

VAPID Keys rotieren

Wichtig: Bei Key-Rotation müssen alle bestehenden Push-Subscriptions aktualisiert werden!

bash

# 1. Neue Keys generieren
npx web-push generate-vapid-keys

# 2. .env-Dateien aktualisieren

# 3. Neu bauen und bereitstellen

# 4. Alte Subscriptions löschen (falls nötig)
# In Supabase SQL Editor:
DELETE FROM public.push_subscriptions;

Logs

Docker Logs

bash

# Alle Logs
docker compose logs -f

# Letzte 100 Zeilen
docker compose logs --tail=100

# Logs für bestimmten Service
docker compose logs -f lager-guru

# Logs mit Zeitstempel
docker compose logs -f -t lager-guru

Nginx Access Logs

bash

# Im Container
docker compose exec lager-guru cat /var/log/nginx/access.log

# Oder wenn Volume-Mapping vorhanden
tail -f /var/log/nginx/access.log

Anwendungs-Logs

Für Frontend-Anwendungen sind Logs in der Browser-Konsole:

Chrome DevTools → Console
Network-Tab für HTTP-Anfragen
Application-Tab für Service Worker-Logs

Supabase Logs

Dashboard → Logs
- API Logs
- Auth Logs
- Realtime Logs
- Database Logs
SQL Editor → Query History
- Alle ausgeführten Abfragen

Log-Rotation

bash

# Log-Rotation für Nginx einrichten (wenn kein Docker-Logging)
# /etc/logrotate.d/nginx
/var/log/nginx/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 www-data adm
    sharedscripts
    postrotate
        [ -f /var/run/nginx.pid ] && kill -USR1 `cat /var/run/nginx.pid`
    endscript
}

Netzwerkzugriff

Netzwerkzugriff prüfen

bash

# Prüfen, ob Port 80 geöffnet ist
netstat -tuln | grep :80

# Oder
ss -tuln | grep :80

# Firewall prüfen
sudo ufw status

Firewall konfigurieren

bash

# HTTP (Port 80) erlauben
sudo ufw allow 80/tcp

# HTTPS (Port 443) erlauben - wenn TLS vorhanden
sudo ufw allow 443/tcp

# Regeln prüfen
sudo ufw status verbose

Interner Netzwerkzugriff

bash

# Nginx Allowlist prüfen
cat deploy/nginx.conf | grep allow

# Zugriff von verschiedenen IP-Adressen testen
curl -I http://lager-guru.internal/health.html

# Nginx Error Logs prüfen
docker compose exec lager-guru tail -f /var/log/nginx/error.log

Häufige Probleme

Problem: "Cannot connect to Supabase"

Lösung:

.env-Datei prüfen
Netzwerkverbindung prüfen: curl https://your-project.supabase.co
Firewall-Regeln prüfen
Supabase Dashboard auf Status prüfen

Problem: "403 Forbidden" beim Zugriff

Lösung:

IP-Adresse in Allowlist prüfen
RLS-Richtlinien in Supabase prüfen
Benutzerrolle in user_roles-Tabelle prüfen

Problem: "Build schlägt mit Speicherfehler fehl"

Lösung:

bash

# Node.js-Speicherlimit erhöhen
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Problem: "Docker-Container beendet sich sofort"

Lösung:

bash

# Logs prüfen
docker compose logs lager-guru

# Konfiguration prüfen
docker compose config

# Prüfen, ob Port 80 frei ist
netstat -tuln | grep :80

Kontakte und Support

GitHub Issues: Issue für Probleme erstellen
Dokumentation: Siehe README.md für vollständige Dokumentation
Supabase Support: Dashboard → Support

Letzte Aktualisierung: 2025-11-05

Lager Guru - Runbook ​

Inhaltsverzeichnis ​

Anwendung starten ​

Docker Deployment (Production) ​

Lokale Entwicklung ​

Status prüfen ​

Health Check ​

Docker Status ​

Datenbankverbindung ​

Troubleshooting ​

Problem: Weißer Bildschirm / Anwendung lädt nicht ​

Problem: Realtime funktioniert nicht (keine automatischen Updates) ​

Problem: Push-Benachrichtigungen funktionieren nicht auf iOS ​

Problem: Nginx gibt 403 Forbidden zurück ​

Problem: Build schlägt in Docker fehl ​

Datenbank wiederherstellen ​

Backup-Prozess ​

Wiederherstellungsprozess ​

Point-in-Time Recovery (Supabase) ​

Notfall-Wiederherstellung ​

Service Worker Cache ​

Service Worker Cache löschen ​

Service Worker-Update erzwingen ​

Gecachte Dateien prüfen ​

VAPID Keys ​

VAPID Keys generieren ​

VAPID Keys konfigurieren ​

VAPID Keys prüfen ​

VAPID Keys rotieren ​

Logs ​

Docker Logs ​

Nginx Access Logs ​

Anwendungs-Logs ​

Supabase Logs ​

Log-Rotation ​

Netzwerkzugriff ​

Netzwerkzugriff prüfen ​

Firewall konfigurieren ​

Interner Netzwerkzugriff ​

Häufige Probleme ​

Problem: "Cannot connect to Supabase" ​

Problem: "403 Forbidden" beim Zugriff ​

Problem: "Build schlägt mit Speicherfehler fehl" ​

Problem: "Docker-Container beendet sich sofort" ​

Kontakte und Support ​

Lager Guru - Runbook

Inhaltsverzeichnis

Anwendung starten

Docker Deployment (Production)

Lokale Entwicklung

Status prüfen

Health Check

Docker Status

Datenbankverbindung

Troubleshooting

Problem: Weißer Bildschirm / Anwendung lädt nicht

Problem: Realtime funktioniert nicht (keine automatischen Updates)

Problem: Push-Benachrichtigungen funktionieren nicht auf iOS

Problem: Nginx gibt 403 Forbidden zurück

Problem: Build schlägt in Docker fehl

Datenbank wiederherstellen

Backup-Prozess

Wiederherstellungsprozess

Point-in-Time Recovery (Supabase)

Notfall-Wiederherstellung

Service Worker Cache

Service Worker Cache löschen

Service Worker-Update erzwingen

Gecachte Dateien prüfen

VAPID Keys

VAPID Keys generieren

VAPID Keys konfigurieren

VAPID Keys prüfen

VAPID Keys rotieren

Logs

Docker Logs

Nginx Access Logs

Anwendungs-Logs

Supabase Logs

Log-Rotation

Netzwerkzugriff

Netzwerkzugriff prüfen

Firewall konfigurieren

Interner Netzwerkzugriff

Häufige Probleme

Problem: "Cannot connect to Supabase"

Problem: "403 Forbidden" beim Zugriff

Problem: "Build schlägt mit Speicherfehler fehl"

Problem: "Docker-Container beendet sich sofort"

Kontakte und Support