Claude Fable 5
eeb0ef6794
All checks were successful
CD / Build and push images (push) Successful in 1m9s
CD / Deploy to Test (push) Successful in 10s
CD / Smoke tests against Test (push) Successful in 1m10s
CD / Promote to Int (push) Successful in 11s
CI / Lint, typecheck, test (push) Successful in 4m7s
CI / Build container images (push) Has been skipped
CI / Auth e2e pack (push) Successful in 5m34s
CI / Import/export fidelity gate (push) Successful in 47s
Seven audience-targeted documents (English first, German translation to follow), linked from the README and a new docs/manual/ index: - docs/features.md — public-facing feature overview: what Dorfteich can do and why that matters - docs/manual/user-guide.md — everyday use: editor, wikilinks, labels, search, comments, watches/digests, import/export, settings - docs/manual/pond-admin-guide.md — pond configuration: members/roles, access rules incl. label scoping and public pages, labels, comment policy, plugins, API/MCP opt-ins, files, export - docs/manual/site-admin-guide.md — instance administration: wizard, settings, quotas, uploads, API/MCP switches, legal pages, plugins, users, and the system panel (jobs/backups/audit/storage) - docs/manual/api-guide.md — example-driven public-API walkthrough (tokens, reading, writing through the collab-safe path, labels, comments, error semantics) - docs/manual/mcp-guide.md — connecting AI assistants: switches, token scopes, Claude Code one-liner, mcp-remote bridge, tool table, audit and safety properties - docs/developer/extending.md — plugin development (sandbox contract, SDK, block plugins, bundled apps/fullscreen, shipping) and core contributions (stack, dev environment, gates, house rules) README: documentation index, repository-layout rows for docs/manual and docs/developer, and the stale "architecture phase" status brought up to reality. All relative links verified. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwZ4jR4KFAPvpjWevfUGX1
133 lines
5.5 KiB
Markdown
133 lines
5.5 KiB
Markdown
# Site-admin guide
|
|
|
|
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), `section-styles-basic` (colored callouts).
|
|
|
|
### 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).
|