stechuhr3/scripts/README.md

# TimeClock v3 - Server-Management Scripts

Dieses Verzeichnis enthält hilfreiche Wartungs- und Management-Scripts für den Produktions-Server.

## Übersicht

| Script | Beschreibung | Verwendung |
|--------|--------------|------------|
| `backup-timeclock.sh` | Erstellt automatische Datenbank-Backups | Täglich per Cronjob |
| `health-check.sh` | Überwacht API-Verfügbarkeit | Alle 5 Min per Cronjob |
| `restore-backup.sh` | Stellt Datenbank-Backup wieder her | Manuell bei Bedarf |

---

## 1. backup-timeclock.sh

Erstellt automatische komprimierte Backups der MySQL-Datenbank.

### Installation

```bash
# Auf den Server kopieren
sudo cp scripts/backup-timeclock.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/backup-timeclock.sh

# Cronjob einrichten (täglich um 2 Uhr)
sudo crontab -e
```

Füge folgende Zeile hinzu:
```cron
0 2 * * * /usr/local/bin/backup-timeclock.sh >> /var/log/timeclock/backup.log 2>&1
```

### Manuell ausführen

```bash
/usr/local/bin/backup-timeclock.sh
```

### Features

- ✅ Automatische Datenbank-Backups mit Kompression
- ✅ Konfigurierbare Retention (Standard: 30 Tage)
- ✅ Optional: Code-Backups
- ✅ Optional: Remote-Backup per rsync
- ✅ Optional: E-Mail-Benachrichtigungen
- ✅ Backup-Statistiken

### Konfiguration

Bearbeite die Variablen am Anfang des Scripts:

```bash
BACKUP_DIR="/var/backups/timeclock"
RETENTION_DAYS=30
BACKUP_CODE=false          # true für Code-Backups
REMOTE_BACKUP=false        # true für Remote-Backup
SEND_EMAIL=false           # true für E-Mail-Benachrichtigung
```

### Backup-Dateien

Backups werden gespeichert unter:
- Datenbank: `/var/backups/timeclock/timeclock_db_YYYYMMDD_HHMMSS.sql.gz`
- Code: `/var/backups/timeclock/timeclock_code_YYYYMMDD_HHMMSS.tar.gz`

---

## 2. health-check.sh

Überwacht die Verfügbarkeit des Backend-API und startet den Service bei Bedarf automatisch neu.

### Installation

```bash
# Auf den Server kopieren
sudo cp scripts/health-check.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/health-check.sh

# Cronjob einrichten (alle 5 Minuten)
crontab -e
```

Füge folgende Zeile hinzu:
```cron
*/5 * * * * /usr/local/bin/health-check.sh >> /var/log/timeclock/health-check.log 2>&1
```

### Manuell ausführen

```bash
/usr/local/bin/health-check.sh
```

### Features

- ✅ Prüft `/api/health` Endpunkt
- ✅ Automatischer Neustart bei Ausfall
- ✅ Mehrere Retry-Versuche (Standard: 3)
- ✅ Unterstützt PM2 und systemd
- ✅ Optional: E-Mail/Webhook-Benachrichtigungen
- ✅ Ressourcen-Monitoring (CPU/RAM/Disk)

### Konfiguration

```bash
API_URL="http://localhost:3010/api/health"
USE_PM2=true              # false für systemd
MAX_RETRIES=3
RETRY_DELAY=5
SEND_EMAIL=false          # true für E-Mail-Benachrichtigung
```

### Benachrichtigungen

Das Script kann bei Ausfällen Benachrichtigungen senden via:
- E-Mail (benötigt `mail` command)
- Webhook (Discord, Slack, etc.)

Konfiguriere die entsprechenden Variablen im Script:

```bash
SEND_EMAIL=true
EMAIL_TO="admin@tsschulz.de"

WEBHOOK_URL="https://discord.com/api/webhooks/..."
```

---

## 3. restore-backup.sh

Interaktives Script zum Wiederherstellen von Datenbank-Backups.

### Verwendung

```bash
# Interaktive Auswahl
sudo /var/www/timeclock/scripts/restore-backup.sh

# Spezifisches Backup wiederherstellen
sudo /var/www/timeclock/scripts/restore-backup.sh timeclock_db_20251018_020000.sql.gz

# Mit vollständigem Pfad
sudo /var/www/timeclock/scripts/restore-backup.sh /var/backups/timeclock/timeclock_db_20251018_020000.sql.gz
```

### Features

- ✅ Interaktive Backup-Auswahl
- ✅ Sicherheitskopie vor Restore
- ✅ Konfirmations-Prompts
- ✅ Automatisches Service-Neustart (optional)
- ✅ Datenbank-Statistiken nach Restore

