Projektarbeit-MYP/docs/FRONTEND_INSTALLATION.md

MYP Frontend - Installationsanleitung

Übersicht

Das MYP Frontend ist eine Next.js-Anwendung, die mit Docker und Caddy als Reverse Proxy betrieben wird. Das konsolidierte Setup-Skript automatisiert die komplette Installation und Konfiguration.

Systemanforderungen

• Betriebssystem: Debian/Raspbian (Raspberry Pi OS)
• Hardware: Raspberry Pi 4 oder höher (empfohlen)
• RAM: Mindestens 2GB
• Speicher: Mindestens 8GB freier Speicherplatz
• Netzwerk: Internetverbindung für Installation

Schnellstart

Automatische Installation

# Als Root ausführen
sudo bash frontend/setup.sh

Das Skript bietet ein interaktives Menü mit folgenden Optionen:

1. Vollständige Frontend-Installation - Komplette Neuinstallation
2. SSL-Zertifikate neu generieren - Erneuert nur die Zertifikate
3. Service-Status prüfen - Diagnose und Monitoring
4. Beenden - Script verlassen

Detaillierte Installationsschritte

1. System-Vorbereitung

Das Skript führt automatisch folgende Schritte durch:

• System-Update: Paketlisten aktualisieren
• Grundtools installieren: curl, wget, git, openssl, etc.
• Internetverbindung prüfen: Verfügbarkeit der benötigten Ressourcen

2. Docker-Installation

• Docker CE: Container-Runtime
• Docker Compose: Multi-Container-Orchestrierung
• Service-Aktivierung: Automatischer Start beim Boot

3. SSL-Zertifikate (Mercedes)

Das Skript erstellt selbstsignierte SSL-Zertifikate mit folgenden Eigenschaften:

Zertifikat-Details:

• Organisation: Mercedes-Benz AG
• Abteilung: IT-Abteilung
• Standort: Stuttgart, Baden-Württemberg, Deutschland
• Primäre Domain: m040tbaraspi001.de040.corpintra.net

Subject Alternative Names (SAN):

• m040tbaraspi001.de040.corpintra.net
• m040tbaraspi001
• localhost
• raspberrypi
• 127.0.0.1
• 192.168.0.109

Speicherorte:

• Zertifikat: /etc/ssl/certs/myp/frontend.crt
• Privater Schlüssel: /etc/ssl/certs/myp/frontend.key
• System-CA-Store: /usr/local/share/ca-certificates/

4. Frontend-Deployment

• Zielverzeichnis: /opt/myp-frontend
• Dateisynchronisation: Exclude node_modules, .git, ssl
• Berechtigungen: Root-Ownership mit korrekten Permissions

5. Docker Compose Konfiguration

Services:

1. frontend-app

   • Build: Next.js Application
   • Port: 3000 (intern)
   • Environment: Production
   • Health Check: /health Endpoint

2. caddy

   • Image: caddy:latest
   • Ports: 80 (HTTP), 443 (HTTPS)
   • SSL-Termination und Reverse Proxy
   • Security Headers und Compression

3. db

   • SQLite-Container mit persistenten Volumes
   • Datenverzeichnis: /data

Volumes:

• caddy_data: Caddy-Daten persistent
• caddy_config: Caddy-Konfiguration
• db_data: Datenbank-Dateien

6. Systemd-Service

Service-Name: myp-frontend.service

Eigenschaften:

• Auto-Start: Beim Boot aktiviert
• Dependencies: Startet nach Docker
• Management: Standard systemctl-Befehle
• Logging: Journald-Integration
• Sicherheit: Sandboxed mit eingeschränkten Berechtigungen

7. Firewall-Konfiguration

UFW-Regeln:

• SSH: Port 22 (Remote-Zugang)
• HTTP: Port 80 (Redirect zu HTTPS)
• HTTPS: Port 443 (Hauptzugang)
• Lokale Verbindungen: 127.0.0.1, ::1
• Mercedes-Netzwerke: 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12

Zugang zur Anwendung

Nach erfolgreicher Installation ist das Frontend verfügbar unter:

• Primär: https://m040tbaraspi001.de040.corpintra.net
• Lokal: https://localhost
• IP-Direkt: https://192.168.0.109

Service-Management

Status prüfen

# Systemd Service Status
sudo systemctl status myp-frontend

# Docker Container Status
cd /opt/myp-frontend
sudo docker compose ps

# Live-Logs anzeigen
sudo docker compose logs -f

Service-Kontrolle

# Service starten
sudo systemctl start myp-frontend

# Service stoppen
sudo systemctl stop myp-frontend

# Service neustarten
sudo systemctl restart myp-frontend

# Service deaktivieren
sudo systemctl disable myp-frontend

Container-Management

# Alle Container neustarten
cd /opt/myp-frontend
sudo docker compose restart

# Einzelnen Container neustarten
sudo docker compose restart caddy
sudo docker compose restart frontend-app

# Container-Logs einzeln
sudo docker compose logs caddy
sudo docker compose logs frontend-app

