-
v1.0.0 Stable
released this
2026-11-02 20:20:59 +01:00 | 161 commits to master since this releaseThe first release of kataba — open, visual documentation: step-by-step guides with annotated photos, organised in a category tree, self-hosted for one organisation.
Features
Content
- Category tree of any depth with category pages and admin management (#6); categories get a description and an image (#41)
- Manual child order for subcategories and guides, alphabetical by default (#40)
- Guides — create, read, publish and delete; drafts and published guides, edits to published guides go live immediately, admins can restore deleted guides (#22, ADR-0008)
- Steps with their own edit route and a step list (#23)
- Step lines — coloured bullets and icon lines (caution, note, reminder), indented up to two levels (#24)
- Step images — upload, 4:3 crop and re-crop, image variants, served through a guarded media route (#25, #36, ADR-0006)
- Annotations — rectangle and circle outlines on step images, each belonging to a step line and taking its colour, highlighted in the reading view (#26, ADR-0011)
- Cover images for guides; without one, a coloured tile (#29)
- Full-text search across guides, filtered by what the reader may see (#33)
Access
- Sign-in with Auth.js and Authentik (OIDC); roles
viewer,authorandadminderived from Authentik groups and checked against the database (#4, ADR-0009) - Visibility
publicorinternal; the most restrictive value along the category chain wins — in listings, search and image delivery (#20, ADR-0002) - Ownership and wiki mode: authors edit their own guides; owners can open a guide to all authors (#27, ADR-0003)
Interface
- Visual theme with semantic tokens, light and dark mode, logo and tiles (#16, ADR-0010)
- Freely chosen accent colour, adjusted for contrast in light and dark mode (#32, ADR-0012)
- Guide editor with the guide's properties in a sidebar (#28)
- Admin settings page — instance name, session lifetime, accent colour, default language (#31)
- Translated UI in English and German with Lingui/gettext (#34, ADR-0007), and a per-user interface language (#44)
- Titlebar with a user menu and centred search (#48)
Operations
- Docker image built from the Next.js standalone output, and an example Compose setup with MariaDB; pending migrations are applied on container start (#50, ADR-0014)
Fixes
- Rich text is kept when a form is sent before Editor.js has loaded (#45)
- No more deadlocks between parallel step and image saves: transactions run under READ COMMITTED behind guide row locks (#46, ADR-0013)
mysql://connection strings are converted tomariadb://for the driver adapter
Quality and documentation
- End-to-end tests with Playwright against their own database (#35), unit tests with Vitest
- Domain glossary (
GLOSSARY.md) and 14 Architecture Decision Records indocs/adr/ - README as a full project introduction, with screenshots
Installation
Requires Node.js, MariaDB and an Authentik OIDC application. See the README for setup with Node.js or Docker:
git clone --branch v1.0.0 https://git.mike-ochmann.de/MassiveDynamic/kataba.git cd kataba/docker cp .env.example .env # fill in docker compose up -d --buildNot in this release
Tool and part lists, difficulty and time estimates, prerequisites, revisions and working copies, comments, PDF export, videos and translation of guide content.
Downloads
-
Source code (ZIP)
1 download
-
Source code (TAR.GZ)
1 download