Laborbuch — administrator manual

Laboratory profile, projects, users and 2FA, storno, translations, week closes, backups, licence, updates.

The administrator manual for a Laborbuch instance — configuration, users, week closes, backups and the licence. Day-to-day work is covered by the user manual.

The admin panel

The panel lives at /admin/ (same account and 2FA as the journal — the panel cannot be opened bypassing 2FA). Accounts with the “staff” right have access; full configuration is done by the superuser created during installation.

First configuration — Site settings

Site settings → Laboratory profile adapts the system to how you work:

Setting	Meaning
Git/GitHub integration	Repositories, commit sync and commit anchors — the IT/hardware profile; disable in a lab without code
File anchors (uploads)	Attaching evidence files to entries
File anchor mode	Upload — files stored in the instance; Hash-only — the file stays with the user, the system stores only its SHA-256 fingerprint (trade secrets never reach the server)

Projects

Projects → Add: name, slug, Vorhaben code (mapping to the BSFZ application), a description demarcating R&D from routine. Two people lists:

• Members — add entries and see the project’s data.
• Observers — see entries and reports (teamwork) but without other people’s hours (masked “—”) and without the right to add entries.

A new account automatically becomes a member of every active project, and a new project receives all existing accounts. Excluding someone from a project is a deliberate removal from the Members list — a person removed once is never re-added.

With Git enabled, add Repositories to the project (owner/name format; the access token is set in the instance configuration as GITHUB_TOKEN). Commits sync every 15 minutes; manually: the dashboard button or the Sync commits from GitHub admin action.

A fine-grained token covers repositories of a single resource owner, so an organisation repository is invisible to a personal account’s token (GitHub then answers 404, not 403). Such a repository gets its own token in the Access token field — issued for the organisation (Resource owner = organisation, selected repository, Contents: Read-only permission); the organisation must allow access via fine-grained PATs. Empty field = the global token. The Check GitHub access action verifies the setup without fetching commits.

Users and 2FA

Users → Add: login and password, then on the account page permissions (“staff” for admin access) and role groups. You declare the 2FA method per account — at the bottom of the user page:

• 2FA — TOTP (app / hardware card): add a device; for apps (e.g. Google Authenticator) the key is generated automatically — the QR code is on the device’s page in the “TOTP devices” section; for a hardware card paste its seed into key and correct clock drift with drift/tolerance.
• 2FA — code by e-mail: add a device; empty email = the account’s address. Requires configured mail (EMAIL_* in the instance configuration).
• An account without a device logs in with the password alone.

The licence limit counts active accounts: with the limit exhausted you cannot add or activate an account — deactivating one (“active” unchecked) frees a seat without losing its entry history.

Accounting parameters (a section on the account page) hold the personal weekly cap. An empty field = the instance-wide cap, 40 h by default, i.e. the Eigenleistung rule under § 3 (3) FZulG. For an employee, enter their contractual hours: an employee’s hours are eligible in the amount actually worked, so a half-time position means 20 h, and an employee’s overtime is not “R&D above the cap”. The cap set here also shows on that person’s dashboard — in the week bar and as the chart line.

Entries, corrections (storno) and translations

Entries in the admin: the full list with filters. Entries of open weeks can be corrected; closed ones (🔒) are permanently read-only.

• Storno: add a new entry with negative hours and point at the corrected one in the corrects field. The original stays — the correction is explicit, as in accounting.
• Translations: with TRANSLATE_AUTO_LANGS set (e.g. de), every new or corrected entry is translated automatically in the background right after saving. Gaps (older entries, a temporary API outage) are filled by the report itself when generated in that language — in batches; in bulk: manage.py translate_entries --lang de. Manually: select entries → action Translate into German / English / Polish (Claude). A translation is a separate record (the original untouched), created once, and can be corrected by hand under Entry translations. Requires ANTHROPIC_API_KEY; every translation is a paid API call — but only one per entry and language.
• Anchors (section within an entry): commits, files (hash computed automatically), mtime, event log, other.

Closing the week — the working rhythm

The week is closed with a command on the server (e.g. each Monday for the previous week):

docker compose exec web python manage.py close_week 2026-W29

Closing: builds the canonical record of the week’s entries → computes SHA-256 → timestamps it via BeatTime (Ed25519 signature) and OpenTimestamps (Bitcoin anchoring) → locks the entries (🔒). Proofs are under Week closes. The OTS stamp matures after Bitcoin confirmation — upgrade_ots refreshes the proofs.

Rule of thumb: close regularly. An open week is entries without a stamp — the sooner you close, the stronger the evidence.

Backups

Admin home → Database backups: create a backup (no downtime), a dated list, Download (keep a copy off the server!), Restore (automatically saves the prior state as pre-restore-…) and Delete. The backup covers the database; evidence files in media/ need a separate directory copy. All operations land in the audit journal.

Read-access audit

Read accesses (audit) — an append-only register: who opened reports, downloaded evidence files, created and restored backups, and when. Records can be neither changed nor deleted.

The licence

The license.json file lives in the installation directory. Its state shows on the dashboard (customer, plan, seat limit, validity). After expiry the instance switches to read-only with full export — data is never held hostage. Renewal: swap in the new file (no restart).

Updates

cd laborbuch && docker compose pull && docker compose up -d

Database migrations run automatically on start. Images are signed (cosign). Create a backup before major updates.