KuppelSimulation/JS/README.md

Observatory Simulation 🔭

Eine realistische Observatoriums-Simulation mit NFC-Tag-basierter Kuppelsteuerung, WebSocket-Architektur und smooth Teleskop-Tracking.

Features

• 🔭 Teleskop-Rotation: Automatische 1 U/min CW-Rotation mit manueller Steuerung
• 🏠 Intelligente Kuppel: NFC-Tag-basierte Positionierung mit smooth Bewegung
• 🌐 WebSocket-Architektur: Multi-Task-System mit Real-time-Kommunikation
• 📱 Responsive UI: Modern dark theme mit Touch-Steuerung
• 🎯 360°-Bug-frei: Korrekte Winkeldifferenz-Berechnungen
• 🏷️ 36 NFC-Tags: Alle 10° für realistische Positionserkennung

Docker Deployment 🐳

Quick Start

# Repository klonen
git clone <repository-url>
cd KuppelSimulation/JS

# Mit Docker Compose starten
docker compose up -d

# Simulation öffnen
open http://localhost:3005

Manuelle Docker Commands

# Docker Image bauen
docker build -t observatory-simulation .

# Container starten
docker run -d \\
  --name observatory-sim \\
  -p 3005:3005 \\
  observatory-simulation

# Container Logs anzeigen
docker logs observatory-sim

# Container stoppen
docker stop observatory-sim

Production Setup mit Nginx

# Production Profile aktivieren
docker compose --profile production up -d

# Zugriff über Port 80/443
open http://observatory.local

Development Setup 💻

Lokale Entwicklung

# Dependencies installieren
npm install

# Development Server starten
npm start

# Öffne http://localhost:3005

Verfügbare Befehle

npm start          # Server starten
npm run dev        # Development mode mit auto-reload
npm test           # Tests ausführen  
npm run lint       # Code linting
npm run build      # Production build

System-Architektur 🏗️

┌─────────────────┐    WebSocket    ┌─────────────────┐
│   Telescope     │ ◄──────────────► │      Server     │
│   (Rotation)    │                 │   (Socket.io)   │
└─────────────────┘                 └─────────────────┘
                                            │
┌─────────────────┐    WebSocket            │    WebSocket
│     Dome        │ ◄──────────────────────┼────────────────► ┌─────────────────┐
│  (NFC Tracking) │                        │                  │  Visualization  │
└─────────────────┘                        │                  │   (Canvas)      │
                                           │                  └─────────────────┘
                                           ▼
                                  ┌─────────────────┐
                                  │   Web Browser   │
                                  │  (User Interface)│
                                  └─────────────────┘

Steuerung 🎮

Teleskop

• Automatisch: 6°/sec CW-Rotation (1 U/min)
• +15° Button: Schnelle CW-Bewegung
• +45° Button: Große CW-Bewegung
• -15° Button: Schnelle CCW-Bewegung
• -45° Button: Große CCW-Bewegung

Kuppel (automatisch)

• NFC-Tag-Navigation: 36 Tags alle 10°
• Intelligente Trigger: Bei 6° Teleskop-Abweichung
• Smooth Bewegung: 0.5°/Frame (15°/sec)
• CW-Puffer: Für große Sprünge

Technische Details ⚙️

Docker Features

• Multi-Stage Build: Optimierte Image-Größe
• Non-Root User: Sicherheit durch observatory User
• Health Checks: Automatische Container-Überwachung
• Alpine Linux: Minimale Basis für kleine Images
• Volume Support: Persistente Daten möglich

WebSocket Events

// Teleskop → Server
'telescope-position': { angle: 123.5 }

// Kuppel → Server  
'dome-position': { angle: 145.0, slotWidth: 20 }

// Server → Clients (Broadcast)
'telescope-position': { angle: 123.5 }
'dome-position': { angle: 145.0, slotWidth: 20 }

NFC-Tag-System

// Tag-Berechnung
tagIndex = Math.floor(angle / 10)  // 0-35
tagAngle = tagIndex * 10 + 5       // Mitte des Tags

// Beispiel
angle: 123° → tagIndex: 12 → tagAngle: 125°

Environment Variables 🔧

NODE_ENV=production    # Produktions-Modus
PORT=3005             # Server Port
LOG_LEVEL=info        # Logging Level

Monitoring & Debugging 📊

Container Logs

# Real-time Logs
docker logs -f observatory-sim

# Letzte 100 Zeilen
docker logs --tail 100 observatory-sim

Browser Console

• Teleskop-Positionen: [Telescope] Broadcasting position: X°
• Kuppel-Tracking: [Dome] MOVING: X° → Y°, Dir=CW/CCW
• WebSocket: [Visualization] Received dome position: X°

Health Check

# Container Status prüfen
docker ps

# Health Status
docker inspect --format='{{.State.Health.Status}}' observatory-sim

Production Considerations 🏭

Performance

• Image-Größe: ~50MB (Alpine + Node.js)
• Memory: ~64MB Runtime
• CPU: Minimal (Event-driven)
• Skalierung: Horizontal über Load Balancer

Sicherheit

• Non-Root Container User
• Minimale Attack Surface (Alpine)
• Keine sensitive Daten im Image
• Network Isolation über Docker Networks

Backup

# Container-Export
docker export observatory-sim > observatory-backup.tar

# Volume-Backup (falls verwendet)
docker run --rm -v observatory-data:/data -v $(pwd):/backup alpine tar czf /backup/data-backup.tar.gz /data

Troubleshooting 🔧

Häufige Probleme

Port 3005 bereits belegt:

# Port-Usage prüfen
lsof -i :3005
netstat -tulpn | grep 3005

# Anderen Port verwenden
docker run -p 3006:3005 observatory-simulation

Container startet nicht:

# Detaillierte Logs
docker logs observatory-sim

# Container-Inspektion
docker inspect observatory-sim

WebSocket-Verbindung fehlschlägt:

• Firewall-Einstellungen prüfen
• Browser-Console für JS-Fehler checken
• Network-Tab in DevTools analysieren

---

License

MIT License - Observatory Simulation Project