commit 9db3812cf8dfd1dc8d50df287e7220a0696ce14c Author: topsith Date: Wed Aug 5 20:29:18 2026 +0200 Initial commit: Mobil_Tag project setup diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..209f5a2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,41 @@ +# Dependencies +node_modules/ +*/node_modules/ + +# Build outputs +dist/ +build/ +*/dist/ +*/build/ + +# Environment variables (but keep .env.example) +.env +.env.local +.env.*.local +!.env.example + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db + +# Logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# Testing +coverage/ + +# TypeScript +*.tsbuildinfo + +# Misc +.cache/ \ No newline at end of file diff --git a/DEPLOY.md b/DEPLOY.md new file mode 100644 index 0000000..72e58f7 --- /dev/null +++ b/DEPLOY.md @@ -0,0 +1,395 @@ +# Deployment-Anleitung: Mobile Tag auf Ubuntu-Server + +Diese Anleitung beschreibt, wie du das Mobile Tag Projekt auf deinen bestehenden Ubuntu-Webserver mit PHP bringst. Das Backend benötigt Node.js (siehe `UBUNTU_SETUP.md`), das Frontend ist eine statische PWA. + +--- + +## Übersicht + +| Komponente | Technologie | Pfad auf Server | Auslieferung | +|---|---|---|---| +| Backend | Node.js + Socket.io | `/var/www/mobile-tag/server/dist` | PM2 auf Port 3001 | +| Frontend (PWA) | Vite-Build | `/var/www/mobile-tag/client/dist` | Apache oder Nginx | +| WebSocket | Socket.io | `:3001` | Nginx Reverse Proxy (empfohlen) | + +--- + +## Voraussetzungen + +- Ubuntu-Server mit SSH-Zugriff +- Node.js ≥ 18 installiert (`node -v` und `npm -v` prüfen) +- Apache oder Nginx als Webserver +- Domain oder Server-IP +- Ports 80, 443 und optional 3001 freigegeben + +--- + +## Schritt 1: Projekt auf den Server kopieren + +### Vom Windows-Rechner (mit Git Bash, WSL oder PowerShell) + +```bash +# Mit scp (Pfad anpassen!) +scp -r "c:/Users/thebi/OneDrive/KI Projekte/Mobil_Tag" root@dein-server:/var/www/mobile-tag +``` + +### Alternativ als ZIP + +1. Auf dem Windows-Rechner den `Mobil_Tag`-Ordner als ZIP packen +2. ZIP per FTP/SFTP in `/var/www/` hochladen +3. Auf dem Server entpacken: + +```bash +cd /var/www +sudo apt install unzip -y +sudo unzip mobile-tag.zip +sudo mv Mobil_Tag mobile-tag +``` + +**Wichtig:** Falls du schon einmal `npm install` lokal gemacht hast, lösche vor dem Kopieren die Ordner `node_modules`: + +```bash +# Auf Windows, bevor du kopierst: +Remove-Item -Recurse -Force "c:/Users/thebi/OneDrive/KI Projekte/Mobil_Tag/node_modules" +Remove-Item -Recurse -Force "c:/Users/thebi/OneDrive/KI Projekte/Mobil_Tag/client/node_modules" +Remove-Item -Recurse -Force "c:/Users/thebi/OneDrive/KI Projekte/Mobil_Tag/server/node_modules" +``` + +--- + +## Schritt 2: Server vorbereiten + +```bash +# Ins Projektverzeichnis wechseln +cd /var/www/mobile-tag + +# Rechte setzen (falls nötig) +sudo chown -R www-data:www-data /var/www/mobile-tag +sudo chmod -R 755 /var/www/mobile-tag + +# Node-Version prüfen +node -v # Sollte v20.x oder höher anzeigen +npm -v +``` + +--- + +## Schritt 3: Abhängigkeiten installieren + +```bash +cd /var/www/mobile-tag +npm run install:all +``` + +Das installiert automatisch: +- Root-Abhängigkeiten (`concurrently`) +- Client-Abhängigkeiten (React, Vite, TensorFlow.js, Tailwind, ...) +- Server-Abhängigkeiten (Express, Socket.io, ...) + +--- + +## Schritt 4: Server-URL konfigurieren + +Der Client muss wissen, wo das Backend läuft. + +```bash +cd /var/www/mobile-tag/client +cp .env.example .env +``` + +Dann `.env` bearbeiten: + +```bash +# Variante A: Backend läuft auf eigener Subdomain (empfohlen mit Nginx) +VITE_SERVER_URL=https://api.dein-domain.de + +# Variante B: Backend läuft direkt auf Port 3001 +VITE_SERVER_URL=http://dein-server-ip:3001 + +# Variante C: Beides auf derselben Domain mit Nginx Reverse Proxy +VITE_SERVER_URL=https://dein-domain.de +``` + +**Wichtig:** Wenn du HTTPS nutzt, muss auch `VITE_SERVER_URL` mit `https://` beginnen. + +--- + +## Schritt 5: Projekt bauen + +```bash +cd /var/www/mobile-tag +npm run build +``` + +Ergebnis: +- `server/dist/` – kompilierter Node.js-Server +- `client/dist/` – fertige PWA-Dateien + +--- + +## Schritt 6: Backend starten + +### Variante A: Mit PM2 (empfohlen für Produktion) + +```bash +# PM2 global installieren +sudo npm install -g pm2 + +# Server als Dienst starten +cd /var/www/mobile-tag/server +pm2 start dist/index.js --name mobile-tag-server + +# PM2 so einrichten, dass es nach Neustart automatisch startet +pm2 save +pm2 startup +# → Den angezeigten Befehl kopieren und ausführen (meist mit sudo) +``` + +**Nützliche PM2-Befehle:** + +```bash +pm2 status # Status anzeigen +pm2 logs mobile-tag-server # Logs anzeigen +pm2 restart mobile-tag-server +pm2 stop mobile-tag-server +pm2 delete mobile-tag-server +``` + +### Variante B: Einfacher Test ohne PM2 + +```bash +cd /var/www/mobile-tag/server +npm start +``` + +Läuft dann solange das Terminal offen ist. + +--- + +## Schritt 7: Frontend ausliefern + +### Mit Apache + +1. `client/dist/` in dein Webverzeichnis kopieren: + +```bash +sudo mkdir -p /var/www/html/mobile-tag +sudo cp -r /var/www/mobile-tag/client/dist/* /var/www/html/mobile-tag/ +``` + +2. Falls nötig, Apache konfigurieren (Single-Page-App-Routing): + +```bash +sudo nano /etc/apache2/sites-available/mobile-tag.conf +``` + +```apache + + ServerName dein-domain.de + DocumentRoot /var/www/html/mobile-tag + + + Options -Indexes +FollowSymLinks + AllowOverride All + Require all granted + + + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^ /index.html [L] + +``` + +Aktivieren: + +```bash +sudo a2enmod rewrite +sudo a2ensite mobile-tag.conf +sudo systemctl reload apache2 +``` + +### Mit Nginx (empfohlen) + +```bash +sudo nano /etc/nginx/sites-available/mobile-tag +``` + +```nginx +server { + listen 80; + server_name dein-domain.de; + root /var/www/html/mobile-tag; + index index.html; + + location / { + try_files $uri $uri/ /index.html; + } + + # WebSocket-Verkehr an Node.js weiterleiten + location /socket.io/ { + proxy_pass http://localhost:3001; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_cache_bypass $http_upgrade; + } +} +``` + +Aktivieren: + +```bash +sudo ln -s /etc/nginx/sites-available/mobile-tag /etc/nginx/sites-enabled/ +sudo nginx -t +sudo systemctl reload nginx +``` + +**Hinweis:** Wenn du Apache statt Nginx verwendest und den Node-Server direkt auf Port 3001 erreichbar machen willst, musst du Port 3001 in der Firewall freigeben (siehe Schritt 9). + +--- + +## Schritt 8: HTTPS mit Let's Encrypt einrichten + +Dieser Schritt ist **zwingend erforderlich**, da Kamera, GPS und Orientierung in Browsern nur mit HTTPS funktionieren. + +### Mit Nginx + +```bash +sudo apt install certbot python3-certbot-nginx -y +sudo certbot --nginx -d dein-domain.de +``` + +### Mit Apache + +```bash +sudo apt install certbot python3-certbot-apache -y +sudo certbot --apache -d dein-domain.de +``` + +Danach ist die App unter `https://dein-domain.de` erreichbar. + +--- + +## Schritt 9: Firewall konfigurieren + +### Wenn Nginx als Reverse Proxy verwendet wird + +Port 3001 muss **nicht** öffentlich erreichbar sein, da Nginx intern weiterleitet: + +```bash +sudo ufw allow 'Nginx Full' +sudo ufw allow OpenSSH +sudo ufw enable +``` + +### Wenn der Node-Server direkt auf Port 3001 erreichbar sein soll + +```bash +sudo ufw allow 3001/tcp +sudo ufw allow 'Apache Full' # oder 'Nginx Full' +sudo ufw allow OpenSSH +sudo ufw enable +``` + +--- + +## Schritt 10: App testen + +1. Öffne im Handy-Browser: `https://dein-domain.de` +2. Erlaube Kamera, Standort und Orientierung. +3. Erstelle einen Raum und teile den Code. +4. Ein zweiter Spieler tritt dem Raum bei. +5. Host startet das Spiel. + +--- + +## Updates einspielen + +Wenn du Änderungen am Code machst: + +```bash +cd /var/www/mobile-tag + +# Neue Dateien vom lokalen Rechner auf den Server kopieren (Schritt 1 wiederholen) + +# Dann auf dem Server: +npm run install:all +npm run build +pm2 restart mobile-tag-server + +# Bei Apache: +sudo cp -r /var/www/mobile-tag/client/dist/* /var/www/html/mobile-tag/ + +# Bei Nginx (falls DocumentRoot direkt auf /var/www/mobile-tag/client/dist zeigt, nicht nötig): +sudo cp -r /var/www/mobile-tag/client/dist/* /var/www/html/mobile-tag/ +``` + +--- + +## Fehlerbehebung + +### „npm: Befehl nicht gefunden" + +Node.js ist nicht installiert oder nicht im PATH. Siehe `UBUNTU_SETUP.md`. + +### „Port 3001 bereits belegt" + +```bash +sudo lsof -i :3001 +# Prozess-ID merken und beenden: +sudo kill -9 +pm2 restart mobile-tag-server +``` + +### „WebSocket-Verbindung fehlgeschlagen" + +- Prüfe, ob der Server läuft: `pm2 status` +- Prüfe die Firewall: `sudo ufw status` +- Prüfe, ob `VITE_SERVER_URL` korrekt ist +- Prüfe die Nginx-Konfiguration auf das `/socket.io/`-Location-Block + +### „Kamera/GPS funktioniert nicht" + +- HTTPS erforderlich! +- Browser-Berechtigungen prüfen +- Auf iOS: nur Safari unterstützt DeviceOrientation vollständig + +### „Permission denied" beim Kopieren + +```bash +sudo chown -R $USER:$USER /var/www/mobile-tag +``` + +--- + +## Zusammenfassung der wichtigsten Befehle + +```bash +# Nach dem Kopieren auf den Server: +cd /var/www/mobile-tag +npm run install:all +npm run build + +cd client +cp .env.example .env +# .env bearbeiten: VITE_SERVER_URL anpassen + +cd /var/www/mobile-tag +npm run build + +cd server +pm2 start dist/index.js --name mobile-tag-server +pm2 save +pm2 startup + +# Nginx-Konfiguration anlegen und HTTPS einrichten +``` + +--- + +*Stand: 26.07.2026* diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..8e6ec97 --- /dev/null +++ b/PLAN.md @@ -0,0 +1,292 @@ +# Mobile Tag – Projektplan + +GPS-basiertes Outdoor-Lasertag für jedes Smartphone als Progressive Web App (PWA). + +--- + +## 1. Konzept & Spielprinzip + +- **Plattform:** Webanwendung (PWA), installierbar auf iOS/Android, keine App-Store-Downloads nötig. +- **Spielort:** Überall im Freien. Das Spielfeld wird vor dem Match definiert. +- **Treffermodell:** Hybrid aus GPS/Kompass (Grob-Check) und Kamera-Computer-Vision (Fein-Check). + - GPS + Kompass prüfen, ob ein Gegner in Reichweite und Blickrichtung liegt. + - Die Kamera zeigt ein Fadenkreuz über dem Live-Bild. + - TensorFlow.js (MoveNet) erkennt Körperteile. Das Fadenkreuz entscheidet über Kopf, Brust, Arm oder Bein. + - Jeder Körperteil verursacht unterschiedlichen Schaden. +- **Nachlade-Mechanik:** Kein Dauerfeuer. Cooldown einstellbar, Standard ~3 s. +- **Spielmodi:** Free-for-All und Teams. +- **Spieleranzahl:** 2–10 Spieler pro Match (MVP). + +--- + +## 2. Architektur + +``` +┌─────────────────┐ ┌──────────────────────┐ +│ Client PWA │◄───────►│ Node.js Game Server │ +│ React + Vite │ WebSocket│ Express + Socket.io │ +└─────────────────┘ └──────────────────────┘ + │ + ▼ + Handy-Sensoren: + - GPS (Geolocation API) + - Kompass (DeviceOrientationEvent) + - Kamera (getUserMedia) + - TensorFlow.js MoveNet (Pose Estimation) +``` + +--- + +## 3. Tech-Stack + +| Schicht | Technologie | +|---|---| +| Frontend | React 18 + Vite + TypeScript | +| PWA | `vite-plugin-pwa` (Workbox) | +| Styling | Tailwind CSS | +| Geo-Logik | Turf.js | +| Kamera | `getUserMedia` + `