- TypeScript 98.2%
- CSS 1.4%
- JavaScript 0.2%
- Dockerfile 0.2%
|
|
||
|---|---|---|
| .claude/skills/release | ||
| docker | ||
| docs | ||
| e2e | ||
| handbook | ||
| prisma | ||
| src | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| Dockerfile | ||
| eslint.config.mjs | ||
| GLOSSARY.md | ||
| LICENSE | ||
| lingui.config.ts | ||
| linguiMacroPlugin.mjs | ||
| next.config.ts | ||
| package-lock.json | ||
| package.json | ||
| playwright.config.ts | ||
| playwright.handbook.config.ts | ||
| prisma.config.ts | ||
| README.md | ||
| rolldown.handbook.config.mjs | ||
| rolldown.restore.config.mjs | ||
| tsconfig.json | ||
| vitest.config.mts | ||
kataba
Open, visual documentation. Step-by-step guides with annotated photos, organised in a category tree — self-hosted, for one organisation.
Handbook · Features · Quickstart · Development · Architecture · Contributing
About
kataba is open-source software for visual, step-by-step instructions — repair guides, assembly instructions, standard operating procedures, anything that is best explained with a photo and an arrow pointing at the right screw.
Its layout is inspired by the repair guides on iFixit (which run on Dozuki); the visual design, texts and assets are kataba's own. Each kataba instance belongs to exactly one organisation and is self-hosted.
Features
- Step-by-step guides — each step has an optional title, up to three 4:3 photos, a list of step lines and free-form rich text.
- Annotated photos — mark areas on a photo with rectangles and circles. Every annotation belongs to a coloured step line and takes its colour, so text and image always point at the same thing.
- Structured step lines — coloured bullets or icon lines (caution, note, reminder), indented up to two levels.
- Category tree of any depth — guides live in exactly one category; children are sorted alphabetically or manually, per category. Categories and guides get cover images or coloured tiles.
- Drafts and publishing — guides are drafts until published; edits to published guides go live immediately. Admins can restore deleted guides.
- Visibility that's easy to reason about — content is
publicorinternal(signed-in only); the most restrictive value along the category chain wins, everywhere: listings, search and image delivery. - Ownership and wiki mode — authors edit their own guides; an owner can open a guide in wiki mode so every author may work on it.
- Single sign-on — sign in via Authentik (OIDC); roles (
viewer,author,admin) come from identity-provider groups and are checked against the database, so demotions take effect immediately. - Full-text search across guides and pages, filtered by what the reader may see.
- A menu in the titlebar — admins link categories, guides, pages or other addresses; each visitor sees only what they may open.
- Multilingual UI — English and German, translated with gettext catalogs. Light and dark mode, with a freely chosen accent colour that is adjusted for contrast.
- Export, import and backup — guides move between instances as ZIP packages; admins download a backup of the whole instance and restore it into a new one.
- Simple self-hosting — run it with Node.js or as a Docker image; images on local disk behind a guarded media route, no object storage or extra services required.
Tech stack
| Area | Technology |
|---|---|
| Framework | Next.js 16 (App Router), React 19, TypeScript |
| Styling | Tailwind CSS 4 with semantic theme tokens |
| Database | MariaDB via Prisma 7 |
| Authentication | Auth.js (JWT sessions) with Authentik as OIDC provider |
| Rich text | Editor.js, rendered by kataba's own allow-listing renderer |
| Images | sharp for variants |
| i18n | Lingui with .po catalogs |
| Testing | Vitest and Playwright |
Handbook
The kataba handbook documents everything about using and running kataba:
- the User handbook: reading guides, and writing them as an author;
- the Administration handbook: managing categories, pages, the menu and settings, and operating an instance: installation, Docker, configuration, Authentik and roles, updating and backup and restore.
Quickstart with Docker Compose
kataba is published on Docker Hub as mikognn/kataba. The example setup in docker/ runs it together with MariaDB; it signs in against an existing Authentik:
cd docker
cp .env.example .env # fill in DB_PASSWORD, AUTH_URL, AUTH_SECRET and the Authentik values
docker compose up -d --build
Put a TLS-terminating reverse proxy in front of port 3000. The handbook explains running with Docker, every environment variable and setting up Authentik.
Development
Development happens on the host, with Node.js, a MariaDB and an Authentik application; Docker is for running kataba, not for working on it (ADR-0014). Set it up as in the handbook's installation, then start the development server instead of building:
npm install
cp .env.example .env && npx auth secret # then fill in .env
npx prisma migrate deploy
npm run dev # http://localhost:3000
| Command | Purpose |
|---|---|
npm run dev |
Start the development server |
npm run build / npm start |
Build and serve a production build |
npm run build:nodb |
Build like the Docker image, without a database, into .next-nodb: fails if a page reaches the database while prerendering |
npm run lint |
Lint with ESLint |
npm run typecheck |
Type-check with tsc |
npm test |
Run the unit tests (Vitest) |
npm run e2e |
Run the end-to-end tests (Playwright) |
npm run i18n:extract |
Extract UI strings into the .po catalogs |
npm run build:restore |
Bundle the restore command into dist/restore.mjs |
npm run restore -- <backup.zip> |
Restore a backup into an empty instance (see Backup and restore) |
npm run handbook:screenshots |
Regenerate the handbook's screenshots (see Working on the handbook) |
Translations
The UI is translated with Lingui (gettext .po catalogs, English source text as msgids; ADR-0007). After adding or changing UI strings, run npm run i18n:extract, fill in the German msgstrs in src/locales/de/messages.po, and commit the catalogs. Compiled catalogs are generated by npm run i18n:compile, which runs automatically before dev and build.
Guide content itself is not translated.
End-to-end tests
npm run e2e runs the Playwright tests in e2e/ against a production build on port 3100. They use their own database, kataba_e2e on the server and with the credentials of DATABASE_URL (or E2E_DATABASE_URL, whose database name must end in _e2e), and their own upload directory .e2e/uploads. Every run migrates and empties that database. Create it once as a database admin:
CREATE DATABASE kataba_e2e;
GRANT ALL PRIVILEGES ON kataba_e2e.* TO 'kataba'@'localhost';
The first run downloads Chromium if needed with npx playwright install chromium. Tests sign in without Authentik: they mint the Auth.js session cookie with the test server's secret for seeded users (an admin, two authors and a viewer, e2e/users.ts).
Working on the handbook
The handbook lives in handbook/ and is built with Zensical, pinned in handbook/requirements.txt. It is a Python tool and stays out of the Node project; run it with uv:
cd handbook
uv run --no-project --with-requirements requirements.txt zensical serve # preview on http://localhost:8000
uv run --no-project --with-requirements requirements.txt zensical build --strict # build into handbook/site/, failing on broken links
Pages are Markdown files in handbook/docs/; new pages go into the nav in handbook/zensical.toml. Document a change to the app in the same pull request. The handbook is published with each release (ADR-0024).
Screenshots
The handbook's screenshots are generated, not taken by hand. npm run handbook:screenshots seeds the e2e database (see End-to-end tests) with an example instance, a makerspace with categories, annotated guides, a draft, versions and pages (e2e/handbook/seed/), builds kataba and starts it on port 3200, and photographs it with Playwright in light mode, in English, at 1280 × 800 and in the Europe/Berlin time zone (e2e/handbook/*.shots.ts). The PNGs land in handbook/docs/assets/screenshots/ and are committed, so building the handbook needs neither the app nor a database. Reference them from a page as e.g. .
Regenerate them, and commit the changed PNGs, whenever a change to the app alters what a screenshot shows. Each shot keeps its file name across runs, so pages never need updating for a rerun; a new screenshot is a new shoot(…, "<name>") in a *.shots.ts file. The run empties the e2e database, so it cannot run at the same time as npm run e2e.
Architecture
kataba keeps its design decisions written down:
GLOSSARY.md— the domain language: guide, step, step line, annotation, effective visibility, wiki mode and more. Code, UI and issues use these terms.docs/adr/— Architecture Decision Records, for example:- One instance serves one organisation
- Most restrictive visibility wins
- Every annotation belongs to one step line
- Images are stored on local disk and served through a guarded route
- Transactions run under READ COMMITTED, serialised by parent-row locks
- Docker is a deployment option; development stays on the host
src/
├── app/ Next.js routes: categories (c/), guides, search, admin, media
├── annotations/ steps/ stepImages/ guides/ categories/ domain modules
├── auth/ permissions/ sign-in, roles, access rules
├── richText/ Editor.js storage and renderer
├── images/ image variants and media access
├── i18n/ locales/ Lingui setup and catalogs
├── guidePackages/ backups/ guide export/import, instance backup and restore
└── theme/ settings/ search/ components/
prisma/ schema and migrations
docker/ Compose example and container entrypoint
e2e/ Playwright tests
docs/adr/ Architecture Decision Records
handbook/ user and administration handbook (Zensical)
Roadmap
- Tool and part lists
- Prerequisites
- Comments
- Videos
- Translation of guide content
Contributing
Contributions are welcome. Issues and pull requests live on the project's Forgejo repository.
- Development happens on the
developmentbranch; please branch from it and open pull requests against it. - Use one feature branch per issue, e.g.
feature/42-short-description. - Use the terms from
GLOSSARY.md; write code, comments and file names in English. - Before opening a pull request, make sure
npm run lint,npm run typecheckandnpm testpass, andnpm run build:nodbtoo if you changed what a page loads. - Larger design decisions deserve an ADR in
docs/adr/.
License
kataba is released under the MIT License. © 2026 Michael Ochmann