Handbook: administration handbook, operator content moved out of the README #139

Closed
opened 2026-11-06 09:59:45 +01:00 by miko · 1 comment
Owner

Part of #137
Depends on #138.

What

Write the Administration handbook: operating a kataba instance and the admin area of the app. The operator content moves out of README.md — the handbook becomes the single source.

Scope

Operating an instance (moved from the README, then extended where thin):

  • Requirements, installation with Node.js, database setup, applying the schema
  • Running with Docker / Docker Compose, notes on volumes and uploads
  • Configuration: all environment variables
  • Authentik (OIDC) setup, group → role mapping
  • Roles (viewer, author, admin)
  • Updates and migrations
  • Backup and restore (CLI restore into an empty instance, ADR-0023)

Admin area in the app:

  • Categories (tree, sorting, cover images/tiles, visibility)
  • Pages outside the tree and the home page
  • Titlebar menu
  • Settings: accent colour, other instance settings
  • Restoring deleted guides
  • Backup download

Use the domain terms from GLOSSARY.md.

README

Afterwards the README keeps: About, Features, Tech stack, a short Docker Compose quickstart, Development, Architecture, Roadmap, Contributing, License — plus prominent links into the handbook. Remove the moved sections (Getting started in detail, Configuration, Authentik, Roles, Backup and restore) instead of duplicating them.

Acceptance criteria

  • Every topic above has a page; nothing operator-relevant is lost from the README
  • README slimmed down and linking to https://pages.mike-ochmann.de/kataba/
  • zensical build --strict passes
Part of #137 Depends on #138. ## What Write the **Administration handbook**: operating a kataba instance and the admin area of the app. The operator content moves out of `README.md` — the handbook becomes the single source. ## Scope **Operating an instance** (moved from the README, then extended where thin): - Requirements, installation with Node.js, database setup, applying the schema - Running with Docker / Docker Compose, notes on volumes and uploads - Configuration: all environment variables - Authentik (OIDC) setup, group → role mapping - Roles (`viewer`, `author`, `admin`) - Updates and migrations - Backup and restore (CLI restore into an empty instance, ADR-0023) **Admin area in the app**: - Categories (tree, sorting, cover images/tiles, visibility) - Pages outside the tree and the home page - Titlebar menu - Settings: accent colour, other instance settings - Restoring deleted guides - Backup download Use the domain terms from `GLOSSARY.md`. ## README Afterwards the README keeps: About, Features, Tech stack, a short Docker Compose quickstart, Development, Architecture, Roadmap, Contributing, License — plus prominent links into the handbook. Remove the moved sections (Getting started in detail, Configuration, Authentik, Roles, Backup and restore) instead of duplicating them. ## Acceptance criteria - [ ] Every topic above has a page; nothing operator-relevant is lost from the README - [ ] README slimmed down and linking to `https://pages.mike-ochmann.de/kataba/` - [ ] `zensical build --strict` passes
Author
Owner

Done in #146: the administration handbook has one page per topic (categories, pages, menu, settings, import/restore of guides, backup/restore, installation, Docker, configuration, sign-in and roles, updating), and the README is slimmed down and links into the handbook.

Done in #146: the administration handbook has one page per topic (categories, pages, menu, settings, import/restore of guides, backup/restore, installation, Docker, configuration, sign-in and roles, updating), and the README is slimmed down and links into the handbook.
miko closed this issue 2026-11-06 11:41:34 +01:00
Sign in to join this conversation.
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
MassiveDynamic/kataba#139
No description provided.