Troubleshooting

Häufige Probleme

1. Frontend nicht erreichbar

Diagnose:

# Service-Status prüfen
sudo systemctl status myp-frontend

# Container-Status prüfen
cd /opt/myp-frontend
sudo docker compose ps

# Netzwerk-Test
curl -k -I https://localhost/health

Lösungsansätze:

• Container neu starten: sudo docker compose restart
• Service neu starten: sudo systemctl restart myp-frontend
• Logs prüfen: sudo docker compose logs

2. SSL-Zertifikat-Probleme

Diagnose:

# Zertifikat-Gültigkeit prüfen
openssl x509 -in /etc/ssl/certs/myp/frontend.crt -noout -dates

# SSL-Verbindung testen
openssl s_client -connect localhost:443 -servername m040tbaraspi001.de040.corpintra.net

Lösung:

# Zertifikate neu generieren
sudo bash frontend/setup.sh
# Dann Option 2 wählen (SSL-Zertifikate neu generieren)

3. Docker-Build Fehler

Diagnose:

# Build-Logs prüfen
cd /opt/myp-frontend
sudo docker compose build --no-cache

# Speicherplatz prüfen
df -h

Lösungsansätze:

• Docker aufräumen: sudo docker system prune -a
• Neuinstallation: Frontend-Verzeichnis löschen und setup.sh erneut ausführen

4. Port-Konflikte

Diagnose:

# Port-Belegung prüfen
sudo netstat -tlnp | grep -E ':(80|443)'
sudo ss -tlnp | grep -E ':(80|443)'

Lösung:

• Konflikt-Services stoppen
• UFW-Regeln prüfen: sudo ufw status

Log-Dateien

Installation:

• /var/log/myp-frontend-install.log

Caddy:

• /var/log/caddy/access.log
• /var/log/caddy/error.log

Docker:

# Container-Logs
sudo docker compose logs frontend-app
sudo docker compose logs caddy

# Systemd-Journal
sudo journalctl -u myp-frontend -f

Sicherheitshinweise

SSL/TLS

• Selbstsignierte Zertifikate erfordern Ausnahmen im Browser
• Für Produktion sollten CA-signierte Zertifikate verwendet werden
• Automatische HTTP-zu-HTTPS-Weiterleitung ist aktiviert

Firewall

• Restriktive Einstellungen - nur notwendige Ports geöffnet
• Mercedes-interne Netzwerke sind zugelassen
• Externe Zugriffe werden standardmäßig blockiert

Container-Sicherheit

• Container laufen mit minimalen Berechtigungen
• Sensitive Dateien sind read-only gemountet
• Netzwerk-Isolation zwischen Containern

Backup und Wartung

Backup wichtiger Dateien

# SSL-Zertifikate
sudo cp -r /etc/ssl/certs/myp /backup/ssl-certificates-$(date +%Y%m%d)

# Anwendungsdaten
sudo cp -r /opt/myp-frontend /backup/frontend-$(date +%Y%m%d)

# Docker Volumes
sudo docker run --rm -v myp-frontend_db_data:/data -v /backup:/backup alpine \
  tar czf /backup/db-data-$(date +%Y%m%d).tar.gz -C /data .

Regelmäßige Wartung

# Docker-System aufräumen (monatlich)
sudo docker system prune -f

# Log-Dateien rotieren (wöchentlich)
sudo logrotate -f /etc/logrotate.conf

# SSL-Zertifikat-Ablauf prüfen (monatlich)
openssl x509 -in /etc/ssl/certs/myp/frontend.crt -noout -dates

Performance-Optimierung

Raspberry Pi spezifisch

• Memory Swappiness: Reduziert auf 10
• I/O Scheduler: Optimiert für SD-Karten
• CPU Scheduling: Verbesserte Interaktivität
• Caching: Effiziente Nutzung des verfügbaren RAMs

Container-Optimierung

• Multi-Stage Builds: Reduzierte Image-Größen
• Health Checks: Automatische Fehlerbehandlung
• Resource Limits: Verhindert Memory-Leaks
• Restart Policies: Automatische Wiederherstellung

Support und Weiterentwicklung

Konfiguration anpassen

• Caddy: frontend/docker/caddy/Caddyfile bearbeiten
• Docker Compose: docker-compose.yml in /opt/myp-frontend
• SSL: Setup-Skript mit Option 2 für neue Zertifikate

Monitoring

• Health Endpoints: /health für Verfügbarkeitsprüfung
• Logs: Strukturierte JSON-Logs von Caddy
• Metrics: Docker-Container-Statistiken

Updates

# Frontend-Code aktualisieren
cd /opt/myp-frontend
sudo git pull origin main
sudo docker compose build --no-cache
sudo docker compose up -d

# System-Updates
sudo apt update && sudo apt upgrade -y
sudo reboot

---

Version: 1.0.0 Letzte Aktualisierung: $(date '+%Y-%m-%d') Autor: MYP Development Team