CaddyApp

CaddyApp ist eine macOS-Desktop-App (SwiftUI) zur lokalen Verwaltung von Caddy. Der Schwerpunkt liegt auf *.localhost-Reverse-Proxy-Workflows, automatisierter Caddy-Konfiguration und On-Demand-App-Routing.

Ziel des Projekts

• Caddy auf macOS einfach installieren, aktualisieren und steuern.
• Lokale Reverse-Proxies fuer Entwicklungs- und Test-Setups verwalten.
• AutoTLS (tls internal) inkl. Root-CA-Trust-Flow nutzbar machen.
• Multipass-/Podman-Workloads erkennen und als Routen integrieren.
• On-Demand-Apps per URL starten und bei Inaktivitaet wieder stoppen.

Funktionsumfang

• SwiftUI-App mit task-orientierter Hauptnavigation und Menubar/Systray-Integration
• Liquid-inspirierte App-Shell mit transparenter Sidebar, Header-Chips und glasartigen Panel-Flaechen
• App-Settings via macOS-Standard Apple-, sowie globales App-Menue (CaddyApp)
• Konfigurationsverwaltung als zentrale AppConfig in den CaddyApp Settings
• Automatischer GH-Pages-Feed-Sync fuer On-Demand-Presets
• Caddy-Erkennung inkl. Install-/Update-Flow
  • Homebrew zuerst
  • Fallback auf app-verwaltetes Binary unter ~/Library/Application Support/CaddyApp/bin/caddy
• Caddy-Release-Monitoring (GitHub API)
• Generierte Caddy-Konfiguration fuer Host-Routen auf *.localhost
• Optional zuschaltbare *.traefik.me-Alias-Hosts pro *.localhost-Route
• Auto-Persistenz + Auto-Validate + Auto-Reload bei gueltigen Aenderungen
• Caddy-Runtime-Steuerung (Start/Stop/Reload) inkl. Fallback-Start
• Auto-Reparatur fuer Homebrew-Service, wenn /opt/homebrew/etc/Caddyfile fehlt (inkl. Service-Restart)
• Auto-Konsolidierung mehrerer laufender Caddy-Prozesse auf eine Instanz (bevorzugt Homebrew-Service)
• Privilegierte Aktionen ueber macOS-Admin-Dialog (kein versteckter Passwortprompt)
• Root-CA-Erkennung und Trust-Unterstuetzung fuer lokale Zertifikate
• Multipass-Service-Erkennung und -Steuerung (Start/Stop/force-stop)
• Multipass-Import aus /etc/caddy-app.yaml
• YAML-basierte Web-Repositories fuer On-Demand-App-Presets
• Gemeinsamer interner Scheduler fuer Polling-, Debounce- und Maintenance-Jobs
• Asynchrone Command-Ausfuehrung fuer UI-relevante Aktionen (Caddy/TLS/Update/Logs)
• Monitoring-Logs mit Tail-Viewport, Live-Append und bedarfsgesteuertem Nachladen aelterer Zeilen fuer bessere UI-Performance
• Exponentielles Retry-Backoff fuer wiederkehrende Runtime-Shell-Checks (max. 30s) inkl. Dashboard-Hinweisen bei Podman-/Docker-/Multipass-Problemen
• Skeleton-Loading fuer Hauptzustand und Inline-Loading-Indikatoren statt Spinner-Fokus

Voraussetzungen

• macOS 14 oder neuer
• Swift 6.x (SwiftPM)
• Optional:
  • Homebrew (fuer bevorzugte Caddy-Installation)
  • Multipass / Podman (fuer Runtime-Discovery-Features)

Schnellstart

make build
make open-app

Alternativ direkt starten:

make run

Build und Entwicklung

Wichtige Make-Targets:

make help      # Targets anzeigen
make build     # Debug-Build + .app-Bundle
make release   # Release-Build + .app-Bundle
make production # Universal Production-Build + ZIP
make dmg       # DMG mit Hintergrundbild + Programme-Link
make run       # App ueber SwiftPM starten
make test      # Tests ausfuehren
make check     # build + test
make docs      # Astro-Dokumentation bauen
make docs-dev  # Astro-Dokumentation lokal starten
make docs-list # Feature-Dokumente auflisten

Build-Artefakte:

• Debug: _build/debug/CaddyApp.app
• Release: _build/release/CaddyApp.app
• Production: _build/production/CaddyApp.app
• Production ZIP: _build/production/CaddyApp.zip
• DMG: _build/production/CaddyApp.dmg

