DE EN IT

~/home / timesheet-guardian / nextcloud

Guide · Self-hosted

Set up the Timesheet Guardian in your Nextcloud

Six steps, one idempotent script, no vendor lock-in: the calendar, Deck, Talk and files of your own Nextcloud, driven by an n8n workflow.

Requirements

  • Nextcloud 28 or newer with Calendar, Deck, Talk and Files.
  • n8n 2.x, reachable from Nextcloud (and the other way round).
  • HTTPS on both sides (QR codes and the PWA need a secure context).
  • occ access (server shell or docker exec) as an admin.

The steps

  1. 1. Prepare Nextcloud with setup.sh

    Creates the groups zeit-team, zeit-chef, zeit-demo, the bot account zeitwaechter (500 MB) and, optionally, your boss. Idempotent: run it as often as you like. Variables: OCC, DEMO, CHEF_UID, CHEF_NAME, CHEF_MAIL, SECRETS_DIR (where bot.pass is written, 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. Access for n8n

    Create a Basic Auth credential in n8n: user zeitwaechter, password from bot.pass. Better: log in as zeitwaechter, Settings, Security, create an app password and use that (revocable on its own). Attach the credential to every Nextcloud HTTP node.

  3. 3. Import the workflow

    Import assets/n8n/zeitwaechter.json. In the node «Demo-Bereich festlegen» enter host, user, calendar, Deck board and Talk token. Create the calendar, the Deck board (with one stack) and the Talk room under the bot account first.

    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. Change the secrets

    Replace both webhook paths (…-CHANGE-ME) and the HMAC secret CHANGE-ME-LONG-RANDOM-SECRET. The secret must be identical in every Code node (use n8n's search). The path is the secret: at least 24 random characters. A new secret invalidates daily QR codes and registered phones.

    openssl rand -hex 32     # HMAC secret / webhook path
  5. 5. Activate and test

    Activate the workflow, then fill in https://YOUR-N8N/form/zeitwaechter: a calendar event, a Deck card and a Talk message must appear.

  6. 6. Phone app (PWA, optional)

    The pages /zeit/, /zeit/anmelden/, /zeit/s/, /zeit-qr/ are static. zeit-punch.php is a same-origin proxy to the stamp webhook (reads the path from private/zeit-punch-hook, n8n at 127.0.0.1:5678, env ZP_N8N/ZP_PRIV; adjust the ZP_PEOPLE name list). Without the PWA: use only the two n8n forms and print the QR codes from the qr webhook.

    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

What is Login Flow v2?

It is how Nextcloud issues an app password without the account password ever being typed into third-party software: the client POSTs /index.php/login/v2, the user approves in the browser, the client receives loginName and appPassword (revocable any time under Settings, Security). Creating the bot's app password by hand (step 2) is equivalent.

Roles

  • zeit-team Staff: see only their own data.
  • zeit-chef Boss: sees the whole team.
  • zeit-demo Fictitious demo accounts: cannot share, 20 MB, no real data.

Which data goes where

  • Bot's calendar: one event per working day or absence
  • Deck: one card per notice or working-time violation
  • Talk: notices and the Friday summary
  • Bot's files (Zeit/): zeiten.csv, stempel.csv, geraete.json, Berichte/
  • Sharing: per user or group, never public

Privacy

This is employee data. Check your legal basis (duty to record working time, GDPR Art. 6), involve the works council or unions where required (DE: § 87 BetrVG, IT: Art. 4 Statuto dei lavoratori), and give staff a privacy notice under Art. 13 GDPR (purpose, recipients, retention, rights). Retention in the working files: 70 days; if the law demands longer (DE § 16 ArbZG: 2 years for hours beyond 8), archive separately. Not legal advice.

Remove everything

The uninstaller asks at every step, only disables at first, never deletes real users, and deletes the bot and demo accounts with their data only with --delete-data and a typed LOESCHEN. Afterwards: deactivate the n8n workflow, delete the credential, remove the PWA files and private/zeit-punch-hook from the web server.

./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