README
¶
Keep your knowledge close.
A small, self-hosted, Markdown-first wiki for documentation.
Kumbuka is the PostgreSQL-backed server and web application. It includes authentication, revision history, search, media, collaboration, administration, themes, and the plugin runtime.
Project-oriented tooling lives in the separate Kumbuka CLI. Use kumbuka-cli for static-site builds, Markdown mirrors, and .kumbukaplugins management.
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.
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.
The server binary has no subcommands. Running kumbuka starts the server directly:
kumbuka \
--database-url 'postgres://USER:PASS@HOST:5432/kumbuka?sslmode=disable' \
--listen-address 0.0.0.0:8080 \
--public-url http://localhost:8080
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__PLUGIN_UPDATE_CHECK_INTERVAL |
15m |
Checks the first-party plugin catalog on this interval; 0 disables scheduled checks while manual checks remain available. |
KUMBUKA__READ_ONLY |
false |
Blocks state-changing application requests while keeping reads and authentication available. |
KUMBUKA__ALLOW_USER_REGISTRATION |
— | Overrides whether unknown OIDC or trusted-proxy identities may create accounts. |
KUMBUKA__LOCAL_LOGIN |
false |
Enables the local recovery login alongside the configured authentication mode. |
KUMBUKA__TRUSTED_GROUP_HEADERS |
X-Forwarded-Groups,X-Auth-Request-Groups |
Trusted-proxy group headers used with the trusted-proxy authentication override. |
KUMBUKA__TRUSTED_ADMIN_GROUP |
— | Trusted-proxy group that grants administrator access with the authentication override. |
KUMBUKA__OIDC_GROUP_CLAIM |
groups |
OIDC group-membership claim used with the OIDC authentication override. |
KUMBUKA__OIDC_ADMIN_GROUP |
— | OIDC group that grants administrator access with the authentication override. |
The CLI registration override is strict: use --allow-user-registration=true or --allow-user-registration=false.
See the documentation for all settings and authentication options.
Reusable packages
Runtime packages that are intentionally shared with the standalone CLI live under pkg/. Server-only HTTP, authentication, routing, service composition, and deployment details remain under internal/.
The public packages are implementation building blocks for Kumbuka tooling; the server remains the primary application in this repository.
CLI
Install or build kumbuka-me/cli for offline/project commands:
kumbuka-cli build --help
kumbuka-cli mirror --help
kumbuka-cli plugins --help
License
Licensed under the Apache License, Version 2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
kumbuka
command
|
|
|
internal
|
|
|
credential
Package credential contains reusable local-credential policy and hashing primitives.
|
Package credential contains reusable local-credential policy and hashing primitives. |
|
flags
Package flags parses deployment-level configuration for the Kumbuka server.
|
Package flags parses deployment-level configuration for the Kumbuka server. |
|
httpresponse
Package httpresponse writes shared HTTP response formats used across transport layers.
|
Package httpresponse writes shared HTTP response formats used across transport layers. |
|
pdf
Package pdf sends standalone page documents to an external PDF renderer.
|
Package pdf sends standalone page documents to an external PDF renderer. |
|
pluginupdate
Package pluginupdate discovers and downloads first-party Kumbuka plugin updates.
|
Package pluginupdate discovers and downloads first-party Kumbuka plugin updates. |
|
portable
Package portable defines Kumbuka's versioned, instance-portable archive format.
|
Package portable defines Kumbuka's versioned, instance-portable archive format. |
|
secrets
Package secrets encrypts sensitive application settings with a deployment-managed key.
|
Package secrets encrypts sensitive application settings with a deployment-managed key. |
|
pkg
|
|
|
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. |
|
icons
Package icons exposes the icon catalogs used by the Kumbuka interface.
|
Package icons exposes the icon catalogs used by the Kumbuka interface. |
|
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. |
|
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. |
|
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. |