README
¶
Keep your knowledge close.
A small, self-hosted, Markdown-first wiki for documentation.
Kumbuka gives you a focused place to write, organize, search, and share documentation. It runs as a single Go application backed by PostgreSQL and includes authentication, revision history, search, media, collaboration, and administration.
The same binary can also publish Markdown as a read-only static documentation site without PostgreSQL or a running Kumbuka server.
Plugin development
Create, test and build Go/WASI plugins with the Kumbuka Plugin SDK and CLI. First-party plugins live in kumbuka-me/plugins; bundled and installed packages use the same public API and sandboxed runtime.
Screenshots
Documentation dashboard
Markdown editor
Quick start
Start Kumbuka with Docker Compose:
docker compose -f deploy/compose.yaml up -d
By default, Kumbuka is available at:
http://localhost:8080
On a fresh database, open Kumbuka and create the first administrator through the setup page.
For production deployments, authentication, Kubernetes, static sites, and other configuration, see the documentation.
Common settings
Environment variables use the KUMBUKA__ prefix.
| Setting | Default | What it changes |
|---|---|---|
KUMBUKA__LISTEN_ADDRESS |
127.0.0.1:8080 |
Address and port Kumbuka listens on. |
KUMBUKA__PUBLIC_URL |
http://localhost:8080 |
Externally visible URL of the Kumbuka installation. |
KUMBUKA__DATABASE_URL |
— | PostgreSQL connection URL. |
KUMBUKA__LOCAL_LOGIN |
false |
Enables the local recovery login alongside the configured authentication mode. |
See the configuration guide for all settings and authentication options.
Documentation
The full documentation is published at:
License
Kumbuka is licensed under the Apache License, Version 2.0.
Static-site plugins
Static builds use a project-level .kumbukaplugins file to pin the plugin packages that the site may use. The file is independent from Kumbuka's plugins.lock: plugins.lock pins packages bundled into the Kumbuka distribution, while .kumbukaplugins pins dependencies of one static content project.
format = 1
[[plugin]]
id = "me.kumbuka.mermaid"
repository = "kumbuka-me/plugins"
tag_prefix = "mermaid/v"
asset = "mermaid"
version = "1.0.1"
[[plugin]]
id = "com.example.chart"
repository = "example/kumbuka-chart"
tag_prefix = "v"
asset = "kumbuka-chart"
version = "2.3.0"
repository is a GitHub owner/repository, tag_prefix is prepended to the version to form the release tag, and asset is the base name of <asset>-<version>.kumbukaplugin and its .sha256 file. Matching bundled packages are reused directly; other packages are verified and cached below the operating system's user cache directory.
Manage the file with:
kumbuka plugins list
kumbuka plugins sync
kumbuka plugins add \
--id com.example.chart \
--repository example/kumbuka-chart \
--plugin-version 2.3.0
kumbuka plugins remove --id com.example.chart
kumbuka build reads all declared package manifests first, analyzes the Markdown using each module's declarative usage rules, adds transitive plugin dependencies, and starts only that selected package set. Unused declared WASM plugins are therefore not compiled or initialized, and unused browser assets are not copied into the generated site. Modules without usage rules are intentionally treated as global and are loaded whenever their plugin is declared.
License
Licensed under the Apache License 2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
kumbuka
command
|
|
|
internal
|
|
|
ascii
Package ascii contains predicates for the ASCII character classes used by Kumbuka.
|
Package ascii contains predicates for the ASCII character classes used by Kumbuka. |
|
cli
Package cli defines Kumbuka's command tree and binds command-line flags to application operations.
|
Package cli defines Kumbuka's command tree and binds command-line flags to application operations. |
|
httpresponse
Package httpresponse writes shared HTTP response formats used across transport layers.
|
Package httpresponse writes shared HTTP response formats used across transport layers. |
|
icons
Package icons exposes the icon catalogs used by the Kumbuka interface.
|
Package icons exposes the icon catalogs used by the Kumbuka interface. |
|
mirror
Package mirror exports the PostgreSQL-backed Kumbuka state as a deterministic, Git-friendly directory tree without changing the database source of truth.
|
Package mirror exports the PostgreSQL-backed Kumbuka state as a deterministic, Git-friendly directory tree without changing the database source of truth. |
|
pdf
Package pdf sends standalone page documents to an external PDF renderer.
|
Package pdf sends standalone page documents to an external PDF renderer. |
|
plugin
Package plugin defines Kumbuka's in-process module contracts.
|
Package plugin defines Kumbuka's in-process module contracts. |
|
plugin/wasm
Package wasm adapts untrusted WASI reactors to Kumbuka's module contracts.
|
Package wasm adapts untrusted WASI reactors to Kumbuka's module contracts. |
|
pluginbrowser
Package pluginbrowser defines the core-owned, isolated browser module surface.
|
Package pluginbrowser defines the core-owned, isolated browser module surface. |
|
plugincap
Package plugincap adapts already-authorized application data to public wire values.
|
Package plugincap adapts already-authorized application data to public wire values. |
|
pluginproject
Package pluginproject manages reproducible plugin dependencies for static Kumbuka projects.
|
Package pluginproject manages reproducible plugin dependencies for static Kumbuka projects. |
|
pluginusage
Package pluginusage defines derived page metadata used to select source-aware plugin modules without making Markdown depend on persistence details.
|
Package pluginusage defines derived page metadata used to select source-aware plugin modules without making Markdown depend on persistence details. |
|
renderprofile
Package renderprofile collects opt-in render timing diagnostics without coupling the Markdown renderer and WASM runtime to each other's logging.
|
Package renderprofile collects opt-in render timing diagnostics without coupling the Markdown renderer and WASM runtime to each other's logging. |
|
revision
Package revision compares persisted page revisions for display.
|
Package revision compares persisted page revisions for display. |
|
secrets
Package secrets encrypts sensitive application settings with a deployment-managed key.
|
Package secrets encrypts sensitive application settings with a deployment-managed key. |
|
serve
Package serve configures and runs the database-backed Kumbuka server.
|
Package serve configures and runs the database-backed Kumbuka server. |
|
Package plugins supplies bundled plugin distribution bytes, not a separate plugin runtime.
|
Package plugins supplies bundled plugin distribution bytes, not a separate plugin runtime. |
|
scripts
|
|
|
generate-icons
command
Command generate-icons creates Kumbuka's Lucide icon picker catalog.
|
Command generate-icons creates Kumbuka's Lucide icon picker catalog. |
|
test
|
|
|
browser/plugins-admin-server
command
A loopback-only, in-memory fixture for the plugin administration browser test.
|
A loopback-only, in-memory fixture for the plugin administration browser test. |