Till Tomczak 0038b15c5b Update: Dokumentation und Production Setup überarbeitet

2025-05-23 08:22:28 +02:00

12 KiB

Executable File

Raw Blame History

🖨️ MYP - Manage your Printer

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.

🏗️ Architektur

Das System basiert auf einer Microservice-Architektur mit klarer Trennung zwischen Frontend und Backend:

🖥️ 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)

🔧 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

Repository klonen

git clone <repository-url>
cd Projektarbeit-MYP

System starten

Windows:

# Einfacher Start (Entwicklungsumgebung)
.\start.ps1

# Mit Optionen
.\start.ps1 -Help                    # Hilfe anzeigen
.\start.ps1 prod                     # Produktionsumgebung
.\start.ps1 dev -Clean               # Mit Bereinigung

Linux/macOS:

# 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

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)

# 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

# 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

# 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

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

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:

{
  "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

TAPO_USERNAME=your-email@example.com
TAPO_PASSWORD=your-secure-password

SSL/TLS-Konfiguration (Produktion)

CADDY_DOMAIN=your-domain.com
CADDY_EMAIL=admin@your-domain.com
SSL_ENABLED=true

🧹 Wartung

System bereinigen

Windows:

# Interaktive Bereinigung
.\cleanup.ps1

# Automatische Bereinigung
.\cleanup.ps1 -Force

# Vollständige Bereinigung (inkl. Volumes)
.\cleanup.ps1 -All -Force

Linux/macOS:

# Interaktive Bereinigung
./cleanup.sh

# Automatische Bereinigung
./cleanup.sh --force

# Vollständige Bereinigung (inkl. Volumes)
./cleanup.sh --all --force

Logs anzeigen

# 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

# 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

# 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

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

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

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

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

Prüfen Sie die Logs: docker-compose logs
Überprüfen Sie die Systemvoraussetzungen
Führen Sie eine Bereinigung durch: ./cleanup.sh --force
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

Fork des Repositories erstellen
Feature-Branch erstellen: git checkout -b feature/neue-funktion
Änderungen committen: git commit -am 'Neue Funktion hinzufügen'
Branch pushen: git push origin feature/neue-funktion
Pull Request erstellen

📄 Lizenz

Dieses Projekt steht unter der MIT-Lizenz. Siehe 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

Entwickelt mit ❤️ für die TBA im Werk 040, Berlin-Marienfelde

12 KiB Executable File Raw Blame History

🖨️ MYP - Manage your Printer

🏗️ Architektur

🔧 Technologie-Stack

🚀 Schnellstart

Voraussetzungen

Installation

📋 Verfügbare Umgebungen

🛠️ Entwicklung (Standard)

🚀 Produktion

🧪 Test

🛠️ Entwicklung

Projektstruktur

Backend-Entwicklung

Frontend-Entwicklung

API-Dokumentation

🔧 Konfiguration

Umgebungsvariablen

Drucker-Konfiguration

TAPO Smart Plug Integration

SSL/TLS-Konfiguration (Produktion)

🧹 Wartung

System bereinigen

Logs anzeigen

Container-Status prüfen

Backup & Restore

🔒 Sicherheit

Produktionsumgebung

Geheimnisse verwalten

🚨 Fehlerbehebung

Häufige Probleme

Support

📈 Performance

Monitoring

Optimierungen

🤝 Beitragen

📄 Lizenz

🙏 Danksagungen

12 KiB

Executable File

Raw Blame History