Claude Fable 5
04e21a0aac
All checks were successful
CD / Build and push images (push) Successful in 3m50s
CI / Lint, typecheck, test (push) Successful in 4m2s
CI / Build container images (push) Has been skipped
CD / Deploy to Test (push) Successful in 11s
CD / Smoke tests against Test (push) Successful in 1m14s
CD / Promote to Int (push) Successful in 13s
CI / Auth e2e pack (push) Successful in 5m37s
CI / Import/export fidelity gate (push) Successful in 47s
AI clients talk to the instance directly at /api/mcp — under the /api/ path (deviation from the issue's literal /mcp) so every existing reverse proxy already routes it; no deployment changes anywhere. - Transport: official @modelcontextprotocol/sdk server, STATELESS — each POST builds a fresh server+transport pair, no session store, replicas stay trivial; GET/DELETE answer 405. Auth per PAT bearer (#104 tokens), per-token rate limit (429 + Retry-After). - Own switches, independent of REST: instance mcp.enabled (admin settings, default off; off = 404, feature invisible) + pond setting mcpEnabled (pond-settings toggle, default off) — pinned independent in both directions by tests. - Tools (thin wrappers over the #104 services, same permission gates, audit-logged writes): list_ponds, list_pages, read_page, search, create_page, update_page (replace semantics through the collab-owned restore path — open editors converge), add_comment, list_labels, set_page_labels (exact replace), export_pond (link to the REST ZIP). Tool errors carry the api error codes; results carry stable slugs/ids. MCP resources stay the documented stage-2 stretch goal. - Deliberately on the SDK's low-level Server API with a hand-written tool table (mcp-tools.ts): the typed registerTool generics drove tsc out of memory in a program this size; manual Zod validation keeps the wire behavior explicit. - PublicApiService exposure filtering parameterized ('api' | 'mcp', shared pondFeatureEnabled helper) — one implementation, two switches. - Docs: "Connect Claude Code / MCP clients" section in public-api.md (claude mcp add one-liner + mcp-remote bridge for stdio clients). Verification: 8-test e2e pack driving the real MCP SDK client over Streamable HTTP against a listening api (initialize + tools/list, switch independence in both directions, anonymous/garbage 401, opt-in 404 semantics, page roundtrip incl. restore-NOTIFY, labels/comments, read scope blocked from writes with scope_required); live check through the web proxy against the seeded stack (tools list, create, read, update, search — LIVE CHECK PASSED); full api suite 61/61 files green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwZ4jR4KFAPvpjWevfUGX1
186 lines
8.2 KiB
Markdown
186 lines
8.2 KiB
Markdown
# Self-hosting Dorfteich
|
|
|
|
Everything you need to install, run, update, and back up your own Dorfteich
|
|
with Docker — this guide is the complete contract: if a step here does not
|
|
work, that is a bug (issue #88).
|
|
|
|
> Docs are English-only by decision (issue #88): the product UI is fully
|
|
> localized (de/en), operator documentation is not — one authoritative text
|
|
> beats two drifting ones.
|
|
|
|
## Requirements
|
|
|
|
- Docker Engine with the Compose plugin (`docker compose version` ≥ 2.20).
|
|
- 2 GB RAM, ~2 GB disk for images plus room for your content and backups.
|
|
- A domain pointing at the host — TLS via your own reverse proxy **or** the
|
|
bundled `caddy` profile (below).
|
|
- Outbound SMTP relay (optional at install time: the setup wizard can
|
|
configure it later, or you skip mail entirely at first).
|
|
|
|
## Install
|
|
|
|
1. Create a directory and fetch the two reference files from the repository
|
|
(`deploy/compose/`): `docker-compose.yml`, `.env.example` — plus
|
|
`Caddyfile` if you want the `caddy` profile.
|
|
|
|
```sh
|
|
mkdir dorfteich && cd dorfteich
|
|
# copy docker-compose.yml, .env.example (and Caddyfile) here
|
|
cp .env.example .env && chmod 600 .env
|
|
```
|
|
|
|
2. Edit `.env` — the minimum:
|
|
- `POSTGRES_PASSWORD`, `COLLAB_TOKEN_SECRET`: long random strings
|
|
(`openssl rand -base64 32`).
|
|
- `IMAGE_PREFIX=gitea.101010.cloud/stwaidele/dorfteich` and `TAG`:
|
|
releases are semver tags (`v1.2.3`); until the first public release,
|
|
`test` tracks the latest verified build.
|
|
- `APP_BASE_URL=https://wiki.example.com` — must be exactly what
|
|
browsers will use; e-mail links and the CSRF origin check derive
|
|
from it.
|
|
- Every other variable is documented inline in `.env.example` with its
|
|
default and effect; nothing outside that file configures the stack.
|
|
|
|
3. Start:
|
|
|
|
```sh
|
|
docker compose up -d # behind your own reverse proxy
|
|
docker compose --profile caddy up -d # or with the bundled TLS ingress
|
|
```
|
|
|
|
- **Own proxy:** route `/*` → `127.0.0.1:$WEB_PORT`, `/api/*` →
|
|
`$API_PORT`, `/collab*` → `$COLLAB_PORT` (**WebSocket upgrade
|
|
required** on `/collab`).
|
|
- **`caddy` profile:** set `DOMAIN=wiki.example.com` in `.env`; Caddy
|
|
publishes 80/443 and obtains Let's Encrypt certificates automatically
|
|
(both ports must be reachable from the internet). `DOMAIN=localhost`
|
|
issues an internal-CA certificate — for smoke tests only.
|
|
|
|
4. Open `https://your-domain/` — a fresh instance shows the **first-run
|
|
setup wizard**.
|
|
|
|
## First-run wizard
|
|
|
|
Six steps, all in the browser (issue #80/#81): language → the Site-Admin
|
|
account (created verified, you are signed in immediately) → instance name
|
|
and default language → SMTP relay (**Save runs a live test** and sends a
|
|
test mail to you; _Skip_ leaves mail unconfigured — sign-up verification
|
|
will not work until an admin adds a relay) → registration mode
|
|
(open/closed) → summary + finish. The wizard locks itself permanently on
|
|
completion. Until it completes, the api answers everything but the wizard
|
|
and health endpoints with `503 setup_required` — that is not an error.
|
|
|
|
Unattended installs skip the wizard by pre-seeding: set the
|
|
`SETUP_ADMIN_*` variables in `.env` before the first start (see
|
|
`.env.example`).
|
|
|
|
## Updating
|
|
|
|
```sh
|
|
# edit .env: TAG=v1.3.0
|
|
docker compose pull && docker compose up -d
|
|
```
|
|
|
|
Database migrations run automatically at api start. Release notes flag
|
|
releases with a `migration` label and any manual steps. **Downgrade
|
|
window: one minor release** — `TAG` back + `pull` + `up -d` is supported
|
|
one step back; further back, restore the backup taken before the update
|
|
instead (the nightly sidecar gives you one at most 24 h old).
|
|
|
|
## Backups & restore
|
|
|
|
Enabled by default (ADR 0015): the `backup` sidecar dumps the database and
|
|
archives the uploads/plugins volumes nightly at `BACKUP_TIME` onto the
|
|
`backups` volume, prunes by `BACKUP_RETENTION_DAYS`, writes `status.json`,
|
|
and — with `BACKUP_MAIL_TO` set — mails you on failure.
|
|
|
|
- On-demand backup: `docker compose run --rm -e BACKUP_RUN_ONCE=1 backup`,
|
|
or the **Back up now** button under _Admin → System_.
|
|
- List sets: `docker compose exec backup ls /backups`
|
|
- Restore: `./restore.sh <backup-id>` (fetch `deploy/backup/restore.sh`
|
|
next to your compose file) — details in
|
|
`docs/operations/restore-runbook.md`.
|
|
|
|
### Off-host copies to a Nextcloud
|
|
|
|
Get the backups off the host — a backup on the same disk protects against
|
|
mistakes, not against losing the host. Any Nextcloud you can reach works
|
|
as the target; configure it entirely in the admin UI (_Admin → System →
|
|
Backups_):
|
|
|
|
1. In Nextcloud, create an **app password** for the account that should
|
|
hold the backups (Settings → Security → Devices & sessions).
|
|
2. In Dorfteich, enable _Upload backups to Nextcloud_, enter the plain
|
|
Nextcloud address (e.g. `https://cloud.example.com`), the username, the
|
|
app password and a folder, and use **Test connection** — it verifies
|
|
the credentials and creates the folder. The password is kept in the
|
|
secret store on the `secrets` volume, never in the database.
|
|
3. Pick the upload schedule (after every nightly backup, weekly, or manual
|
|
only) and the retention for both sides. After each successful upload,
|
|
old remote bundles beyond the retention are pruned — never the newest
|
|
one.
|
|
|
|
Each upload is ONE self-contained archive
|
|
(`dorfteich-backup-<id>.tar.gz` = database dump + files archive +
|
|
manifest) — everything needed to rebuild the instance after total loss.
|
|
`readyz` warns (`backup_remote` check) when the off-host copy grows stale,
|
|
and upload failures alert through the backup failure mail.
|
|
|
|
**Restore from the admin UI:** _Admin → System → Backups → Restore_ lists
|
|
local and Nextcloud sets. Restoring asks you to re-type the backup id,
|
|
then the instance enters maintenance mode (everything answers 503 plus a
|
|
status page), restores itself through the backup sidecar, and restarts.
|
|
If the app itself is gone, use the operator path in
|
|
`docs/operations/restore-runbook.md` instead — it documents fetching a
|
|
bundle from Nextcloud by hand.
|
|
|
|
## Public REST API
|
|
|
|
Scripts and integrations can talk to the instance through a
|
|
token-authenticated API at `/api/public/v1`, and MCP clients (Claude Code
|
|
and friends) through the built-in MCP endpoint at `/api/mcp` — both off by
|
|
default, enabled per instance and per pond. Details, token walkthrough,
|
|
and the OpenAPI document: [public-api.md](public-api.md).
|
|
|
|
## Health & troubleshooting
|
|
|
|
- `GET /api/v1/readyz` is the instance's own diagnosis. HTTP 503 =
|
|
database/migrations broken (the instance cannot serve). HTTP 200 with
|
|
`"status":"degraded"` = a warning-level check: `converter`/`renderer`
|
|
down (import/export/PDF degrade, everything else works) or `backup`
|
|
stale (last success older than 26 h). Each check carries a `detail`.
|
|
Monitor set: `deploy/monitoring.md`.
|
|
- Logs: `docker compose logs api` (or `web`, `collab`, `backup`, `db`) —
|
|
structured JSON, rotated by Docker.
|
|
- **Proxy pitfalls:** editor never connects / "offline" although the page
|
|
loads → the proxy does not upgrade WebSockets on `/collab`. All
|
|
mutations fail with 403 `csrf_origin_mismatch` → `APP_BASE_URL` does not
|
|
match the URL in the browser (scheme and host must be identical).
|
|
E-mail links point at the wrong host → same variable.
|
|
- Wizard reappears after a restart → the database volume was not
|
|
persisted; never run without the `db-data` volume.
|
|
- `docker compose ps` shows `unhealthy` → that container's liveness check
|
|
fails; a _degraded_ readyz alone never marks containers unhealthy and
|
|
never restarts anything.
|
|
|
|
## Building from source instead
|
|
|
|
Clone the repository and build the images locally — the reference compose
|
|
carries the build contexts already:
|
|
|
|
```sh
|
|
docker compose build && docker compose up -d
|
|
```
|
|
|
|
Same layout, same volumes; you trade the registry pull for a local
|
|
toolchain (Node 22 build stages run inside Docker, nothing else needed).
|
|
|
|
## Verified install
|
|
|
|
The guide is verified by a scripted clean-machine run
|
|
(`deploy/self-hosting-verify.sh`): fresh directory, reference compose +
|
|
`.env.example` only, `--profile caddy` with an internal-CA certificate,
|
|
asserting that the wizard answers over TLS. Run it yourself on any Docker
|
|
host — it uses its own compose project name and high ports, then removes
|
|
everything.
|