presseportale/ASSET-URLS-GUIDE.md

# Asset-URLs für Multi-Domain Vite-Setup

## Empfohlene Asset-URLs

Für dein Multi-Domain-Setup empfehle ich folgende Asset-URLs:

### ✅ Aktuelle Konfiguration (EMPFOHLEN)

| Bereich | Domain | Asset-URL | Port | Verwendung |
|---------|--------|-----------|------|------------|
| **Backend** | pr-copilot.test | `assets.pr-copilot.test` | 5177 | Portal + FluxUI |
| **Frontend** | presseecho.test<br>businessportal24.test | `assets-web.pr-copilot.test` | 5178 | Beide Frontend-Domains |

### Warum diese URLs?

#### 1. **assets.pr-copilot.test** (Portal/Backend)
- ✅ Kurz und prägnant
- ✅ Eindeutig dem Portal zugeordnet
- ✅ Keine zusätzliche Subdomain-Tiefe
- ✅ Folgt gängiger Konvention

#### 2. **assets-web.pr-copilot.test** (Web/Frontend)
- ✅ Klar als "Web" (Frontend) gekennzeichnet
- ✅ Ein Asset-Server für beide Frontend-Domains
- ✅ Gute Trennung zu Portal-Assets
- ✅ Einfach zu merken

## Alternative Namenskonventionen

Falls du andere URLs bevorzugst, hier sind Alternativen:

### Option A: Mit Suffix-Präfix
```
portal-assets.pr-copilot.test  → Port 5177
web-assets.pr-copilot.test     → Port 5178
```
- ⚠️ Etwas länger
- ✅ Sehr explizit

### Option B: Mit "vite" im Namen
```
vite.pr-copilot.test          → Port 5177
vite-web.pr-copilot.test      → Port 5178
```
- ⚠️ Technologie-spezifisch (was wenn du später zu einem anderen Build-Tool wechselst?)
- ⚠️ Weniger klar was geladen wird

### Option C: Separate Domains pro Frontend
```
assets.pr-copilot.test           → Port 5177 (Portal)
assets.presseecho.test           → Port 5178 (Presseecho)
assets.businessportal24.test     → Port 5178 (Businessportal24)
```
- ⚠️ Mehr DNS-Einträge nötig
- ⚠️ Beide Frontend-Domains würden trotzdem auf denselben Port zeigen
- ❌ Unnötig komplex

### ✅ Empfehlung: Bleib bei der aktuellen Lösung!

## Traefik-Konfiguration (aktuell in docker-compose.yml)

```yaml
# Portal Assets (Backend)
- "traefik.http.routers.assets-portal.rule=Host(`assets.pr-copilot.test`)"
- "traefik.http.routers.assets-portal.entrypoints=websecure"
- "traefik.http.routers.assets-portal.tls=true"
- "traefik.http.routers.assets-portal.service=assets-portal-service"
- "traefik.http.services.assets-portal-service.loadbalancer.server.port=5177"
- "traefik.http.services.assets-portal-service.loadbalancer.server.scheme=http"

# Web Assets (Frontend)
- "traefik.http.routers.assets-web.rule=Host(`assets-web.pr-copilot.test`)"
- "traefik.http.routers.assets-web.entrypoints=websecure"
- "traefik.http.routers.assets-web.tls=true"
- "traefik.http.routers.assets-web.service=assets-web-service"
- "traefik.http.services.assets-web-service.loadbalancer.server.port=5178"
- "traefik.http.services.assets-web-service.loadbalancer.server.scheme=http"
```

## Port-Mapping in docker-compose.yml

```yaml
ports:
    - '${VITE_PORT_PORTAL:-5177}:5177'
    - '${VITE_PORT_WEB:-5178}:5178'
```

## Umgebungsvariablen (.env)

```env
# Vite Asset Domains
ASSET_URL_PORTAL=https://assets.pr-copilot.test
ASSET_URL_WEB=https://assets-web.pr-copilot.test

# Vite Development Ports
VITE_PORT_PORTAL=5177
VITE_PORT_WEB=5178
```

## DNS / Hosts-Datei

Füge folgende Einträge zu deiner `/etc/hosts` (Linux/Mac) oder `C:\Windows\System32\drivers\etc\hosts` (Windows) hinzu:

```
127.0.0.1 pr-copilot.test
127.0.0.1 presseecho.test
127.0.0.1 businessportal24.test
127.0.0.1 assets.pr-copilot.test
127.0.0.1 assets-web.pr-copilot.test
```

## Vite-Konfigurationen

