Lokale Entwicklung

Betreibe eine vollständige Hoppla-Instanz lokal auf einem Laptop — ohne Kubernetes, ohne Cluster — damit deine Entwickler Integrationen bauen, White-Label-Branding testen oder das Produkt erkunden können. Es laufen dieselben vorgefertigten Images wie in Produktion (nichts wird aus dem Quellcode gebaut), hinter einem kleinen Reverse-Proxy, sodass Dashboard, API, Session-Cookies und Echtzeit-Updates gemeinsam auf einer http://localhost-Origin funktionieren.

Das ist eine Entwicklungsinstanz

Sie läuft mit einer einzigen Datenbankrolle (die PostgreSQL-Row-Level-Security wird lokal umgangen — die Mandanten-Trennung auf Anwendungsebene greift weiterhin), lockert Captcha- und Secure-Cookie-Anforderungen für http://localhost und liefert einen geteilten Wegwerf-APP_KEY mit. Niemals in Produktion verwenden. Für Produktion nutzt du install.sh und das Helm-Chart.

Was du brauchst

• Docker mit Compose v2 (docker compose version)
• Deine Registry-Zugangsdaten und eine Entwicklungslizenz aus deinem Welcome-Pack

Das Bundle liegt im Distributions-Repository unter dist/selfhosted/local/. Es enthält eine docker-compose.yml, eine einsatzbereite .env.example, eine config.js und ein Caddyfile.

Die Entwicklungslizenz besorgen

Die Entwicklungslizenz wird wie jede andere in der Hoppla-Admin-Konsole ausgestellt, mit einem Unterschied: ihre Umgebung ist development — und damit domain-ungebunden. Sie trägt keine gebundenen Domains und erzeugt keine Bindungswarnung, läuft also auf jedem Host deiner Entwickler (localhost, eine geteilte Dev-Box, CI). Bitte deinen Hoppla-Kontakt, eine development-Lizenz ins Welcome-Pack aufzunehmen (ein Pack kann Produktions-, Staging-, Testing- und Entwicklungslizenzen zusammen bündeln).

Starten

cd dist/selfhosted/local

# 1. Konfiguration — die Defaults passen für lokale Entwicklung.
cp .env.example .env

# 2. Docker einmalig an der Registry anmelden — mit dem klassischen
#    read:packages-Token aus deinem Welcome-Pack.
echo "<DEIN_GHCR_TOKEN>" | docker login ghcr.io -u "<DEIN_GITHUB_USERNAME>" --password-stdin

# 3. Lizenz ablegen.
cp /pfad/zu/hoppla.license ./license/hoppla.license

# 4. Stack starten (lädt die Images beim ersten Mal).
docker compose up -d

# 5. Ersten Admin + Organisation anlegen (idempotent).
docker compose exec api php artisan hoppla:install

Öffne http://localhost und melde dich an. Ausgehende E-Mails fängt Mailpit unter http://localhost:8025 ab — es verlässt keine echte Mail den Rechner.

Lizenz und Zustand jederzeit prüfen:

docker compose exec api php artisan license:inspect
docker compose exec api php artisan hoppla:doctor

Lizenz einbinden

Die Anwendung liest ihre Lizenz aus einer von zwei Quellen (siehe Konfiguration):

• Aus einer Datei — HOPPLA_LICENSE_PATH (Standard /var/hoppla/license/hoppla.license). Das lokale Bundle mountet ./license/hoppla.license dorthin.
• Inline — HOPPLA_LICENSE auf den vollständigen armored Lizenztext gesetzt (der -----BEGIN HOPPLA LICENSE----- … -----END…-Block). Praktisch, wenn ein Datei-Mount unpraktisch ist, z. B. in CI oder einer gehosteten Dev-Umgebung.

Setzt du HOPPLA_LICENSE, kannst du den Datei-Mount ganz weglassen.

Rebrand lokal testen

White-Label-Branding — Markenname, Farben, Logo, Login-Seite, Portal-Domains — konfigurierst du innerhalb der App, sobald du angemeldet bist, und es wird auf dieser lokalen Instanz genau so dargestellt wie in Produktion. Damit ist lokal der richtige Ort, um einen Reseller-Rebrand zu bauen und zu testen, bevor er live geht. Siehe White-Label für die vollständige Anleitung.

Aktualisieren

Erhöhe HOPPLA_VERSION in .env (die aktuelle Version findest du in VERSIONS.md im Distributions-Repository), dann:

docker compose pull
docker compose up -d   # Schema-Migrationen laufen beim Hochfahren automatisch

Fehlerbehebung

Symptom	Lösung
Images lassen sich nicht laden (denied / unauthorized)	docker login ghcr.io … mit einem klassischen read:packages-Token wiederholen — fein-granulare Tokens authentifizieren sich nicht an GHCR.
http://localhost zeigt nichts / Port 80 belegt	HTTP_PORT in .env auf einen freien Port setzen (z. B. 8080) und diesen öffnen. Echtzeit-Updates (Websocket) setzen den Standard-Port voraus; alles andere läuft auf jedem Port.
„No license configured"	Prüfen, dass ./license/hoppla.license existiert, dann docker compose restart api worker scheduler.
Login abgelehnt / Captcha-Fehler	Sicherstellen, dass .env APP_ENV=local und TURNSTILE_REQUIRED=false behält (die Defaults).
Checks laufen nie	Die Dienste scheduler und worker müssen laufen (docker compose ps) — sie brauchen die Lizenz ebenfalls gemountet.

Um alles zu löschen und neu zu starten: docker compose down -v (löscht das Datenbank-Volume).