Prerequisites
- Bun — the runtime (
bun --version). - Docker — runs Postgres, and optionally Gitea. The test/dev flow requires it.
- git on your
PATH. - For IDA-based extractors: a licensed IDA install and uv. IDA is
auto-discovered; otherwise set
IDA_PATH.
Host install
bun install
bun run setup # boot Postgres (+ optional Gitea), apply migrations,
# and provision IDA extractor deps if IDA is installed
bun run dev # api + reactor + worker together → http://127.0.0.1:3000
# (or run them separately to scale workers: bun run api / reactor / worker)Open http://127.0.0.1:3000/. The API and the web UI share one origin — no separate frontend build. On first open the corpus is empty and the UI walks you through the first upload.
bun run setup is idempotent and prints exactly what to run next. It fails
fast with a clear message if Docker is missing, and degrades cleanly when IDA or Gitea are absent.Containers (full stack)
Build an image with Bun, the app, and the plugins, and run the API, reactor, and worker against the Compose Postgres:
docker compose --profile app up -d --build
# API + web UI on http://localhost:3000 (override with KE_API_HOST_PORT)The app profile keeps these out of the default docker compose up, so the bare
Postgres+Gitea dev flow is unaffected. The three services share a blob volume. The image does not bundle
IDA (licensed, host-specific) — to run IDA extractors, run the worker on a host with IDA, or mount
idat into the worker container and set IDA_PATH.
Configuration
All settings have working defaults; override with environment variables (Bun auto-loads a
.env file — copy .env.example). Configuration is validated at startup: a bad
value fails fast with a readable message, not a stack trace.
| Variable | Purpose | Default |
|---|---|---|
DATABASE_URL | Postgres connection | postgres://ke_simple:ke_simple@localhost:55432/ke_simple |
KE_API_HOST / KE_API_PORT | REST API + web UI bind | 127.0.0.1 / 3000 |
KE_WORKER_CONCURRENCY | default extractor concurrency | 1 |
IDA_PATH | IDA headless executable (enables IDA extractors) | auto-discovered |
KE_IDA_PYTHONPATH / KE_GIT_IDA_PATH | extra extractor PYTHONPATH / git-ida path | — / git-ida |
KE_GITEA_URL + KE_GITEA_TOKEN (+ KE_GITEA_USER) | hosted-repo transport (set together) | unset (disabled) |
Gitea (optional, automatic)
Corpus, upload, and search work without Gitea. Hosted repositories (create, push-projection,
build-from-selection) need it — and bun run setup already takes care of it: it starts the
dockerized Gitea, provisions an admin token, and writes KE_GITEA_URL /
KE_GITEA_TOKEN / KE_GITEA_USER into your .env, which
bun run dev loads automatically. Nothing else to do.
bun run setup # provisions Gitea + writes KE_GITEA_* to .env
bun run setup --no-gitea # skip Gitea entirelyDon't want Gitea? --no-gitea leaves it out; the corpus features are unaffected.