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

# 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

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

Umgebungsvariablen (.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

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

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

# Sollte zu 127.0.0.1 auflösen
ping assets.pr-copilot.test
ping assets-web.pr-copilot.test

2. Vite-Server starten

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:

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

   # 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! 🚀