PKR-Lab

Konfiguration

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ios/konfiguration.md

Konfiguration

Code: Utilities/Constants.swift, Services/KeychainService.swift, project.yml

Die App hat keine Konfigurationsdatei und keine Feature-Flags. Alle Adressen und festen Werte stehen im Quelltext in Constants.swift, geheime Werte im Keychain des Geräts. Eine Änderung der Konstanten erfordert einen neuen Build.


Konstanten (Constants.swift)

Konstante Wert Bedeutung
apiBaseURL https://carplay-api.prod.homeserver Backend carplay-api (läuft im TECH-Cluster, prod ist nur die URL-Stufe, siehe Domain-Tiers)
wolAgentBaseURL https://100.123.214.4:9102 WoL-Agent auf dem Banana Pi im Vereinsheim, Tailscale-IP
refreshInterval 30 Sekunden Pause zwischen zwei Abrufen von GET /api/dashboard
requestTimeout 10 Sekunden Timeout je Anfrage an carplay-api und WoL-Agent
maxAlertTitleLength 20 Alert-Titel werden in der Liste auf 20 Zeichen gekürzt (…)
maxAlertSubtitleLength 30 Alert-Nachricht auf 30 Zeichen
Weather.latitude, longitude, locationLabel 50.4205, 7.4061, „Andernach, Deutschland“ Wetterstandort (fest)
Weather.openMeteoForecastURL https://api.open-meteo.com/v1/forecast Wetterquelle
Tankerkoenig.baseURL https://creativecommons.tankerkoenig.de/json Preis-API
Tankerkoenig.nearbySearchRadiusKm 10 Umkreis der Suche nach der nächsten Station
Tankerkoenig.excludedBrands Shell, Aral, Esso, Agip, Eni Marken, die bei „Nächste“ übersprungen werden
Tankerkoenig.fixedStations Andernach, Plaidt, Mülheim-Kärlich drei Stationen mit fester Tankerkönig-ID
Pegel.baseURL, stationUUID, stationLabel Pegelonline REST v2, UUID der Station, „Rhein-Pegel Andernach“ Pegelstand
SelfHostedServices.all Nextcloud, Immich, Vaultwarden, Paperless-ngx, n8n, Wiki.js, Zammad Kacheln „Dienste“ im Alltag-Dashboard, jeweils https://<host>
News.tagesschauURL, heiseFeedURL, weltFeedURL Tagesschau-API, Heise-Atom, WELT-RSS Nachrichtenquellen
News.maxSummaryLength 160 Zusammenfassung wird gekürzt
Keychain.service com.yourname.homeserver-dashboard Dienstname aller Keychain-Einträge
timeZoneIdentifier, timeZone Europe/Berlin Zeitzone für Open-Meteo und die Datumsformate
locationPurposeKey TankstellenSuche Schlüssel in NSLocationTemporaryUsageDescriptionDictionary (project.yml) für die genaue Standortfreigabe
HostID.homeserver, controlPlane1, worker1 homeserver, controlplane-1, worker-1 Host-IDs aus dem Dashboard, die die Steuerung für den Online-Status nutzt

Die Host-Karten der Übersicht (Homeserver, NAS, ControlPlane-1, Worker 1) werden nicht in der App festgelegt, sondern vom Backend geliefert (config.hosts in den Helm-Values von carplay-api, siehe carplay-api: Konfiguration). Die App zeigt nur die Hosts, die online sind.


Keychain-Einträge

Die App speichert drei Werte mit kSecClassGenericPassword und kSecAttrAccessibleWhenUnlockedThisDeviceOnly (nur bei entsperrtem Gerät lesbar, nicht in Backups oder auf andere Geräte übertragbar):

Konto (kSecAttrAccount) Inhalt Eingabe Verwendet von
carplay-api-bearer-token Bearer-Token für carplay-api Einstellungen → „carplay-api Token“ HomeserverAPIClient (Header Authorization: Bearer …)
vereinsheim-wol-agent-bearer-token Token des WoL-Agents Einstellungen → „Vereinsheim-WoL-Agent-Token“ RemoteWolAgentClient
tankerkoenig-api-key Tankerkönig-API-Key Einstellungen → „Tankerkönig API-Key“ TankerkoenigAPIClient

