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

# Site-admin guide

_Deutsche Fassung: [docs/de/manual/site-admin-guide.md](../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](../self-hosting/README.md); 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](api-guide.md)).
- **Built-in MCP endpoint**: exposes `/api/mcp` for AI assistants
  ([MCP guide](mcp-guide.md)).

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`](../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), `excalidraw` (hand-drawn sketches), `chordpro`
(ChordPro leadsheets — chords above lyrics), `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):

```sh
cd packages/plugins/<name>   # toc | page-index | mermaid | drawio | excalidraw | chordpro | 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); `excalidraw` bundles its editor from npm into a ~16 MiB ZIP; the
remaining five 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](../self-hosting/README.md#backups--restore) and
    the [restore runbook](../operations/restore-runbook.md).
- **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`](../../deploy/monitoring.md)).
- Going live checklist for a fresh production instance:
  [`deploy/go-live.md`](../../deploy/go-live.md).