~/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. 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. 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. 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. 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 path5. 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. 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-teamStaff: see only their own data.zeit-chefBoss: sees the whole team.zeit-demoFictitious 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
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)