Projektstruktur

• Sources/CaddyApp/Views/AppShell/ - Hauptfenster-Shell mit NavigationSplitView, Sidebar und Main-Layout
• Sources/CaddyApp/Views/Tabs/ - task-orientierte Arbeitsbereiche (Uebersicht/Setup/Routing/Services/Apps/Monitoring)
• Sources/CaddyApp/Views/Settings/ - Settings-Root + Pane-Views
• Sources/CaddyApp/Views/OnDemand/ - On-Demand-Feature-Komponenten
• Sources/CaddyApp/Views/Shared/ - Wiederverwendbare UI-Bausteine
• Sources/CaddyApp/ViewModels/ - UI-State und Orchestrierung
• Sources/CaddyApp/ViewModels/Features/ - Feature-spezifische ViewModels
• Sources/CaddyApp/Services/ - Caddy-, Runtime- und Systemintegration
• Sources/CaddyApp/Models/ - Domain-Modelle (one-type-per-file)
  • Models/Config/, Models/Routing/, Models/OnDemand/, Models/Multipass/
  • Models/Repository/, Models/Caddy/, Models/TLS/, Models/Setup/, Models/Dashboard/
• docs/src/content/docs/ - veroeffentlichte Astro/Starlight-Nutzerdokumentation
• docs/features/ - interne Feature-Status- und Fortschrittsdokumente
• docs/repository/ - YAML-Feeds fuer Web-Repositories
• docs/scripts/ - Build-Helfer fuer die Dokumentationssite
• scripts/ - Build- und Automatisierungs-Skripte
• assets/ - App- und Systray-Grafiken

YAML-Repository-Feed

Der initiale Repository-Feed liegt unter:

• docs/repository/repositories.yaml
• docs/repository/apps/index.yaml
• docs/repository/apps/*.yaml

Dieser Bereich ist fuer GitHub Pages vorgesehen und dient als Quelle fuer importierbare On-Demand-App-Definitionen.

Multipass-Konfiguration

Optional kann pro VM eine Konfiguration aus /etc/caddy-app.yaml importiert werden. Typische Inhalte:

• Service-Name, Port, Scheme (http/https)
• Host-/Wildcard-Routing (z. B. *.<service>.<vm>.mp.localhost)
• VM Auto-Start/Auto-Stop
• systemd-Steuerung (start, restart, stop)

Details siehe: docs/features/040-runtime-discovery-multipass-podman.md.

Releases

GitHub-Releases triggern den Build-Workflow in .github/workflows/release.yml. Dabei wird ein Release-Build erstellt, als macOS-App gebuendelt und als ZIP-Artefakt angehaengt. Der Release-Build wird als Universal-Binary (arm64 + x86_64) erzeugt.

Fuer lokale Distributionsartefakte:

make production
make dmg

Das DMG enthaelt ein Hintergrundbild sowie einen Applications-Ordner-Link fuer den ueblichen Drag-and-Drop-Installationspfad.

Release-App lokal starten (Download von GitHub)

Nach dem Entpacken kann macOS die App beim ersten Start blockieren (Gatekeeper/Quarantine). Falls die App nicht startet:

xattr -dr com.apple.quarantine CaddyApp.app
open CaddyApp.app

Optional zur Architektur-Pruefung:

file CaddyApp.app/Contents/MacOS/CaddyApp

Dokumentation

• Verwendet Astro mit Starlight und wird aus docs/ gebaut.
• Veroeffentlichte Inhalte liegen unter docs/src/content/docs/.
• Der YAML-Repository-Feed bleibt unter docs/repository/ und wird in denselben statischen Output gespiegelt.
• In der App ist die Dokumentation ueber den Support-Button und per F1 erreichbar.
• Projektueberblick: docs/PROJECT.md
• Interne Feature-Details: docs/features/*.md
• Agent-Regeln: AGENTS.md

Architektur-Hinweis (Model Refactor)

• Business-Logik (Validierung, Normalisierung, Mapping/Factory-Regeln) liegt in Models/**.
• ViewModels halten UI-Zustand und orchestrieren Services.
• Services kapseln IO/Systemintegration (Shell, Netzwerk, Filesystem) und vermeiden fachliche Duplikation.
• UI-nahe Mutation und Systemdialoge laufen auf dem MainActor; wiederkehrende Hintergrundarbeit wird zentral ueber InternalScheduler und explizite Cancellation gesteuert.
• Persistierte Einstellungen laufen ueber AppConfig; Legacy-CustomConfigSettings werden beim Laden migriert.