On this page
Work on a local checkout¶
Start the components you need¶
Start Docker. Create a private config/.env from
the template and set development credentials.
For UTF-8 text on a local filesystem, set EXTRACTOR_BACKEND=local and
FILE_STORAGE_BACKEND=local in that file.
Run this block from the repository root.
contextbase_dev() {
docker compose --project-directory . -f compose/docker-compose.yml \
-f compose/docker-compose.override.yml "$@"
}
contextbase_dev up -d --wait db pgbouncer redis
contextbase_dev run --rm --build web /bin/sh /code/docker/django/admin.sh \
python manage.py migrate --noinput
contextbase_dev up -d --wait web worker beat
curl --fail 'http://localhost:8000/health/?format=json'
The base Compose file sends ordinary
database traffic through PgBouncer. admin.sh uses the direct route.
The development override
mounts the source for the API, worker and scheduler. To try the product
with a sample corpus, use quickstart.
Run the web UI¶
Start with a running backend and the supported Node version. Install the locked dependencies and start Next.js from the repository root.
npm --prefix frontend ci
cd frontend
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000 npm run dev
Open http://localhost:3000. If you change the frontend origin, add its
full address to the backend’s FRONTEND_ORIGINS. Without an API address
set at build time, the client uses the browser’s current origin, as in the
packaged gateway. Frontend setup
Choose the tools declared by the checkout¶
For host-side checks use the declared Python, Poetry and system packages, and Node. Install the dependencies for the components you are checking.
poetry sync
npm --prefix frontend ci
npm --prefix sdk/typescript ci
uv --directory sdk/python sync --frozen
Repository instructions · Backend conventions · Frontend conventions · Contribution guide
Run checks at the level of the change¶
Set up the disposable PostgreSQL and PgBouncer profile with a separate native volume. Assign tests their own Compose project, ports, database, Redis queues and file storage. With the test environment ready, run the API test for metadata filters in search.
DJANGO_ENV=development poetry run pytest -n 0 --no-cov \
tests/test_apps/test_main/test_api/test_document_search_filter.py
For changes to the application, its tests, or shared contracts, builds and CI, run the full gate with a direct administrative DB route and a Redis broker.
RUNNER="poetry run" ./docker/django/ci.sh
The full gate checks both SDKs and requires 100% line and branch coverage.
For frontend changes, also run npm run verify from frontend/. Choose
the checks for standalone SDK or documentation changes from the
quality gate.
Record the command, exit status and exact revision checked for review.