Skip to content

Local development

Implemented

The development CLI and Compose paths exist; shared remote services still require their own provisioning.

Code and tests
Terminal window
./bin/kesita dev setup
./bin/kesita dev up

Use ./bin/kesita dev status to inspect the environment and ./bin/kesita dev logs to follow it. The CLI help is the command reference:

Terminal window
./bin/kesita dev --help
./bin/kesita dev up --help
flowchart LR
    CLI[kesita dev up] --> Host[Default<br/>Next.js on host]
    CLI --> Container[--mode container<br/>app in Compose]
    CLI --> Hybrid[--hybrid<br/>selected real dev services]
    Host --> Local[Local PostgreSQL, Azurite,<br/>workers and simulations]
    Container --> Local
    Hybrid --> Shared[Development Legal API<br/>and real model provider]

The default host mode gives the fastest frontend hot reload. Container mode runs the app with the rest of the Compose stack and is useful for image and networking parity. --hybrid is independent: it keeps product data local while sending legal requests to the deployed development Legal API and model requests to the real provider.

For hybrid development, copy infra/env/hybrid.env.example to the ignored infra/env/hybrid.env, fill only development credentials, then run:

Terminal window
./bin/kesita dev up app --hybrid
./bin/kesita dev doctor --hybrid

See Hybrid development for the service and authentication boundaries.

flowchart TB
    Supervisor[Kesita supervisor] --> App[Product app]
    Supervisor --> Compose[Local Compose dependencies]
    Compose --> ProductDB[(Product PostgreSQL)]
    Compose --> LegalDB[(Legal PostgreSQL)]
    Compose --> Blob[Azurite]
    Compose --> APIs[Product and Legal APIs]
    Compose --> Workers[Product and corpus workers]
    Compose --> Sim[Provider simulation]
    Separate[Separate targets] --> Site[Public site]
    Separate --> Docs[Docs site]

Start the public site with ./bin/kesita dev up site and docs with ./bin/kesita dev up docs. Simulated providers are the default and unmatched requests fail instead of reaching paid services.

Terminal window
./bin/kesita dev down
./bin/kesita dev reset

reset destroys disposable local databases and emulator uploads, then rebuilds fixtures. Never use it against shared, staging, or production resources.

If startup fails, run ./bin/kesita dev doctor, then inspect status and logs. Fix the first unhealthy dependency before restarting the full stack.