flutter_tank_web_app/DEPLOYMENT.md

Proxy Server Deployment - Anleitung

📋 Übersicht

Diese Anleitung erklärt, wie Sie den Reverse Proxy Server für PTV API Geocoding deployen. Der Proxy umgeht CORS-Probleme und läuft als eigenständiger Container.

🏗️ Architektur

Browser (Flutter Web App)
    ↓
Proxy Server (localhost:3000 / your-server.com:3000)
    ↓
PTV Geocoding API (api.myptv.com)

🚀 Lokale Entwicklung

1. Proxy Server starten

cd /home/digitalman/Development/flutter_tank_web_app

# Option A: Mit Script
./start-proxy.sh

# Option B: Manuell
cd proxy-server
node server.js

Der Proxy läuft auf http://localhost:3000

2. Flutter App starten

flutter run -d chrome

3. Testen

Geocoding Request:

curl "http://localhost:3000/?lat=47.9385165&lon=13.762887&apiKey=YOUR_API_KEY"

Erwartete Response:

{
  "success": true,
  "location": "Straßenname Hausnummer, PLZ Stadt",
  "coordinates": {
    "lat": 47.9385165,
    "lon": 13.762887
  }
}

Health Check:

curl http://localhost:3000/health
# Response: healthy

🐳 Docker Deployment (Empfohlen)

1. Docker Images bauen

# Interaktives Deployment-Script
./deploy.sh
# Wählen Sie Option 3: "Alles bauen und starten"

# Oder manuell
docker-compose up -d --build

2. Services überprüfen

docker-compose ps

# Erwartete Ausgabe:
# flutter-tank-web   Up   0.0.0.0:8090->80/tcp
# ptv-proxy          Up   0.0.0.0:3000->3000/tcp

3. Logs prüfen

# Proxy Logs
docker-compose logs -f ptv-proxy

# Alle Services
docker-compose logs -f

🌐 Produktion - Auf Server deployen

Schritt 1: Server vorbereiten

SSH zum Server:

ssh user@your-server.com

Docker installieren (falls nicht vorhanden):

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Schritt 2: Code auf Server kopieren

Option A: Git

git clone https://github.com/your-repo/flutter_tank_web_app.git
cd flutter_tank_web_app

Option B: SCP/Rsync

# Von lokalem Rechner
rsync -avz --exclude 'build' --exclude '.dart_tool' \
  . user@your-server.com:/opt/flutter-tank-app/

Schritt 3: Proxy URL konfigurieren

Bearbeiten Sie lib/config/environment.dart:

class Environment {
  // Produktions-URL des Proxy Servers
  static const String localProxyUrl = 'http://your-server.com:3000';
  static const bool useLocalProxy = true;
  
  // ... rest bleibt gleich
}

Schritt 4: Neu builden und deployen

cd /opt/flutter-tank-app
./deploy.sh
# Option 3: "Alles bauen und starten"

Schritt 5: Firewall konfigurieren

# Port 8090 (Web App) und 3000 (Proxy) öffnen
sudo ufw allow 8090/tcp
sudo ufw allow 3000/tcp
sudo ufw enable

🔒 Sichere Konfiguration mit Nginx (Empfohlen)

Statt Port 3000 direkt zu exponieren, verwenden Sie Nginx als Reverse Proxy:

1. Nginx konfigurieren

sudo nano /etc/nginx/sites-available/tank.yourdomain.com

server {
    listen 80;
    server_name tank.yourdomain.com;

    # Flutter Web App
    location / {
        proxy_pass http://localhost:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Proxy Server (API Endpoint)
    location /api/geocode {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # CORS Headers werden vom Proxy Server gesetzt
        proxy_hide_header Access-Control-Allow-Origin;
    }
}

2. Site aktivieren

sudo ln -s /etc/nginx/sites-available/tanknew.joshihomeserver.ipv64.net /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

3. SSL Zertifikat (Let's Encrypt)

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d tanknew.joshihomeserver.ipv64.net

4. Environment anpassen

static const String localProxyUrl = 'https://tanknew.joshihomeserver.ipv64.net/api/geocode';

5. Firewall anpassen

# Nur 80 und 443 öffnen (nicht 3000)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw deny 3000/tcp  # Proxy nur über Nginx erreichbar

🔧 Troubleshooting

Proxy Server startet nicht

Logs prüfen:

docker-compose logs ptv-proxy

Häufige Probleme:

• Port 3000 bereits belegt: sudo lsof -i :3000
• Node.js nicht installiert: node --version

CORS-Fehler trotz Proxy

Prüfen:

1. Ist der Proxy erreichbar? curl http://localhost:3000/health
2. Richtige URL in environment.dart?
3. Browser Cache leeren und App neu laden

"Connection refused"

Lösung:

# Docker Container laufen?
docker-compose ps

# Proxy neu starten
docker-compose restart ptv-proxy

PTV API gibt 401 zurück

Problem: Ungültiger API Key
Lösung: API Key in environment.dart überprüfen

Im Container: "npm not found"

Problem: Lokales node_modules committet
Lösung:

# .dockerignore prüfen
cat .dockerignore | grep node_modules

# Sollte vorhanden sein

📊 Monitoring

Service Status

# Docker
docker-compose ps

# System Resources
docker stats

# Health Check
curl http://localhost:3000/health

Logs Live anschauen

# Proxy
docker-compose logs -f ptv-proxy

# Alle Services
docker-compose logs -f --tail=100

🔄 Updates deployen

# Code aktualisieren
git pull

# Container neu bauen und starten
docker-compose up -d --build

# Alte Images aufräumen
docker image prune -f

✅ Erfolgskriterien

Nach erfolgreichem Deployment sollten Sie:

• ✅ Proxy Health Check erfolgreich: curl http://tanknew.joshihomeserver.ipv64.net:3000/health
• ✅ Geocoding funktioniert in der App
• ✅ Browser Console zeigt: "🔄 Verwende lokalen Proxy..."
• ✅ Browser Console zeigt: "✅ Geocoding erfolgreich (Proxy): [Adresse]"
• ✅ Keine CORS-Fehler mehr

📝 Produktions-Checkliste

• Docker und Docker Compose installiert
• Code auf Server übertragen
• localProxyUrl in environment.dart angepasst
• Docker Containers laufen (docker-compose ps)
• Firewall konfiguriert
• Nginx Reverse Proxy eingerichtet (empfohlen)
• SSL Zertifikat installiert
• Health Checks erfolgreich
• Geocoding in App getestet