Das Einstellungs-Sheet (Zahnrad) öffnen nur die Tabs Steuerung und Tankstellen. Jeder Bereich hat In Keychain speichern (aktiv erst bei nicht leerem Feld) und Gespeichertes … entfernen. Nach dem Speichern leert die App das Eingabefeld. Beim Öffnen steht „Es ist bereits ein Token/Key gespeichert.“, wenn ein Wert existiert. Der gespeicherte Wert wird nie angezeigt.


Transport

Die App hat keine App-Transport-Security-Ausnahme: Jede Anfrage muss HTTPS sein. Traefik leitet HTTP global auf HTTPS um und liefert *.tech.homeserver und *.prod.homeserver mit Zertifikaten einer privaten Root-CA aus (Internes TLS).

Für alle Hosts mit Endung .homeserver und für den Host aus wolAgentBaseURL (100.123.214.4) validiert MTLSDelegate das Serverzertifikat nur gegen die mitgelieferte Root-CA homeserver-root-ca.pem (SecTrustSetAnchorCertificates plus SecTrustSetAnchorCertificatesOnly), nicht gegen den Trust Store des Geräts. Ein Zertifikat einer anderen CA wird abgelehnt, auch wenn der Nutzer sie auf dem iPhone installiert hat. Ein Konfigurationsprofil mit der Root-CA auf dem Gerät ist für diese App nicht mehr nötig. Fehlt die Datei im Bundle, schlagen alle gepinnten Anfragen fehl (fail closed). Alle anderen Hosts (Wetter, News, Tankpreise) nutzen den Standard.

Die Root-CA läuft 2036-08-10 ab. Bei einem Wechsel muss Resources/homeserver-root-ca.pem ersetzt und die App neu gebaut werden. Der CI-Job ca-checksum vergleicht die Datei mit pki/homeserver-root-ca.pem in capulus-core und schlägt bei Abweichung fehl. Details: Verbindung und Sicherheit.


Projekteinstellungen (project.yml)

Schlüssel Wert Wirkung
options.deploymentTarget.iOS 15.0 Mindestversion (nur hier gesetzt, gilt für das Target mit)
PRODUCT_BUNDLE_IDENTIFIER com.yourname.homeserver-dashboard Platzhalter, anpassen
MARKETING_VERSION, CURRENT_PROJECT_VERSION 1.0.0, 1 Rückfallwert; das Build-Skript „Version aus Git-Tag“ setzt CFBundleShortVersionString im gebauten Info.plist auf den letzten Tag vX.Y.Z (ohne v)
ENABLE_USER_SCRIPT_SANDBOXING false nötig, damit das Versions-Skript git und das gebaute Info.plist erreicht
TARGETED_DEVICE_FAMILY 1,2 iPhone und iPad
UIRequiresFullScreen true kein Split View auf dem iPad
UISupportedInterfaceOrientations iPhone: Hochformat. iPad: alle vier
NSLocationWhenInUseUsageDescription Text zur Tankstellen-Suche Standortabfrage „beim Verwenden“
NSLocationTemporaryUsageDescriptionDictionary.TankstellenSuche Text für die temporär genaue Standortfreigabe wird von LocationManager angefragt
SWIFT_VERSION 5.0 kein Swift-6-Strict-Concurrency
scheme.testTargets leer es gibt keine Tests

Die Datei HomeserverDashboard.entitlements ist leer. Es gibt keine Entitlements, kein Keychain-Sharing und keine Network-Extension.


Debugging und Fehlersuche

Symptom Ursache Lösung
Änderung an Constants.swift wirkt nicht alter Build auf dem Gerät neu bauen und installieren
Alle Anfragen an *.homeserver schlagen fehl, Safari lädt die Seite Root-CA fehlt im Bundle oder ist abgelaufen/ersetzt Resources/homeserver-root-ca.pem prüfen (openssl x509 -in … -noout -dates), project.yml bindet sie als Ressource ein
ca-checksum in der CI schlägt fehl Kopie weicht von capulus-core ab Datei aus pki/homeserver-root-ca.pem neu kopieren
Token fehlt nach Neuinstallation oder Identifier-Wechsel TODO: prüfen, ob iOS die Keychain-Einträge behält Token neu eingeben, siehe Installation
Zahnrad fehlt nur auf Steuerung und Tankstellen vorhanden zu einem dieser Tabs wechseln (im Alltag-Modus: Tankstellen)
„Speichern fehlgeschlagen: …“ Keychain-Fehler (KeychainError.unhandled(status)) Gerät entsperren, Fehlercode (OSStatus) nachschlagen

Mehr: Debugging und Fehlersuche.