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:

# 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:

# 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

# 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

# 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

# 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

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

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

Schritt 6: Nginx einrichten

# 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

# 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):

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:

# 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

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

Schritt 10: Testen

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

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

---

Nützliche Befehle

Mit PM2:

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:

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

Nginx:

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:

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

---

Updates durchführen

Automatisch mit Script:

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

Manuell:

# 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

# 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

# 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

# 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

# Zertifikat erneuern
sudo certbot renew --force-renewal

# Nginx neustarten
sudo systemctl restart nginx

---

Backup & Restore

Backup erstellen:

# 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:

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

# Code
./deploy.sh rollback

---

Performance-Tipps

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

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:

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:

# /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

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):

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