stechuhr3/QUICKSTART_DEPLOYMENT.md

# 🚀 TimeClock v3 - Schnellstart Deployment

Eine Schritt-für-Schritt-Anleitung für das Deployment auf **stechuhr3.tsschulz.de**.

## Voraussetzungen

✅ Ubuntu 22.04 Server  
✅ Root/Sudo-Zugriff  
✅ Domain `stechuhr3.tsschulz.de` zeigt auf Server-IP  
✅ MySQL/MariaDB läuft  
✅ SSH-Zugang zum Server  

## Option 1: Automatisches Deployment (Empfohlen) 🎯

### Auf deinem lokalen Rechner:

```bash
# 1. Projekt auf Server übertragen
cd /home/torsten/Programs/TimeClock
rsync -avz --exclude 'node_modules' --exclude '.git' . user@YOUR_SERVER_IP:/tmp/timeclock-deploy/

# 2. SSH zum Server
ssh user@YOUR_SERVER_IP
```

### Auf dem Server:

```bash
# 3. Projekt vorbereiten
sudo mkdir -p /var/www
sudo mv /tmp/timeclock-deploy /var/www/timeclock
sudo chown -R $USER:$USER /var/www/timeclock

# 4. Automatisches Deployment starten
cd /var/www/timeclock
chmod +x deploy.sh
./deploy.sh install
```

Das war's! 🎉 Das Script führt automatisch durch alle notwendigen Schritte.

---

## Option 2: Manuelles Deployment (Schritt für Schritt) 📝

### Schritt 1: System vorbereiten

```bash
# System aktualisieren
sudo apt update && sudo apt upgrade -y

# Node.js 20.x installieren
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Weitere Abhängigkeiten
sudo apt install -y nginx certbot python3-certbot-nginx
sudo npm install -g pm2
```

### Schritt 2: Datenbank einrichten

```bash
# MySQL/MariaDB
sudo mysql -u root -p

# In MySQL:
CREATE DATABASE IF NOT EXISTS stechuhr2;
CREATE USER IF NOT EXISTS 'timeclock'@'localhost' IDENTIFIED BY 'DEIN_SICHERES_PASSWORT';
GRANT ALL PRIVILEGES ON stechuhr2.* TO 'timeclock'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

### Schritt 3: Projekt auf Server übertragen

```bash
# Auf lokalem Rechner:
rsync -avz --exclude 'node_modules' ~/Programs/TimeClock/ user@YOUR_SERVER_IP:/var/www/timeclock/

# ODER per Git (wenn in Repository):
# ssh user@YOUR_SERVER_IP
# cd /var/www
# git clone https://github.com/IHR-USERNAME/TimeClock.git timeclock
```

### Schritt 4: Backend konfigurieren

```bash
cd /var/www/timeclock/backend

# Dependencies installieren
npm install --production

# .env erstellen
cp env.production.template .env
nano .env

# Wichtige Werte anpassen:
# - DB_PASSWORD=dein_db_passwort
# - JWT_SECRET=generiere_mit_node_crypto
# - SESSION_SECRET=generiere_mit_node_crypto
# - FRONTEND_URL=https://stechuhr3.tsschulz.de

# Secrets generieren:
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
```

### Schritt 5: Frontend bauen

```bash
cd /var/www/timeclock/frontend
npm install
npm run build
```

### Schritt 6: Nginx einrichten

```bash
# Konfiguration kopieren
sudo cp /var/www/timeclock/nginx.conf /etc/nginx/sites-available/stechuhr3.tsschulz.de

# Site aktivieren
sudo ln -s /etc/nginx/sites-available/stechuhr3.tsschulz.de /etc/nginx/sites-enabled/

# Default-Site deaktivieren (optional)
sudo rm /etc/nginx/sites-enabled/default

# Testen und neuladen
sudo nginx -t
sudo systemctl reload nginx
```

### Schritt 7: SSL-Zertifikat erstellen

```bash
# Let's Encrypt Zertifikat
sudo certbot --nginx -d stechuhr3.tsschulz.de

# Folge den Anweisungen:
# - E-Mail eingeben
# - Nutzungsbedingungen akzeptieren
# - HTTPS-Redirect aktivieren (empfohlen)
```

### Schritt 8: Backend starten

**Option A: Mit PM2 (empfohlen):**

```bash
cd /var/www/timeclock/backend
pm2 start src/index.js --name timeclock-backend --env production
pm2 save
pm2 startup systemd
# Führe den angezeigten Befehl aus
```

**Option B: Mit systemd:**

```bash
# Service installieren
sudo cp /var/www/timeclock/timeclock.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable timeclock
sudo systemctl start timeclock
```

### Schritt 9: Firewall konfigurieren

```bash
sudo ufw allow ssh
sudo ufw allow 'Nginx Full'
sudo ufw enable
```

### Schritt 10: Testen

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

# Frontend aufrufen
# Browser: https://stechuhr3.tsschulz.de
```

---

## Nützliche Befehle

### Mit PM2:

```bash
pm2 status                    # Status anzeigen
pm2 logs timeclock-backend    # Logs anzeigen
pm2 restart timeclock-backend # Neustart
pm2 stop timeclock-backend    # Stoppen
pm2 monit                     # Monitoring
```

### Mit systemd:

```bash
sudo systemctl status timeclock    # Status
sudo journalctl -u timeclock -f    # Logs
sudo systemctl restart timeclock   # Neustart
sudo systemctl stop timeclock      # Stoppen
```

### Nginx:

```bash
sudo nginx -t                      # Config testen
sudo systemctl reload nginx        # Neuladen
sudo tail -f /var/log/nginx/stechuhr3.access.log
sudo tail -f /var/log/nginx/stechuhr3.error.log
```

### SSL:

```bash
sudo certbot certificates          # Zertifikate anzeigen
sudo certbot renew                 # Erneuern
sudo certbot renew --dry-run       # Test-Erneuerung
```

---

## Updates durchführen

### Automatisch mit Script:

```bash
cd /var/www/timeclock
./deploy.sh backup  # Erst Backup
./deploy.sh update  # Dann Update
```

### Manuell:

```bash
# 1. Backup erstellen
cd /var/www/timeclock
./deploy.sh backup

# 2. Code aktualisieren
git pull  # oder neue Dateien übertragen

# 3. Backend
cd backend
npm install --production
pm2 restart timeclock-backend

# 4. Frontend
cd ../frontend
npm install
npm run build
```

---

## Problembehebung

### Backend startet nicht

```bash
# Logs prüfen
pm2 logs timeclock-backend --err

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

# Port-Belegung prüfen
sudo netstat -tulpn | grep 3010
```

### Frontend zeigt nicht an

```bash
# Nginx testen
sudo nginx -t

# Build-Verzeichnis prüfen
ls -la /var/www/timeclock/frontend/dist/

# Nginx neuladen
sudo systemctl reload nginx
```

### API-Anfragen schlagen fehl

```bash
# CORS: FRONTEND_URL in .env prüfen
# Backend muss FRONTEND_URL=https://stechuhr3.tsschulz.de haben

# Nginx Proxy prüfen
sudo nginx -t
```

### SSL-Probleme

```bash
# Zertifikat erneuern
sudo certbot renew --force-renewal

# Nginx neustarten
sudo systemctl restart nginx
```

---

## Backup & Restore

### Backup erstellen:

```bash
# Automatisch
./deploy.sh backup

# Manuell - Datenbank
mysqldump -u timeclock -p stechuhr2 | gzip > backup_$(date +%Y%m%d).sql.gz

# Manuell - Code
tar -czf backup_code_$(date +%Y%m%d).tar.gz /var/www/timeclock
```

### Restore:

```bash
# Datenbank
gunzip < backup_20251018.sql.gz | mysql -u timeclock -p stechuhr2

# Code
./deploy.sh rollback
```

---

## Performance-Tipps

### PM2 Cluster-Modus (nutzt alle CPU-Kerne):

```bash
pm2 delete timeclock-backend
pm2 start src/index.js --name timeclock-backend --instances max --env production
pm2 save
```

### Nginx Caching aktivieren:

Füge in `/etc/nginx/sites-available/stechuhr3.tsschulz.de` hinzu:

```nginx
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=100m;

location /api {
    proxy_cache api_cache;
    proxy_cache_valid 200 5m;
    # ... rest der Config
}
```

---

## Sicherheits-Checkliste

- [ ] Starke Passwörter für DB, JWT, Session
- [ ] SSL/TLS aktiviert
- [ ] Firewall konfiguriert
- [ ] NODE_ENV=production
- [ ] Console-Logs deaktiviert (Vite Build)
- [ ] Regelmäßige Backups eingerichtet
- [ ] fail2ban installieren (optional)
- [ ] Rate Limiting aktivieren (optional)

---

## Monitoring einrichten

### Einfaches Health-Check Script:

```bash
# /usr/local/bin/check-timeclock.sh
#!/bin/bash
if ! curl -sf http://localhost:3010/api/health > /dev/null; then
    echo "Backend down! $(date)" >> /var/log/timeclock/health.log
    pm2 restart timeclock-backend
fi
```

```bash
sudo chmod +x /usr/local/bin/check-timeclock.sh

# Cronjob alle 5 Minuten
sudo crontab -e
# */5 * * * * /usr/local/bin/check-timeclock.sh
```

### PM2 Plus (Cloud-Monitoring):

```bash
pm2 plus
# Link folgen und Account verbinden
```

---

## Support

Detaillierte Dokumentation: `DEPLOYMENT.md`

Bei Problemen:
1. Logs prüfen (`pm2 logs` oder `journalctl -u timeclock`)
2. Nginx-Logs prüfen (`/var/log/nginx/`)
3. Health-Check testen: `curl http://localhost:3010/api/health`

---

**Deployment erfolgreich! 🎉**

Deine App läuft auf: **https://stechuhr3.tsschulz.de**