### Ablauf

1. Zeigt Liste verfügbarer Backups
2. Erstellt Sicherheitskopie der aktuellen DB
3. Bestätigung erforderlich
4. Restore durchführen
5. Optional: Service neu starten

### ⚠️ WARNUNG

Das Restore überschreibt die aktuelle Datenbank! Eine Sicherheitskopie wird automatisch erstellt, aber sei vorsichtig!

---

## Logs

Alle Scripts loggen nach:
- `/var/log/timeclock/backup.log` - Backup-Logs
- `/var/log/timeclock/health-check.log` - Health-Check-Logs

### Logs ansehen

```bash
# Backup-Logs
tail -f /var/log/timeclock/backup.log

# Health-Check-Logs
tail -f /var/log/timeclock/health-check.log

# Alle Logs
tail -f /var/log/timeclock/*.log
```

---

## Cronjob-Übersicht

Empfohlene Cronjob-Konfiguration:

```cron
# TimeClock Maintenance Jobs

# Backup: Täglich um 2 Uhr morgens
0 2 * * * /usr/local/bin/backup-timeclock.sh >> /var/log/timeclock/backup.log 2>&1

# Health-Check: Alle 5 Minuten
*/5 * * * * /usr/local/bin/health-check.sh >> /var/log/timeclock/health-check.log 2>&1

# Optional: Log-Rotation - Alte Logs löschen (älter als 90 Tage)
0 3 * * 0 find /var/log/timeclock -name "*.log" -mtime +90 -delete
```

---

## Weitere nützliche Commands

### Backup-Verwaltung

```bash
# Liste aller Backups
ls -lh /var/backups/timeclock/

# Anzahl der Backups
ls -1 /var/backups/timeclock/timeclock_db_*.sql.gz | wc -l

# Gesamtgröße der Backups
du -sh /var/backups/timeclock/

# Ältestes Backup
ls -t /var/backups/timeclock/timeclock_db_*.sql.gz | tail -1

# Neuestes Backup
ls -t /var/backups/timeclock/timeclock_db_*.sql.gz | head -1

# Manuell alte Backups löschen (älter als 30 Tage)
find /var/backups/timeclock -name "timeclock_db_*.sql.gz" -mtime +30 -delete
```

### Service-Management

```bash
# Mit PM2
pm2 status
pm2 logs timeclock-backend
pm2 restart timeclock-backend
pm2 monit

# Mit systemd
sudo systemctl status timeclock
sudo journalctl -u timeclock -f
sudo systemctl restart timeclock
```

### API-Tests

```bash
# Health-Check
curl http://localhost:3010/api/health

# Mit Details
curl -s http://localhost:3010/api/health | jq

# Response-Zeit messen
time curl -s http://localhost:3010/api/health > /dev/null
```

---

## Troubleshooting

### Script läuft nicht

```bash
# Berechtigungen prüfen
ls -l /usr/local/bin/backup-timeclock.sh

# Ausführbar machen
sudo chmod +x /usr/local/bin/backup-timeclock.sh

# Script-Fehler debuggen
bash -x /usr/local/bin/backup-timeclock.sh
```

### Cronjob läuft nicht

```bash
# Cronjobs anzeigen
crontab -l

# Cron-Logs prüfen
sudo grep CRON /var/log/syslog

# Cronjob manuell testen
/usr/local/bin/backup-timeclock.sh
```

### Backup schlägt fehl

```bash
# DB-Verbindung testen
mysql -u timeclock -p -e "SHOW DATABASES;"

# .env Datei prüfen
cat /var/www/timeclock/backend/.env

# Backup-Verzeichnis prüfen
ls -ld /var/backups/timeclock

# Schreibrechte prüfen
touch /var/backups/timeclock/test.txt
```

---

## Best Practices

1. **Regelmäßige Backups testen**
   - Teste mindestens monatlich ein Restore
   - Verifiziere Backup-Integrität

2. **Monitoring einrichten**
   - Health-Checks aktivieren
   - E-Mail-Benachrichtigungen konfigurieren

3. **Logs überwachen**
   - Prüfe regelmäßig die Log-Dateien
   - Implementiere Log-Rotation

4. **Off-Site Backups**
   - Aktiviere Remote-Backup in `backup-timeclock.sh`
   - Speichere Backups an einem anderen Ort

5. **Sicherheit**
   - Schütze Backup-Dateien (enthalten sensible Daten!)
   - Setze restriktive Berechtigungen

---

## Support

Bei Problemen:
1. Prüfe die Log-Dateien
2. Teste Scripts manuell
3. Siehe Haupt-Dokumentation: `../DEPLOYMENT.md`

---

**Automatisierte Wartung für sorgenfreien Betrieb! 🚀**