Knowledge Storage System (KSS)

The Knowledge Storage System is a self-hosted notebook for teams who keep technical notes and want those notes to become knowledge. People write pages out of blocks, together and offline if need be, and link those blocks to each other and to terms from established ontologies. KSS turns the pages into a knowledge graph that can be explored and queried. It runs on your own server with Docker Compose.

What it does

• Writes pages together: blocks of text, code, diagrams, images, video, files, web pages, checklists, chemistry and graph views, edited by several people at once and offline, merged without conflicts when they reconnect.
• Links knowledge: a block can mention, use or answer another block, a page, a concept of the workspace or a term from ontologies such as ChEBI; a relation rail draws the links beside the page.
• Builds a knowledge graph from every page, which the graph explorer shows and SPARQL queries.
• Proposes links: a language model of your choice suggests entities and relations, limited by the ontologies and their shapes; people review the suggestions before they enter the graph.
• Keeps web pages: a web page block browses a page through the server and can freeze it into a snapshot that stays as it was.
• Organises and moves pages: folders, links between pages, and page archives to export and import.
• Is administered in the browser: workspace members and policies, and for administrators the server settings, user accounts and a history of changes.

Three rules shape the design:

• Your notes stay on your server. The language model is one you run or choose; a workspace sends page content to a model outside your network only if its owner allows that.
• The model proposes, people decide. Nothing the model suggests enters the graph without review, and ontology terms always come from the ontologies themselves.
• Other sites' pages are kept apart. Browsed web pages run on a host name of their own, with no access to your session or your data.

The interface and the handbook are available in English, German and Spanish.

Requirements

• Linux with Docker and the Compose plugin, version 2.24 or newer, and git
• just, the command runner the maintenance recipes use (recommended)
• Two DNS names for the server: one for KSS, one for browsed web pages (for example kss.example.org and web.example.org)
• Optional: an OpenAI-compatible language model endpoint (vLLM or Ollama) for proposing links, and a Keycloak realm for single sign-on

Nothing else is installed on the host: the installer runs in a container, and the images build KSS, its web client and the handbook.

Installation

git clone ssh://git@fj16.bastler.space:223/markusw/kss.git
cd kss
git checkout release-1.1        # or a newer release tag
./install.sh

The installer asks for:

• the address of KSS and of the web page origin;
• the reverse proxy: KSS's own Caddy with automatic HTTPS on ports 80 and 443, or your existing Caddy, Traefik, nginx, Apache, HAProxy, Nginx Proxy Manager, Envoy, Kong, Cloudflare Tunnel or lighttpd, for which it writes the configuration;
• the language model's address, model and key (optional);
• Keycloak sign-in (optional);
• whether to start now.

It writes .env with new secrets, the compose override, the sync key pair and the proxy configuration, then builds and starts the containers and asks for the first administrator. Re-running it is safe: it shows the current values, keeps the secrets and the lines you added to .env, and backs up every file it changes. To install without questions:

# answers.toml: each key is the name of a question
public_url = "https://kss.example.org"
web_url = "https://web.example.org"
proxy_mode = "A"
acme_email = "ops@example.org"
start = true

./install.sh --answers answers.toml

The handbook's installation page explains every question, the proxy modes and what a proxy must allow.

Running

When the installer has started KSS, check it and sign in:

curl https://kss.example.org/api/health    # {"ok": true, "db": true, "graphService": true}

Open https://kss.example.org and sign in with the administrator account. Then:

1. Under Workspaces, type a New workspace name and click Create. This loads the ontologies into the workspace's graph in the background.
2. In the workspace, Create page and start writing; New folder groups pages.
3. Give people access: through Keycloak, or as local accounts under Server settings → Users, then as members on the workspace's Settings page.

Day-to-day commands:

Command	What it does
just prod-up	build and (re)start the stack after a change to .env or an upgrade
just install	re-run the installer to change the configuration
just logs [service]	follow the logs
just manage <command>	run a Django management command, e.g. createsuperuser
just chebi-structures	once: build the ChEBI index that identifies drawn chemical structures
just proxy-check	validate the generated proxy configuration with the proxy's own image

just --list shows every recipe. Back up the database, the uploaded files, .env and infra/keys/ as the handbook's backup page describes.

Documentation

The handbook covers using and running KSS in English, German and Spanish. Every installation serves it at /docs/ (the Handbook link in the app bar); the sources are in handbook/, and just docs-dev serves them on their own.

• Getting started, guides and concepts for people who write in KSS
• Administration: installation, configuration, sign-in, language models, server settings, backup and maintenance
• Reference: block types, keyboard shortcuts, configuration variables, SPARQL, glossary
• KSS-design-spec.md: the design specification, the source of truth
• docs/decisions/: milestone summaries and decision records; docs/spikes/: spike reports
• RUN.md: the operational runbook for development and production
• FRONTEND_DESIGN.md: the web client's visual language

Development

The development stack runs on http://localhost:8080; the full procedure is in RUN.md. It needs Docker with Compose, just, uv, pnpm (Node ≥ 22), Rust ≥ 1.85 and openssl; on WSL Ubuntu, bootstrap-wsl.sh installs the user-space tools.

just deps              # uv sync, pnpm install, cargo fetch
just dev               # dev keys and .env, then build and start the stack
just seed              # demo workspace: alice (owner), bob (editor), carol (viewer); password: password
just dev-mockllm       # the deterministic mock language model (needed by some e2e specs)
pnpm --filter web dev  # Vite dev server on http://localhost:5173 (proxies /api and /sync)
just test              # pytest, vitest, cargo test, the handbook generator
just lint              # ruff + pyright, eslint + tsc, fmt + clippy
just e2e               # Playwright against the running stack

Layer	Technology
CRDT / sync	Loro, Loro Protocol over WebSocket; a Rust sync server (axum, tokio, sqlx)
Web client	React, TypeScript and Vite (PWA), ProseMirror, CodeMirror 6, Cytoscape.js, Ketcher, RDKit.js
App server	Django and Django Ninja; jobs with Procrastinate
Graph	FastAPI and pyoxigraph, one Oxigraph store per workspace
Database	PostgreSQL 16
Edge	Caddy

Licence

Copyright © 2026 Markus Walther

The Knowledge Storage System is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed without any warranty. If you run a modified version as a network service, the licence requires you to offer its users the modified source.