breakpilot-pwa/.claude/rules/night-scheduler.md

Night Scheduler - Entwicklerdokumentation

Status: Produktiv Letzte Aktualisierung: 2026-02-09 URL: https://macmini:3002/infrastructure/night-mode API: http://macmini:8096

---

Uebersicht

Der Night Scheduler ermoeglicht die automatische Nachtabschaltung der Docker-Services:

• Zeitgesteuerte Abschaltung (Standard: 22:00)
• Zeitgesteuerter Start (Standard: 06:00)
• Manuelle Sofortaktionen (Start/Stop)
• Dashboard-UI zur Konfiguration

---

Architektur

┌─────────────────────────────────────────────────────────────┐
│  Admin Dashboard (Port 3002)                                │
│  /infrastructure/night-mode                                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  API Proxy: /api/admin/night-mode                           │
│  - GET: Status abrufen                                      │
│  - POST: Konfiguration speichern                            │
│  - POST /execute: Sofortaktion (start/stop)                 │
│  - GET /services: Service-Liste                             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  night-scheduler (Port 8096)                                │
│  - Python/FastAPI Container                                 │
│  - Prueft jede Minute ob Aktion faellig                     │
│  - Fuehrt docker compose start/stop aus                     │
│  - Speichert Config in /config/night-mode.json              │
└─────────────────────────────────────────────────────────────┘

---

Dateien

Pfad	Beschreibung
night-scheduler/scheduler.py	Python Scheduler mit FastAPI
night-scheduler/Dockerfile	Container mit Docker CLI
night-scheduler/requirements.txt	Dependencies
night-scheduler/config/night-mode.json	Konfigurationsdatei
night-scheduler/tests/test_scheduler.py	Unit Tests
admin-v2/app/api/admin/night-mode/route.ts	API Proxy
admin-v2/app/api/admin/night-mode/execute/route.ts	Execute Endpoint
admin-v2/app/api/admin/night-mode/services/route.ts	Services Endpoint
admin-v2/app/(admin)/infrastructure/night-mode/page.tsx	UI Seite

---

API Endpoints

GET /api/night-mode

Status und Konfiguration abrufen.

Response:

{
  "config": {
    "enabled": true,
    "shutdown_time": "22:00",
    "startup_time": "06:00",
    "last_action": "startup",
    "last_action_time": "2026-02-09T06:00:00",
    "excluded_services": ["night-scheduler", "nginx"]
  },
  "current_time": "14:30:00",
  "next_action": "shutdown",
  "next_action_time": "22:00",
  "time_until_next_action": "7h 30min",
  "services_status": {
    "backend": "running",
    "postgres": "running"
  }
}

POST /api/night-mode

Konfiguration aktualisieren.

Request:

{
  "enabled": true,
  "shutdown_time": "23:00",
  "startup_time": "07:00",
  "excluded_services": ["night-scheduler", "nginx", "vault"]
}

POST /api/night-mode/execute

Sofortige Aktion ausfuehren.

Request:

{
  "action": "stop"  // oder "start"
}

Response:

{
  "success": true,
  "message": "Aktion 'stop' erfolgreich ausgefuehrt fuer 25 Services"
}

GET /api/night-mode/services

Liste aller Services abrufen.

Response:

{
  "all_services": ["backend", "postgres", "valkey", ...],
  "excluded_services": ["night-scheduler", "nginx"],
  "status": {
    "backend": "running",
    "postgres": "running"
  }
}

---

Konfiguration

Config-Format (night-mode.json)

{
  "enabled": true,
  "shutdown_time": "22:00",
  "startup_time": "06:00",
  "last_action": "startup",
  "last_action_time": "2026-02-09T06:00:00",
  "excluded_services": ["night-scheduler", "nginx"]
}

Umgebungsvariablen

Variable	Default	Beschreibung
COMPOSE_PROJECT_NAME	breakpilot-pwa	Docker Compose Projektname

---

Ausgeschlossene Services

Diese Services werden NICHT gestoppt:

1. night-scheduler - Muss laufen, um Services zu starten
2. nginx - Optional, fuer HTTPS-Zugriff

Weitere Services koennen ueber die Konfiguration ausgeschlossen werden.

---

Docker Compose Integration

night-scheduler:
  build: ./night-scheduler
  container_name: breakpilot-pwa-night-scheduler
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - ./night-scheduler/config:/config
    - ./docker-compose.yml:/app/docker-compose.yml:ro
  environment:
    - COMPOSE_PROJECT_NAME=breakpilot-pwa
  ports:
    - "8096:8096"
  networks:
    - breakpilot-pwa-network
  restart: unless-stopped

---

Tests ausfuehren

# Im Container
docker exec -it breakpilot-pwa-night-scheduler pytest -v

# Lokal (mit Dependencies)
cd night-scheduler
pip install -r requirements.txt
pytest -v tests/

---

Deployment

# 1. Dateien synchronisieren
rsync -avz night-scheduler/ macmini:.../night-scheduler/

# 2. Container bauen
ssh macmini "docker compose -f .../docker-compose.yml build --no-cache night-scheduler"

# 3. Container starten
ssh macmini "docker compose -f .../docker-compose.yml up -d night-scheduler"

# 4. Testen
curl http://macmini:8096/health
curl http://macmini:8096/api/night-mode

---

Troubleshooting

Problem: Services werden nicht gestoppt/gestartet

1. Pruefen ob Docker Socket gemountet ist:

   docker exec breakpilot-pwa-night-scheduler ls -la /var/run/docker.sock
   

2. Pruefen ob docker compose CLI verfuegbar ist:

   docker exec breakpilot-pwa-night-scheduler docker compose version
   

3. Logs pruefen:

   docker logs breakpilot-pwa-night-scheduler
   

Problem: Konfiguration wird nicht gespeichert

1. Pruefen ob /config beschreibbar ist:

   docker exec breakpilot-pwa-night-scheduler touch /config/test
   

2. Volume-Mount pruefen in docker-compose.yml

Problem: API nicht erreichbar

1. Container-Status pruefen:

   docker ps | grep night-scheduler
   

2. Health-Check pruefen:

   curl http://localhost:8096/health
   

---

Sicherheitshinweise

• Der Container benoetigt Zugriff auf den Docker Socket
• Nur interne Services koennen gestoppt/gestartet werden
• Keine Authentifizierung (internes Netzwerk)
• Keine sensitiven Daten in der Konfiguration

---

Dependencies (SBOM)

Package	Version	Lizenz
FastAPI	0.109.0	MIT
Uvicorn	0.27.0	BSD-3-Clause
Pydantic	2.5.3	MIT
pytest	8.0.0	MIT
pytest-asyncio	0.23.0	Apache-2.0
httpx	0.26.0	BSD-3-Clause

---

Aenderungshistorie

Datum	Aenderung
2026-02-09	Initiale Implementierung