Mobil_Tag/DEPLOY.md

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)

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

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:

# 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

# 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

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.

cd /var/www/mobile-tag/client
cp .env.example .env

Dann .env bearbeiten:

# 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

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)

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

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

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:

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

sudo nano /etc/apache2/sites-available/mobile-tag.conf

<VirtualHost *:80>
    ServerName dein-domain.de
    DocumentRoot /var/www/html/mobile-tag

    <Directory /var/www/html/mobile-tag>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^ /index.html [L]
</VirtualHost>

Aktivieren:

sudo a2enmod rewrite
sudo a2ensite mobile-tag.conf
sudo systemctl reload apache2

Mit Nginx (empfohlen)

sudo nano /etc/nginx/sites-available/mobile-tag

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:

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

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d dein-domain.de

Mit Apache

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:

sudo ufw allow 'Nginx Full'
sudo ufw allow OpenSSH
sudo ufw enable

Wenn der Node-Server direkt auf Port 3001 erreichbar sein soll

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:

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"

sudo lsof -i :3001
# Prozess-ID merken und beenden:
sudo kill -9 <PID>
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

sudo chown -R $USER:$USER /var/www/mobile-tag

---

Zusammenfassung der wichtigsten Befehle

# 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