Skip to content

CONFIGURATION

Jump to bottom
scheilch edited this page Mar 8, 2026 · 2 revisions

🇬🇧 English version

OpenCloudTouch Konfigurationsanleitung

Version: 0.2.0
Letzte Aktualisierung: 11.02.2026

Dieses Dokument beschreibt alle Konfigurationsoptionen für das OpenCloudTouch-Backend.

Konfigurationsmethoden

OpenCloudTouch unterstützt 3 Konfigurationsmethoden (in Reihenfolge der Priorität):

  1. Umgebungsvariablen (höchste Priorität)
  2. Konfigurationsdatei (config.yaml)
  3. Eingebaute Standardwerte (Fallback)

Die Konfiguration wird von Pydantic Settings mit automatischer Validierung verarbeitet.

Umgebungsvariablen

Alle Umgebungsvariablen verwenden das Präfix OCT_, um Konflikte zu vermeiden.

Grundeinstellungen

Variable Typ Standard Beschreibung
OCT_HOST string 0.0.0.0 API-Bindungsadresse (0.0.0.0 für Docker verwenden)
OCT_PORT int 7777 API-Port
OCT_LOG_LEVEL enum INFO Log-Level: DEBUG, INFO, WARNING, ERROR, CRITICAL
OCT_DB_PATH path /data/oct.db Pfad zur SQLite-Datenbankdatei

Erkennungseinstellungen

Variable Typ Standard Beschreibung
OCT_DISCOVERY_ENABLED bool true SSDP/UPnP-Automatischerkennung aktivieren
OCT_DISCOVERY_TIMEOUT int 10 SSDP-Erkennungs-Timeout in Sekunden
OCT_MANUAL_DEVICE_IPS list [] Kommagetrennte Geräte-IPs (Fallback)

Beispiel:

export OCT_MANUAL_DEVICE_IPS="192.168.178.78,192.168.178.79"

Erweiterte Einstellungen

Variable Typ Standard Beschreibung
OCT_MOCK_MODE bool false Mock-Geräte zum Testen verwenden (keine echte Hardware nötig)
OCT_CORS_ORIGINS list ["*"] Erlaubte CORS-Origins (kommagetrennt)
OCT_MAX_DEVICE_POLL_INTERVAL int 30 Gerätestatus-Abfrageintervall (Sekunden)

Konfigurationsdatei (config.yaml)

OpenCloudTouch kann die Konfiguration aus einer YAML-Datei laden.

Konfigurationsdatei in Docker verwenden

Konfigurationsdatei als Volume einbinden:

docker run -d \
  --name opencloudtouch \
  --network host \
  -v /path/to/config.yaml:/app/config.yaml:ro \
  -v oct-data:/data \
  opencloudtouch:latest

Einbindung über Docker Compose:

# docker-compose.yml
services:
  opencloudtouch:
    image: opencloudtouch:latest
    network_mode: host
    volumes:
      - ./config.yaml:/app/config.yaml:ro  # Read-only
      - oct-data:/data

Format der Konfigurationsdatei

# config.yaml - OpenCloudTouch Konfiguration
# Umgebungsvariablen haben Vorrang vor dieser Datei

# Grundeinstellungen
host: "0.0.0.0"
port: 7777
log_level: "INFO"
db_path: "/data/oct.db"

# Erkennungseinstellungen
discovery:
  enabled: true
  timeout: 10
  manual_ips:
    - "192.168.178.78"
    - "192.168.178.79"

# CORS-Einstellungen
cors:
  origins:
    - "http://localhost:5173"  # Vite Dev-Server
    - "https://myapp.example.com"

# Mock-Modus (zum Testen ohne Hardware)
mock_mode: false

# Geräte-Abfrage
max_device_poll_interval: 30

Ladepriorität:

  • OCT_PORT=8080 (Umgebungsvariable) überschreibt port: 7777 (config.yaml)
  • port: 7777 (config.yaml) überschreibt den eingebauten Standardwert 7777

Umgebungsspezifische Konfigurationen

Entwicklung (Lokal)

# .env.development
OCT_LOG_LEVEL=DEBUG
OCT_MOCK_MODE=true
OCT_DISCOVERY_ENABLED=false
OCT_MANUAL_DEVICE_IPS=192.168.1.100,192.168.1.101

Produktion (Docker)

# docker-compose.yml
environment:
  OCT_LOG_LEVEL: INFO
  OCT_DISCOVERY_ENABLED: true
  OCT_DB_PATH: /data/oct.db

