Claude Fable 5
2fe9374f16
All checks were successful
CI / Import/export fidelity gate (pull_request) Successful in 54s
CI / Lint, typecheck, test (pull_request) Successful in 4m25s
CD / Build and push images (push) Successful in 17s
Release / Build release images and notes (push) Successful in 1m18s
CD / Smoke tests against Test (push) Successful in 1m18s
CI / Build container images (push) Has been skipped
CI / Import/export fidelity gate (push) Successful in 59s
CI / Build container images (pull_request) Successful in 3m49s
CI / Auth e2e pack (pull_request) Successful in 6m47s
CD / Deploy to Test (push) Successful in 11s
CD / Promote to Int (push) Successful in 11s
Release / Release-candidate operations QA (push) Successful in 45s
Prod deploy / Deploy the released images to Prod (push) Successful in 15s
CI / Lint, typecheck, test (push) Successful in 4m36s
CI / Auth e2e pack (push) Successful in 6m54s
- Tutorial K19: neue Sektion „Excalidraw — Skizzen wie von Hand" mit
Nadias Bühnenplan-Beispiel (konzerte-live); Intro fünf→sechs Plugins.
- Tutorial K18: fünf→sechs Standard-Plugins.
- Site-Admin-Guide (en+de): Referenzliste + Build-Namensliste +
Build-Hinweis (~16-MiB-ZIP aus npm).
- plugin-architecture.md: Referenz-Eintrag excalidraw (npm-Library-
Spielart des Bundled-App-Pfads, {scene, svg}).
- developer/extending (en+de): Excalidraw als zweite Bundled-App-Variante.
Holt die in #136 zugesagten Doku-Ergänzungen nach. Screenshot für K19
folgt nach dem CSP-Deploy (damit die Handschrift korrekt rendert).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0155v2aT8AG1kZDQEZiCLBWC
154 lines
6.4 KiB
Markdown
154 lines
6.4 KiB
Markdown
# 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),
|
|
`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 | 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 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](../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).
|