Update: Dokumentation und Production Setup überarbeitet

This commit is contained in:
2025-05-23 08:22:28 +02:00
parent aa4ec84a44
commit 0038b15c5b
2 changed files with 793 additions and 131 deletions

596
README.md
View File

@ -1,139 +1,475 @@
# 📦 MYP - Manage your Printer
# 🖨️ MYP - Manage your Printer
MYP *(Manage your Printer)* ist eine Plattform zur Reservierung von 3D-Druckern, die für die TBA im Werk 040, Berlin-Marienfelde, entwickelt wurde.
[![Docker](https://img.shields.io/badge/Docker-Ready-blue?logo=docker)](https://docker.com)
[![Linux](https://img.shields.io/badge/Linux-Compatible-green?logo=linux)](https://linux.org)
[![Windows](https://img.shields.io/badge/Windows-Compatible-blue?logo=windows)](https://windows.com)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
[![Version](https://img.shields.io/badge/Version-2.0.0-brightgreen.svg)](https://github.com)
> Frontend: https://git.i.mercedes-benz.com/TBA-Berlin-FI/MYP/tree/main/frontend
MYP *(Manage your Printer)* ist eine moderne, containerbasierte Plattform zur Verwaltung und Reservierung von 3D-Druckern, entwickelt für die TBA im Werk 040, Berlin-Marienfelde.
> ⚠️ MYP ist zzt. in Entwicklung
## 🏗️ Architektur
> ‼ Datenbank aus Blueprint steht im Konflikt zu MYP.sql - Integration muss besprochen werden
Das System basiert auf einer **Microservice-Architektur** mit klarer Trennung zwischen Frontend und Backend:
> 💡 Vorschlag wenn machbar @Torben: Aufteilung der Datenbanken? API ist ja nur für Drucker zuständig; WebInterface für Authentifizierung, Sessions etc.
- **🖥️ Backend**: Flask API Server (Python) - Port 5000
- **🌐 Frontend**: Next.js Web Interface (TypeScript/React) - Port 3000
- **🔄 Proxy**: Caddy Reverse Proxy - Port 80/443
- **📊 Monitoring**: Prometheus & Grafana (Entwicklung)
> UltiMaker HTTP API: https://support.makerbot.com/s/article/1667412427787
### 🔧 Technologie-Stack
**Backend:**
- Flask 3.0+ (Python Web Framework)
- SQLAlchemy (ORM)
- JWT Authentication
- TAPO Smart Plug Integration
- RESTful API Design
**Frontend:**
- Next.js 14+ (React Framework)
- TypeScript (Type Safety)
- Tailwind CSS (Styling)
- Drizzle ORM (Database)
- Modern UI Components
**Infrastructure:**
- Docker & Docker Compose
- Caddy (Reverse Proxy)
- Prometheus (Monitoring)
- Grafana (Dashboards)
## 🚀 Schnellstart
### Voraussetzungen
- **Docker** & **Docker Compose** installiert
- **Git** (empfohlen für Entwicklung)
- **4GB RAM** und **10GB freier Speicherplatz**
- **PowerShell 5.1+** (Windows) oder **Bash 4.0+** (Linux/macOS)
### Installation
1. **Repository klonen**
```bash
git clone <repository-url>
cd Projektarbeit-MYP
```
2. **System starten**
**Windows:**
```powershell
# Einfacher Start (Entwicklungsumgebung)
.\start.ps1
# Mit Optionen
.\start.ps1 -Help # Hilfe anzeigen
.\start.ps1 prod # Produktionsumgebung
.\start.ps1 dev -Clean # Mit Bereinigung
```
**Linux/macOS:**
```bash
# Ausführungsrechte setzen (einmalig)
chmod +x start.sh cleanup.sh
# Einfacher Start (Entwicklungsumgebung)
./start.sh
# Mit Optionen
./start.sh --help # Hilfe anzeigen
./start.sh prod # Produktionsumgebung
./start.sh dev --clean # Mit Bereinigung
```
3. **Zugriff auf die Anwendung**
- 🌐 **Web Interface**: http://localhost
- 🔧 **Backend API**: http://localhost/api
- ⚛️ **Frontend Dev**: http://localhost:3000 (nur Entwicklung)
## 📋 Verfügbare Umgebungen
### 🛠️ Entwicklung (Standard)
```bash
# Windows
.\start.ps1 dev
# Linux/macOS
./start.sh dev
```
**Features:**
- Hot Reload für Frontend und Backend
- Debug-Server auf Port 5555 (Backend) und 8081 (Frontend)
- Monitoring: Prometheus (9090), Grafana (3001)
- Datenbank-Viewer: Adminer (8080)
- Redis Cache (6379)
- Entwickler-Tools aktiviert
### 🚀 Produktion
```bash
# Windows
.\start.ps1 prod
# Linux/macOS
./start.sh prod
```
**Features:**
- Optimierte Container-Images
- SSL-Verschlüsselung (Let's Encrypt)
- Performance-Optimierungen
- Sicherheitsheader
- Automatische Backups
- Health Checks
### 🧪 Test
```bash
# Windows
.\start.ps1 test
# Linux/macOS
./start.sh test
```
**Features:**
- In-Memory-Datenbank
- Mock-Services
- Test-Fixtures
- Coverage-Reports
- Automatisierte Tests
## 🛠️ Entwicklung
### Projektstruktur
```
Projektarbeit-MYP/
├── 🖥️ backend/ # Flask API Server
│ ├── app.py # Hauptanwendung
│ ├── config.py # Konfiguration
│ ├── security.py # Sicherheitsmodule
│ ├── monitoring.py # Monitoring & Logging
│ ├── requirements.txt # Python-Abhängigkeiten
│ ├── Dockerfile # Produktions-Container
│ ├── Dockerfile.dev # Entwicklungs-Container
│ ├── instance/ # Datenbank & Uploads
│ ├── logs/ # Anwendungslogs
│ ├── migrations/ # Datenbankmigrationen
│ ├── static/ # Statische Dateien
│ └── templates/ # HTML-Templates
├── 🌐 frontend/ # Next.js Web Interface
│ ├── src/ # Quellcode
│ │ ├── app/ # App Router (Next.js 14)
│ │ ├── components/ # React-Komponenten
│ │ ├── server/ # Server-seitige Logik
│ │ └── utils/ # Hilfsfunktionen
│ ├── public/ # Öffentliche Dateien
│ ├── package.json # Node.js-Abhängigkeiten
│ ├── Dockerfile # Produktions-Container
│ ├── Dockerfile.dev # Entwicklungs-Container
│ ├── tailwind.config.ts # Tailwind-Konfiguration
│ ├── tsconfig.json # TypeScript-Konfiguration
│ └── drizzle/ # Datenbank-Schema
├── 🔄 proxy/ # Caddy Reverse Proxy
│ └── Caddyfile # Proxy-Konfiguration
├── 📊 monitoring/ # Prometheus & Grafana
│ ├── prometheus/ # Monitoring-Konfiguration
│ └── grafana/ # Dashboard-Konfiguration
├── 🔧 infrastructure/ # Deployment & Konfiguration
│ ├── scripts/ # Deployment-Skripte
│ │ ├── start.ps1 # Windows-Startskript
│ │ ├── start.sh # Linux/macOS-Startskript
│ │ ├── cleanup.ps1 # Windows-Bereinigung
│ │ └── cleanup.sh # Linux/macOS-Bereinigung
│ └── environments/ # Umgebungskonfigurationen
│ ├── development.env # Entwicklungsumgebung
│ ├── production.env # Produktionsumgebung
│ └── test.env # Testumgebung
├── 🧪 tests/ # Übergreifende Tests
│ ├── e2e/ # End-to-End-Tests
│ └── integration/ # Integrationstests
├── 📚 docs/ # Projektdokumentation
├── 📝 logs/ # Systemlogs
├── 🐳 docker-compose.yml # Hauptkonfiguration
├── 🐳 docker-compose.dev.yml # Entwicklungskonfiguration
├── 📋 README.md # Diese Datei
├── 📋 PROJECT_STRUCTURE.md # Detaillierte Architektur
├── 📋 Dokumentation.md # Deutsche Dokumentation
└── 📄 LICENSE.md # Lizenzinformationen
```
### Backend-Entwicklung
```bash
cd backend
# Virtuelle Umgebung erstellen
python -m venv venv
# Aktivieren
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
# Abhängigkeiten installieren
pip install -r requirements.txt
# Entwicklungsserver starten
flask run --debug --host=0.0.0.0 --port=5000
```
### Frontend-Entwicklung
```bash
cd frontend
# Abhängigkeiten installieren
pnpm install
# Entwicklungsserver starten
pnpm dev
# Build für Produktion
pnpm build
# Linting & Formatierung
pnpm lint
pnpm format
```
### API-Dokumentation
Die API-Dokumentation ist verfügbar unter:
- **Swagger UI**: http://localhost/api/docs
- **OpenAPI Spec**: http://localhost/api/swagger.json
- **Redoc**: http://localhost/api/redoc
## 🔧 Konfiguration
### Umgebungsvariablen
Konfigurationsdateien befinden sich in `infrastructure/environments/`:
- `development.env` - Entwicklungsumgebung
- `production.env` - Produktionsumgebung
- `test.env` - Testumgebung
### Drucker-Konfiguration
Drucker werden über die `PRINTERS` Umgebungsvariable konfiguriert:
```json
{
"Drucker 1": {
"ip": "192.168.0.100",
"model": "UltiMaker S5",
"location": "Raum A.1.01"
},
"Drucker 2": {
"ip": "192.168.0.101",
"model": "UltiMaker S5",
"location": "Raum A.1.02"
}
}
```
### TAPO Smart Plug Integration
```env
TAPO_USERNAME=your-email@example.com
TAPO_PASSWORD=your-secure-password
```
### SSL/TLS-Konfiguration (Produktion)
```env
CADDY_DOMAIN=your-domain.com
CADDY_EMAIL=admin@your-domain.com
SSL_ENABLED=true
```
## 🧹 Wartung
### System bereinigen
**Windows:**
```powershell
# Interaktive Bereinigung
.\cleanup.ps1
# Automatische Bereinigung
.\cleanup.ps1 -Force
# Vollständige Bereinigung (inkl. Volumes)
.\cleanup.ps1 -All -Force
```
**Linux/macOS:**
```bash
# Interaktive Bereinigung
./cleanup.sh
# Automatische Bereinigung
./cleanup.sh --force
# Vollständige Bereinigung (inkl. Volumes)
./cleanup.sh --all --force
```
### Logs anzeigen
```bash
# Alle Services
docker-compose logs -f
# Spezifische Services
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f caddy
# Mit Zeitstempel
docker-compose logs -f -t
```
### Container-Status prüfen
```bash
# Status aller Container
docker-compose ps
# Detaillierte Informationen
docker-compose top
# Ressourcenverbrauch
docker stats
# Health Checks
docker-compose exec backend curl -f http://localhost:5000/health
docker-compose exec frontend curl -f http://localhost:3000/api/health
```
### Backup & Restore
```bash
# Datenbank-Backup erstellen
docker-compose exec backend python -c "
import sqlite3
import shutil
shutil.copy('instance/myp.db', 'instance/backup_$(date +%Y%m%d_%H%M%S).db')
"
# Logs archivieren
tar -czf logs_backup_$(date +%Y%m%d_%H%M%S).tar.gz logs/
```
## 🔒 Sicherheit
### Produktionsumgebung
- **SSL/TLS**: Automatische Let's Encrypt-Zertifikate
- **Security Headers**: HSTS, CSP, X-Frame-Options
- **Rate Limiting**: API-Endpunkt-Schutz
- **Authentication**: JWT-basierte Authentifizierung
- **Input Validation**: Umfassende Eingabevalidierung
- **CORS**: Konfigurierbare Cross-Origin-Richtlinien
### Geheimnisse verwalten
```bash
# Sichere Umgebungsvariablen setzen
echo "SECRET_KEY=$(openssl rand -hex 32)" >> infrastructure/environments/production.env
echo "JWT_SECRET=$(openssl rand -hex 32)" >> infrastructure/environments/production.env
```
## 🚨 Fehlerbehebung
### Häufige Probleme
**Docker-Container starten nicht:**
```bash
# Docker-Status prüfen
docker info
# Container-Logs anzeigen
docker-compose logs
# Ports prüfen
netstat -tulpn | grep :80
netstat -tulpn | grep :3000
netstat -tulpn | grep :5000
```
**Frontend kann Backend nicht erreichen:**
```bash
# Netzwerk-Konfiguration prüfen
docker network ls
docker network inspect projektarbeit-myp_myp-network
# API-Erreichbarkeit testen
curl -f http://localhost/api/health
```
**Datenbank-Probleme:**
```bash
# Datenbank-Integrität prüfen
docker-compose exec backend python -c "
import sqlite3
conn = sqlite3.connect('instance/myp.db')
conn.execute('PRAGMA integrity_check;')
print(conn.fetchall())
"
```
### Support
Bei Problemen:
1. Prüfen Sie die Logs: `docker-compose logs`
2. Überprüfen Sie die Systemvoraussetzungen
3. Führen Sie eine Bereinigung durch: `./cleanup.sh --force`
4. Starten Sie das System neu: `./start.sh`
## 📈 Performance
### Monitoring
- **Prometheus**: http://localhost:9090 (nur Entwicklung)
- **Grafana**: http://localhost:3001 (nur Entwicklung)
- **Caddy Admin**: http://localhost:2019
### Optimierungen
- **Container-Images**: Multi-Stage-Builds für minimale Größe
- **Caching**: Redis für Session-Management
- **CDN**: Statische Assets über Caddy
- **Database**: SQLite mit WAL-Modus für bessere Performance
## 🤝 Beitragen
1. Fork des Repositories erstellen
2. Feature-Branch erstellen: `git checkout -b feature/neue-funktion`
3. Änderungen committen: `git commit -am 'Neue Funktion hinzufügen'`
4. Branch pushen: `git push origin feature/neue-funktion`
5. Pull Request erstellen
## 📄 Lizenz
Dieses Projekt steht unter der MIT-Lizenz. Siehe [LICENSE.md](LICENSE.md) für Details.
## 🙏 Danksagungen
- **TBA Werk 040** - Für die Unterstützung und Anforderungen
- **Open Source Community** - Für die verwendeten Technologien
- **Docker Team** - Für die Container-Technologie
- **Next.js Team** - Für das Frontend-Framework
- **Flask Team** - Für das Backend-Framework
---
# Datenbankstruktur
(MYP.sql - Gerät: Reservation Pi)
### Printer
- Speichert Informationen zu Druckern.
- Beinhaltet Details wie Namen, Beschreibung und Betriebsstatus.
- Verknüpft mit Druckaufträgen.
### PrintJob
- Enthält alle Druckaufträge.
- Jeder Auftrag ist einem Drucker und einem Benutzer zugeordnet.
- Speichert Startzeit, Dauer und Kommentare zu den Aufträgen.
- Erfassung, ob ein Auftrag abgebrochen wurde und die dazugehörige Begründung.
### Account
- Verwaltet Benutzerkonten.
- Speichert Authentifizierungsdetails wie Tokens und deren Ablaufzeiten.
### Session
- Erfasst Session-Daten.
- Beinhaltet eindeutige Session-Tokens und Ablaufdaten.
### User
- Speichert Benutzerinformationen.
- Verknüpft mit Druckaufträgen, Accounts und Sessions.
## Fremdschlüsselbeziehungen
- `User` ist verknüpft mit `PrintJob`, `Account` und `Session` über Benutzer-ID.
- `Printer` ist verknüpft mit `PrintJob` über die Drucker-ID.
## Installation und Start
### Windows
1. Stellen Sie sicher, dass Docker Desktop installiert und gestartet ist.
2. Öffnen Sie PowerShell und navigieren Sie zum Projektverzeichnis.
3. Führen Sie das Start-Skript aus:
```
.\start.ps1
```
### Linux/Mac
1. Stellen Sie sicher, dass Docker installiert und gestartet ist.
2. Öffnen Sie ein Terminal und navigieren Sie zum Projektverzeichnis.
3. Machen Sie die Skripte ausführbar:
```
chmod +x start.sh cleanup.sh
```
4. Führen Sie das Start-Skript aus:
```
./start.sh
```
## Bereinigung der Umgebung
Um eine vollständige Bereinigung aller Container, Images und Volumes durchzuführen, können Sie folgende Skripte verwenden:
### Windows
```
.\cleanup.ps1
```
### Linux/Mac
```
./cleanup.sh
```
Die Bereinigung kann auch während des Starts der Anwendung durchgeführt werden, wenn alte Container erkannt werden.
## Backend-Interface
Das Backend-Interface ist unter folgenden URLs erreichbar:
- Produktionsumgebung: http://localhost:5000
- Debug-Server: http://localhost:5555
## Frontend-Interface
Das Frontend-Interface ist unter folgenden URLs erreichbar:
- Produktionsumgebung: http://localhost:80 oder https://localhost:443
- Debug-Server: http://localhost:8081
## SSH-Server
Die Start-Skripte sorgen automatisch dafür, dass ein SSH-Server installiert, aktiviert und gestartet wird:
- Unter Linux: Verwendet systemd, um den OpenSSH-Server zu aktivieren und zu starten
- Unter Windows: Installiert und konfiguriert den Windows OpenSSH-Server
Der SSH-Server wird so konfiguriert, dass er automatisch beim Systemstart aktiviert wird, um einen Fernzugriff auf das System zu ermöglichen. Auf Windows-Systemen wird auch eine entsprechende Firewall-Regel erstellt.
### Manuelles Einrichten des SSH-Servers
Falls die automatische Installation fehlschlägt:
#### Linux (Debian/Ubuntu)
```
sudo apt-get update
sudo apt-get install openssh-server
sudo systemctl enable ssh
sudo systemctl start ssh
```
#### Windows 10/11
1. Öffnen Sie "Einstellungen" > "Apps" > "Optionale Features"
2. Klicken Sie auf "Feature hinzufügen" und wählen Sie "OpenSSH Server"
3. Nach der Installation öffnen Sie PowerShell als Administrator und führen Sie folgende Befehle aus:
```
Set-Service -Name sshd -StartupType Automatic
Start-Service sshd
New-NetFirewallRule -Name 'OpenSSH-Server-In-TCP' -DisplayName 'OpenSSH Server (TCP-In)' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22
```
**Entwickelt mit ❤️ für die TBA im Werk 040, Berlin-Marienfelde**