open, visual documentation https://pages.mike-ochmann.de/kataba/
  • TypeScript 98.2%
  • CSS 1.4%
  • JavaScript 0.2%
  • Dockerfile 0.2%
Find a file
2026-11-06 15:21:23 +01:00
.claude/skills/release Builds without a database are checked before a release (#151) 2026-11-06 14:54:52 +01:00
docker SMTP server in the settings instead of environment variables (#99) 2026-11-06 13:55:18 +01:00
docs Builds without a database are checked before a release (#151) 2026-11-06 14:54:52 +01:00
e2e Wider reference search in the inline toolbar (#152) 2026-11-06 15:17:23 +01:00
handbook Release of Version 1.3.0 2026-11-06 15:20:41 +01:00
prisma Problem reports on guides, with optional email to the owner (#99) 2026-11-06 12:26:05 +01:00
src Wider reference search in the inline toolbar (#152) 2026-11-06 15:17:23 +01:00
.dockerignore Builds without a database are checked before a release (#151) 2026-11-06 14:54:52 +01:00
.env.example SMTP server in the settings instead of environment variables (#99) 2026-11-06 13:55:18 +01:00
.gitignore Builds without a database are checked before a release (#151) 2026-11-06 14:54:52 +01:00
CHANGELOG.md Wider reference search in the inline toolbar (#152) 2026-11-06 15:17:23 +01:00
CLAUDE.md Configure agent skills: Forgejo issue tracker, triage labels, domain docs 2026-11-01 16:23:51 +01:00
Dockerfile Instance backup with restore by CLI (#109) 2026-11-05 17:51:27 +01:00
eslint.config.mjs Builds without a database are checked before a release (#151) 2026-11-06 14:54:52 +01:00
GLOSSARY.md References to guides, categories and pages in rich text (#101) 2026-11-06 14:20:58 +01:00
LICENSE Clean up project scaffold (#2) 2026-11-01 16:23:51 +01:00
lingui.config.ts Review fixes for the Lingui setup (#3) 2026-11-02 12:58:28 +01:00
linguiMacroPlugin.mjs Instance backup with restore by CLI (#109) 2026-11-05 17:51:27 +01:00
next.config.ts Builds without a database are checked before a release (#151) 2026-11-06 14:54:52 +01:00
package-lock.json Release of Version 1.3.0 2026-11-06 15:20:41 +01:00
package.json Release of Version 1.3.0 2026-11-06 15:20:41 +01:00
playwright.config.ts End-to-end tests with Playwright (#15) 2026-11-02 13:41:51 +01:00
playwright.handbook.config.ts Handbook screenshots generated with Playwright from a seeded example instance (#140) 2026-11-06 11:23:56 +01:00
prisma.config.ts Clean up project scaffold (#2) 2026-11-01 16:23:51 +01:00
README.md Builds without a database are checked before a release (#151) 2026-11-06 14:54:52 +01:00
rolldown.handbook.config.mjs Handbook screenshots generated with Playwright from a seeded example instance (#140) 2026-11-06 11:23:56 +01:00
rolldown.restore.config.mjs Instance backup with restore by CLI (#109) 2026-11-05 17:51:27 +01:00
tsconfig.json Builds without a database are checked before a release (#151) 2026-11-06 14:54:52 +01:00
vitest.config.mts Instance backup with restore by CLI (#109) 2026-11-05 17:51:27 +01:00

kataba logo

kataba

Open, visual documentation. Step-by-step guides with annotated photos, organised in a category tree — self-hosted, for one organisation.

License: MIT Next.js TypeScript Prisma MariaDB Docker Hub

Handbook · Features · Quickstart · Development · Architecture · Contributing


A kataba guide step: a photo with coloured rectangle and circle annotations, next to the step lines in matching colours

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 public or internal (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:

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. ![The guide editor](../assets/screenshots/editor.png).

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:

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 development branch; 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 typecheck and npm test pass, and npm run build:nodb too 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