DE EN IT

~/home / arbeitszeit-waechter / nextcloud

Anleitung · Selbst hosten

Zeit-Wächter in deiner Nextcloud einrichten

Sechs Schritte, ein idempotentes Skript, kein Vendor-Lock-in: Kalender, Deck, Talk und Dateien deiner eigenen Nextcloud, gesteuert von einem n8n-Workflow.

Voraussetzungen

  • Nextcloud 28 oder neuer mit den Apps Calendar, Deck, Talk und Files.
  • n8n 2.x, von Nextcloud erreichbar (und umgekehrt).
  • HTTPS auf beiden Seiten (QR-Codes und PWA brauchen einen sicheren Kontext).
  • occ-Zugang (Server-Shell oder docker exec) als Admin.

Die Schritte

  1. 1. Nextcloud mit setup.sh vorbereiten

    Legt die Gruppen zeit-team, zeit-chef, zeit-demo, das Bot-Konto zeitwaechter (500 MB) und optional deinen Chef an. Idempotent: du kannst es beliebig oft starten. Variablen: OCC, DEMO, CHEF_UID, CHEF_NAME, CHEF_MAIL, SECRETS_DIR (dort liegt bot.pass, chmod 600).

    # Docker AIO (Standard des Skripts)
    CHEF_UID=mario CHEF_NAME="Mario Rossi" CHEF_MAIL=mario@firma.example DEMO=0 ./setup.sh
    
    # Docker Compose (Dienst "app")
    OCC="docker compose exec -T -u www-data -e OC_PASS app php occ" DEMO=0 CHEF_UID=mario CHEF_MAIL=mario@firma.example ./setup.sh
    
    # Bare metal
    OCC="sudo -u www-data --preserve-env=OC_PASS php /var/www/nextcloud/occ" DEMO=0 SECRETS_DIR=/root/zeit-secrets ./setup.sh
    
    ./setup.sh --check          # nur Status
    ./setup.sh --demo-off       # Demo-Konten deaktivieren (--purge: löschen)
  2. 2. Zugang für n8n

    In n8n eine Credential vom Typ Basic Auth anlegen: Benutzer zeitwaechter, Passwort aus bot.pass. Besser: als zeitwaechter anmelden, unter Einstellungen, Sicherheit ein App-Passwort erzeugen und dieses nehmen (einzeln widerrufbar). Die Credential allen Nextcloud-HTTP-Knoten zuweisen.

  3. 3. Workflow importieren

    assets/n8n/zeitwaechter.json importieren. Im Knoten «Demo-Bereich festlegen» Host, Benutzer, Kalender, Deck-Board und Talk-Token eintragen. Kalender, Deck-Board (mit einem Stapel) und Talk-Raum vorher im Konto des Bots anlegen.

    const NC = 'https://cloud.example.com';
    const USER = 'zeitwaechter';
    const TALK = `${NC}/ocs/v2.php/apps/spreed/api/v1/chat/YOUR-TALK-TOKEN`;
    // + calendar slug (CAL), Deck board/stack ids (DECK)
  4. 4. Geheimnisse ändern

    Beide Webhook-Pfade (…-CHANGE-ME) und das HMAC-Geheimnis CHANGE-ME-LONG-RANDOM-SECRET ersetzen. Das Geheimnis muss in allen Code-Knoten gleich sein (n8n-Suche nutzen). Der Pfad ist das Geheimnis: mindestens 24 zufällige Zeichen. Ein neues Geheimnis macht Tages-QR-Codes und registrierte Handys ungültig.

    openssl rand -hex 32     # HMAC secret / webhook path
  5. 5. Aktivieren und testen

    Workflow aktivieren, dann https://DEIN-N8N/form/zeitwaechter ausfüllen: Es muss ein Kalendereintrag, eine Deck-Karte und eine Talk-Nachricht entstehen.

  6. 6. Handy-App (PWA, optional)

    Die Seiten /zeit/, /zeit/anmelden/, /zeit/s/, /zeit-qr/ sind statisch. zeit-punch.php ist ein Same-Origin-Proxy zum Stempel-Webhook (liest den Pfad aus private/zeit-punch-hook, n8n unter 127.0.0.1:5678, Umgebung ZP_N8N/ZP_PRIV; Namensliste ZP_PEOPLE anpassen). Ohne PWA: nur die zwei n8n-Formulare und die QR-Codes aus dem qr-Webhook drucken.

    location = /zeit-punch.php { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root/zeit-punch.php; fastcgi_pass unix:/run/php/php-fpm.sock; }
    location ^~ /private/ { deny all; }      # better: private/ outside the web root
    # private/zeit-punch-hook = one line: the path of the n8n stamp webhook

Was ist Login Flow v2?

Nextcloud stellt damit ein App-Passwort aus, ohne dass das Kontopasswort in Fremdsoftware getippt wird: Der Client ruft POST /index.php/login/v2 auf, der Nutzer bestätigt im Browser, der Client erhält loginName und appPassword (jederzeit unter Einstellungen, Sicherheit widerrufbar). Das App-Passwort des Bots von Hand zu erzeugen (Schritt 2) ist gleichwertig.

Rollen

  • zeit-team Mitarbeiter: sehen nur ihre eigenen Daten.
  • zeit-chef Chef: sieht das ganze Team.
  • zeit-demo Fiktive Demo-Konten: dürfen nichts teilen, 20 MB, keine echten Daten.

Welche Daten landen wo

  • Kalender des Bots: ein Eintrag je Arbeitstag oder Abwesenheit
  • Deck: eine Karte je Hinweis oder ArbZG-Verstoß
  • Talk: Hinweise und Freitags-Zusammenfassung
  • Dateien des Bots (Zeit/): zeiten.csv, stempel.csv, geraete.json, Berichte/
  • Freigabe: je Benutzer oder Gruppe, nie öffentlich

Datenschutz

Es sind Beschäftigtendaten. Prüfe die Rechtsgrundlage (Pflicht zur Zeiterfassung, Art. 6 DSGVO, § 26 BDSG), beteilige den Betriebsrat (§ 87 BetrVG), wo es einen gibt, und gib den Beschäftigten eine Information nach Art. 13 DSGVO (Zweck, Empfänger, Fristen, Rechte). Aufbewahrung in den Arbeitsdateien: 70 Tage; verlangt das Gesetz längere Fristen (§ 16 ArbZG: 2 Jahre für Zeiten über 8 Stunden), archiviere getrennt. Keine Rechtsberatung.

Vollständig entfernen

Der Rückbau fragt bei jedem Schritt nach, deaktiviert zunächst nur, löscht echte Benutzer nie und löscht Bot- und Demo-Konten samt Daten nur mit --delete-data und getipptem LOESCHEN. Danach: n8n-Workflow deaktivieren, Credential löschen, PWA-Dateien und private/zeit-punch-hook vom Webserver entfernen.

./uninstall.sh --dry-run        # show only
./uninstall.sh                  # asks at each step; disables accounts, removes groups
./uninstall.sh --delete-data    # may DELETE bot + demo accounts with data (type LOESCHEN)

Downloads