Skip to content

Installation

boudou edited this page Nov 4, 2026 · 11 revisions

Installation

You need Docker, uv and Git. If you don't have Python 3.12, uv installs it.

flowchart LR
    a["1. Clone and<br/>copy .env"] --> b["2. docker compose up -d<br/>Postgres on 5433"]
    b --> c["3. uv sync"]
    c --> d["4. Dry-run a preset"]
    d --> e["Connect a client"]
Loading

1. Get the code

git clone https://github.com/boudou/StrataKB.git
cd StrataKB
cp .env.example .env

Change the two passwords in .env (DB_PASSWORD, READONLY_DB_PASSWORD) and the matching database URLs, unless the server only runs on your own machine.

2. Start the database

docker compose up -d

This starts PostgreSQL 16 with pgvector on port 5433, so it doesn't collide with a PostgreSQL already running on 5432. On the first start it creates three schemas from db/:

File Creates
01_init.sql Layers, documents, chunks with their vectors, users and the audit log
02_learning.sql Interactions, feedback, and the synonyms and rewrites the server has learned
03_readonly_role.sql The strata_readonly role used by the SQL inspection tools

The scripts run only when the data volume is empty. To start again from scratch, run docker compose down -v. This deletes all data.

3. Install the server

uv sync

The first search downloads two models into your Hugging Face cache: the embedding model, about 420 MB, and the reranker, about 90 MB. After that, StrataKB works offline unless you turn on OpenAI embeddings or query rewriting.

4. Check that it runs

uv run python scripts/apply_preset.py examples/sepa/preset.yaml --dry-run

A dry run parses the example SEPA preset without touching the database. Leave out --dry-run to build the layer. Then connect a client and ask "What does reject reason AC04 mean?".

Development install

uv sync --extra dev
uv run pytest                  # the integration tests need the database running
uv run ruff check src tests

See CONTRIBUTING.md before opening a pull request.

Clone this wiki locally