### vite.portal.config.js
```javascript
export default defineConfig({
    // ...
    server: {
        https: false,
        cors: true,
        host: "0.0.0.0",
        port: 5177,
        hmr: {
            host: "assets.pr-copilot.test",  // ← Asset-URL
            protocol: "wss",
        },
    },
    // ...
});
```

### vite.web.config.js
```javascript
export default defineConfig({
    // ...
    server: {
        https: false,
        cors: true,
        host: "0.0.0.0",
        port: 5178,
        hmr: {
            host: "assets-web.pr-copilot.test",  // ← Asset-URL
            protocol: "wss",
        },
    },
    // ...
});
```

## Wie funktioniert das Routing?

```
Browser-Request
    ↓
1. User besucht: https://presseecho.test
    ↓
2. Laravel lädt View mit: @vite(['resources/css/web/theme-presseecho.css', ...])
    ↓
3. Vite-Helper generiert: <script src="https://assets-web.pr-copilot.test/@vite/client"></script>
                          <link href="https://assets-web.pr-copilot.test/resources/css/web/theme-presseecho.css">
    ↓
4. Browser requested: assets-web.pr-copilot.test
    ↓
5. Traefik routet zu: Container Port 5178
    ↓
6. Vite Web Server antwortet
    ↓
7. HMR WebSocket öffnet: wss://assets-web.pr-copilot.test
    ↓
8. ✅ Hot Module Replacement funktioniert!
```

## Testing

### 1. DNS-Auflösung testen
```bash
# Sollte zu 127.0.0.1 auflösen
ping assets.pr-copilot.test
ping assets-web.pr-copilot.test
```

### 2. Vite-Server starten
```bash
npm run dev:all
```

Du solltest sehen:
```
[PORTAL] VITE v6.0.x ready in xxx ms
[PORTAL] ➜  Local:   http://0.0.0.0:5177/
[PORTAL] ➜  Network: use --host to expose
[WEB]    VITE v6.0.x ready in xxx ms
[WEB]    ➜  Local:   http://0.0.0.0:5178/
```

### 3. Browser-Test
Öffne:
- https://pr-copilot.test (sollte Assets von assets.pr-copilot.test laden)
- https://presseecho.test (sollte Assets von assets-web.pr-copilot.test laden)
- https://businessportal24.test (sollte Assets von assets-web.pr-copilot.test laden)

### 4. HMR-Test
1. Öffne Browser DevTools (F12)
2. Gehe zu "Network" Tab
3. Filter auf "WS" (WebSocket)
4. Du solltest Verbindungen zu `wss://assets.*.pr-copilot.test` sehen
5. Ändere eine CSS-Datei
6. Browser sollte automatisch neu laden (ohne vollständigen Page-Refresh)

## Troubleshooting

### Assets werden nicht geladen

**Problem:** Assets 404 oder laden nicht

**Lösung:**
```bash
# 1. Vite-Server läuft?
npm run dev:all

# 2. Ports erreichbar?
curl http://localhost:5177
curl http://localhost:5178

# 3. Traefik routet korrekt?
docker compose logs laravel.test | grep traefik
```

### HMR funktioniert nicht

**Problem:** Hot Module Replacement lädt nicht automatisch neu

**Lösung:**
1. Browser-Console checken (F12 → Console)
2. WebSocket-Verbindung prüfen (F12 → Network → WS)
3. Falls "WebSocket connection failed":
   ```bash
   # Traefik-Logs checken
   docker compose logs laravel.test
   
   # Vite-Server neu starten
   npm run dev:all
   ```

### "Mixed Content"-Fehler

**Problem:** Browser blockiert HTTP-Assets auf HTTPS-Site

**Lösung:**
- Stelle sicher, dass HMR mit `wss://` (nicht `ws://`) läuft
- Prüfe `protocol: "wss"` in Vite-Configs
- Traefik sollte SSL für Asset-Domains bereitstellen

## Zusammenfassung

### ✅ Verwende diese Asset-URLs:

```
assets.pr-copilot.test       → Port 5177 (Portal/Backend)
assets-web.pr-copilot.test   → Port 5178 (Web/Frontend)
```

### ✅ Vorteile:
- Kurz und prägnant
- Klare Trennung Backend/Frontend
- Ein Asset-Server für beide Frontend-Domains
- Einfach zu merken und zu konfigurieren
- Folgt Best Practices

### ✅ Bereits konfiguriert in:
- ✅ docker-compose.yml (Traefik-Labels + Port-Mapping)
- ✅ vite.portal.config.js (HMR-Host)
- ✅ vite.web.config.js (HMR-Host)
- ✅ .env.example (Variablen-Vorlage)

**Du bist ready to go! 🚀**