Test (CI/CD)

# GitHub Actions / CI
export OCT_MOCK_MODE=true
export OCT_DB_PATH=:memory:
export OCT_LOG_LEVEL=WARNING

Konfigurationsvalidierung

OpenCloudTouch validiert die Konfiguration beim Start mithilfe von Pydantic.

Gültige Konfiguration

docker logs opencloudtouch
# [INFO] Environment validation passed
# [INFO] Data directory OK
# [INFO] Database exists
# [INFO] Starting application on 0.0.0.0:7777

Ungültige Konfiguration

docker run -e OCT_PORT=invalid opencloudtouch:latest
# [ERROR] OCT_PORT must be numeric (got: invalid)
# Exit code: 1

Häufige Konfigurationsszenarien

Szenario 1: Port ändern

Umgebungsvariable:

docker run -e OCT_PORT=8080 -p 8080:8080 opencloudtouch:latest

Konfigurationsdatei:

# config.yaml
port: 8080

Szenario 2: Manuelle Geräte-IPs (ohne Erkennung)

docker run \
  -e OCT_DISCOVERY_ENABLED=false \
  -e OCT_MANUAL_DEVICE_IPS="192.168.1.10,192.168.1.20" \
  opencloudtouch:latest

Szenario 3: Debug-Protokollierung

docker run -e OCT_LOG_LEVEL=DEBUG opencloudtouch:latest

Szenario 4: Benutzerdefinierter Datenbankspeicherort

docker run \
  -e OCT_DB_PATH=/data/custom.db \
  -v /my/data:/data \
  opencloudtouch:latest

Szenario 5: Mock-Modus (Testen ohne Hardware)

docker run -e OCT_MOCK_MODE=true opencloudtouch:latest

Fehlerbehebung bei der Konfiguration

Aktuelle Konfiguration prüfen

Über Logs:

docker logs opencloudtouch | grep "Starting application"
# [INFO] Starting application on 0.0.0.0:7777
# [INFO] Database: /data/oct.db
# [INFO] Discovery: true

Über die API:

curl http://localhost:7777/health
# {"status":"healthy","version":"0.2.0"}

Häufige Probleme

Problem: „Data directory is not writable"

# Berechtigungen korrigieren:
docker exec opencloudtouch ls -ld /data
# drwxr-xr-x 2 oct oct 4096 ...

Problem: „OCT_LOG_LEVEL must be one of: DEBUG, INFO, ..."

# Nur gültige Werte verwenden:
export OCT_LOG_LEVEL=INFO  # ✅
export OCT_LOG_LEVEL=info  # ❌ (Groß-/Kleinschreibung beachten!)

Problem: Geräte werden nicht gefunden

# Debug-Protokollierung aktivieren:
docker run -e OCT_LOG_LEVEL=DEBUG opencloudtouch:latest
# Logs auf SSDP-Erkennungsdetails prüfen

Konfigurationsreferenz (Code)

Die Konfiguration ist definiert in: apps/backend/src/opencloudtouch/core/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class AppConfig(BaseSettings):
    """Application configuration with environment variable support."""
    
    model_config = SettingsConfigDict(
        env_prefix="OCT_",
        case_sensitive=False,
        env_file=".env",
        env_file_encoding="utf-8"
    )
    
    # Core
    host: str = "0.0.0.0"
    port: int = 7777
    log_level: str = "INFO"
    db_path: str = "/data/oct.db"
    
    # Discovery
    discovery_enabled: bool = True
    discovery_timeout: int = 10
    manual_device_ips: list[str] = []
    
    # Mock mode
    mock_mode: bool = False

Bewährte Vorgehensweisen

  1. Umgebungsvariablen in Docker verwenden – Einfacher pro Deployment zu überschreiben
  2. Konfigurationsdatei für die Entwicklung verwenden – In Git versionieren, im Team teilen
  3. Niemals Geheimnisse committen – .env.local verwenden (in .gitignore)
  4. Beim Start validieren – Die Anwendung bricht bei ungültiger Konfiguration sofort ab
  5. Standardwerte dokumentieren – Benutzer sollten wissen, was ohne Konfiguration passiert

Siehe auch

OpenCloudTouch

🇩🇪 Benutzerhandbuch

🇬🇧 User Guide

Development

API & Architecture

Technical Reference

Legal

Clone this wiki locally