On this page
Extend Core at explicit boundaries¶
Register an application or observer¶
Install the Django extension package in the affected process environments
and add its app name to CONTEXTBASE_EXTENSIONS. Core registers it in
Django and mounts its optional urls after the Core routes. For public
HTTP paths outside the shipped matchers, add a Caddy rule and call the
route through the gateway.
Extension settings ·
Caddy matchers
Declare integrations in the app’s extension module.
Set
MIDDLEWAREto dotted class or factory paths. Request middleware must support async calls.Set
PROVIDERSto a factory path. The loader calls it after Django setup, passes the process role and expects a tuple of Dishka providers. To replace a binding, mark it as an override and add its exact key to the host allowlist. Core rejects a second replacement of that key. Provider loader
Set CONTEXTBASE_OBSERVERS to comma-separated dotted paths to classes
or factories that take no arguments. An observer receives events such as
query completion, model calls, ingestion stages and task events. It runs
inline, so keep it short and delegate I/O.
Observer interface
For detailed traces, override QueryTraceSink explicitly through a DI
provider. This binding is independent of the observer settings. Apply
visibility and masking policy in the trace consumer.
Trace interface
Check the installed extension and actual consumer¶
Run Django checks and migrations in the target installation. Startup rejects a missing configured app. System checks report unusable middleware, apps and observers. Test the extension through its actual routes, worker and browser consumers. If it serves requests and tasks, verify both DI containers. For changes to a shared contract, verify Enterprise or another affected extension on the exact Core candidate before adopting it.
For a built-in Core node, update its configuration, validation, execution and compatibility together. The installed node catalogue defines the available operations. Node catalogue · Search and answers · Processing and indexing