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.

ContextBase0.1.0

Search the documentation