dorfteich/docs/manual/site-admin-guide.md

Site-admin guide

Deutsche Fassung: docs/de/manual/site-admin-guide.md

How to administer a Dorfteich instance from the browser. Installation, updates, and host-level operations are covered by the self-hosting guide; this guide is about the two admin pages: Admin → Settings (/admin) and Admin → System (/admin/system).

A site admin sees and may do everything — use a normal account for daily work.

First contact: the setup wizard

A fresh instance greets you with a six-step wizard: language → the site-admin account → instance name and default language → SMTP relay (with a live test mail; skippable) → registration mode → done. Until it finishes, the instance answers everything with 503 setup_required. Unattended installs pre-seed the wizard via SETUP_ADMIN_* environment variables.

Admin → Settings

Instance

• Name (shown in the top bar and mails) and default language (used for anonymous visitors and server-rendered pages).
• Registration mode: open (anyone may sign up, with e-mail verification) or closed (only existing accounts sign in).

Quotas

Instance-wide defaults: editors/readers per pond, additional shared ponds per user (default 0 — raise it or grant per-user overrides to let people create shared ponds), storage per pond, maximum file size. The quota manager below sets per-user/per-pond overrides that win over the defaults.

Uploads

The allow-list of non-image file extensions users may attach, and the SVG policy (sanitize strips scripts from uploaded SVGs, reject refuses them).

Public API and MCP

Two independent master switches, both off by default:

• Public REST API: lets users mint personal access tokens and use /api/public/v1 (see the API guide).
• Built-in MCP endpoint: exposes /api/mcp for AI assistants (MCP guide).

Either switch alone does nothing per pond — each pond additionally opts in via its pond settings. Off means the endpoints answer 404.

Legal pages

Imprint and privacy policy as Markdown, published at /legal/imprint and /legal/privacy and linked from every page footer. A template with a review checklist ships in docs/self-hosting/legal-template.md. Until configured, the pages show a notice (and you a warning banner).

Backups

See Admin → System → Backups below.

Plugins

Install plugins by uploading a ZIP (alternatively: drop the ZIP into the _dropzone/ folder on the plugins volume — a watcher installs it within seconds and moves rejected packages to _quarantine/ with the reason).

Each installed plugin has an instance mode:

Mode	Meaning
disabled	inactive everywhere (the default after install)
optional	pond admins decide per pond
required	active in every pond, no opt-out

Every plugin has a sandboxed preview page for trying it before enabling. Uninstalling is blocked while a plugin is required; documents keep their plugin blocks either way and show the plugin's fallback text when it is missing.

Shipped reference plugins: toc (table of contents), page-index (label-filtered page list), mermaid (diagram blocks), drawio (full draw.io editing), section-styles-basic (colored callouts).

Getting the reference plugin ZIPs. They are not bundled with the server images — build them from the repository (Node 22 + pnpm, one-time pnpm install at the repo root):

cd packages/plugins/<name>   # toc | page-index | mermaid | drawio | section-styles-basic
pnpm build                   # → dist/<id>-<version>.zip — upload that file

The drawio build downloads its pinned editor bundle from GitHub on the first run and packs a ~27 MiB ZIP (within the 64 MiB plugin upload limit); the other four build offline in seconds.

Typical rollout: upload the ZIP, check the sandboxed preview, switch the instance mode to optional, then enable the plugin per pond (pond settings → Plugins — in personal ponds the owner does this).

Users

The user manager: search accounts, disable/enable, resend verification mails, promote/demote site admins, and delete accounts. Deletion offers pseudonymization: the account and its personal data disappear, but shared content survives attributed to a neutral placeholder. Guards prevent disabling yourself or removing the last site admin.

Admin → System

The operator's single glance:

• Jobs: every maintenance job (trash purge, version thinning, page compaction, data-export purge, notification digests) with cadence, last run, duration and outcome — plus a manual Run button (itself audit-logged).
• Backups: the status card mirrors the sidecar's last run and its freshness verdict, with a Back up now button. Below it:
  • Backup settings: local retention (overrides the container default), and the Nextcloud target — server address, username, app password (kept in the file-based secret store on the secrets volume, never in the database), folder, upload schedule (after every backup / weekly / manual), remote retention, and a Test connection button that verifies credentials and creates the folder.
  • Restore: lists local and Nextcloud sets; restoring asks you to re-type the backup id, then the instance enters maintenance mode, restores itself, and restarts. Everything else about backups (mirror to a private host, disaster recovery) lives in the self-hosting guide and the restore runbook.
• Audit log: administrative and auth events (grants, members, user admin, quotas, plugins, settings, setup, tokens, API writes, backup actions) with actor/action/time filters, 50 per page.
• Storage: the twenty largest ponds and the instance total.

Health, monitoring, go-live

• GET /api/v1/readyz is the instance's own diagnosis; monitor it (down vs. degraded semantics and a ready-made monitor set: deploy/monitoring.md).
• Going live checklist for a fresh production instance: deploy/go-live.md.