Skip to content

Local development

The repository has three useful local layers:

  1. Python runtime and policy code.
  2. Docker services for DataHub, OpenTelemetry, and Jaeger.
  3. The browser console for manual checks.

Install development tools

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev,bootstrap,docs]"

The docs extra installs the MkDocs Material theme. The build output goes to build/docs-site/, which is ignored by git.

Run the test suite

.venv/bin/python -m pytest
.venv/bin/python -m compileall -q src scripts deploy
git diff --check

The optional Jaeger environment test needs a running local trace backend:

THEMIS_OTEL_CHECK=1 .venv/bin/python -m pytest -q tests/test_otel_environment.py

Build the documentation

.venv/bin/mkdocs build --strict

Preview it locally:

.venv/bin/mkdocs serve

The production build uses the canonical URL https://azharizz.blog/themis/docs/.

Rules for changes

  • Keep secrets in ignored environment files.
  • Keep SQL read-only at the agent boundary.
  • Do not add Apollo data to a public Themis fixture.
  • Do not use useEffect in the React surface. The current console is vanilla JavaScript and must keep that boundary.
  • Add a contract test for a new public route.
  • Run a browser smoke test after UI changes.
  • Record a new runtime receipt for claims about live behavior.