Development Setup
OpenTremor has independently packaged components in sibling repositories. This page covers workspace setup and development across those components, with a focus on OpenTremor-core, the server.
Prerequisites
Section titled “Prerequisites”| Tool | Purpose |
|---|---|
| Docker with Compose | Runs the local stack, builds, and tests in containers |
git, make, python3 | bootstrap.sh clones the components; make provides workspace commands |
The workspace Makefile runs builds and tests in containers, so you do not need to install Python, uv, or Node on your machine.
Get the workspace
Section titled “Get the workspace”./bootstrap.sh # clones every required OpenTremor-* component beside this repositoryComponents use path dependencies such as ../OpenTremor-x, so keep them side by side as bootstrap.sh does.
Run the development stack
Section titled “Run the development stack”make up-dev # API, dashboard, docs, MongoDB, and task scheduler with live reloadThe stack is available at http://localhost:8080: / routes to the API, /dashboard to the dashboard, and /docs to the documentation site. The development stack bind-mounts the components so edits reload the service that owns them.
The local configuration provides a default superadmin login. See Configuration Reference — auth for configuration details.
Run the tests
Section titled “Run the tests”From the workspace root, run the core test suite with all thirteen packs installed:
make testThis target starts a temporary MongoDB and runs the tests in the uv container.
To run another Python component’s tests, mount the workspace so its sibling path dependencies are available. For example:
docker run --rm -v "$PWD":/ws:ro -w /ws/OpenTremor-platform \ -e UV_PROJECT_ENVIRONMENT=/tmp/venv \ ghcr.io/astral-sh/uv:0.12.22-python3.14-trixie-slim \ sh -c 'uv sync -q --frozen && uv run --no-sync pytest -q -p no:cacheprovider'Core also supports a zero-packs installation. Run uv sync without --group internal; pack-dependent tests are skipped. This does not provide full test coverage.
Project layout
Section titled “Project layout”OpenTremor-core/├── configs/│ ├── opentremor-core.yaml Standalone Docker stack with MongoDB│ ├── opentremor-core-local.yaml Local development with MongoDB on localhost:27017│ ├── opentremor-core-prod.yaml Production configuration│ └── opentremor-core-tests.yaml Test suite configuration├── src/│ ├── opentremor_core/ Python server package│ ├── tests/ Test suite│ ├── tools/ CLI utilities│ └── server.py Uvicorn entry point├── pyproject.toml├── Dockerfile└── docker-compose.yaml Core and MongoDB; no packs or dashboardFormat Python code
Section titled “Format Python code”Formatting changes files. This command mounts the core repository as writable:
docker run --rm -v "$PWD/OpenTremor-core":/src -w /src -e UV_PROJECT_ENVIRONMENT=/tmp/venv \ ghcr.io/astral-sh/uv:0.12.22-python3.14-trixie-slim \ sh -c 'uv run --only-group dev black src/ && uv run --only-group dev isort src/'Continuous integration
Section titled “Continuous integration”Component repositories run their own CI. The workspace repository also runs a cross-component gate when it receives an update from a component, on its own pushes and pull requests, and daily. The gate uses a self-hosted runner and runs its checks in one job.
The integration gate requires a registered self-hosted runner. Without one, jobs queue. The runner needs Docker for the Compose config checks and enough disk for the Python, Node, and Go toolchains installed into its tool cache.
| Area | Checks |
|---|---|
| Platform | uv sync --locked, verifies opentremor_core is absent, then runs pytest |
| Core | Tests once with zero packs and once with all thirteen packs installed |
| Packs, task scheduler, and MCP | uv sync --locked and pytest for each component |
| Dashboard | npm ci, lint, TypeScript check, and build |
| Docs | npm ci and build; requires all twenty module manifests to compose |
| Deployments | Helm lint and render for each values profile; validates all three Compose files |
| Terraform provider | go build, go vet, and go test |
The integration gate does not filter by changed paths. A change in one component can affect another component’s tests.
Update dependencies
Section titled “Update dependencies”Renovate opens dependency update pull requests on Monday mornings (UTC), as configured in .github/renovate.json5. It discovers manifests across the workspace.
| Update | Pull request | Merge behavior |
|---|---|---|
| Python, npm, and Go minor or patch updates | Grouped by ecosystem | Renovate merges after checks pass and the version is three days old |
| Container image minor or patch updates | One grouped pull request | A person merges it |
Development tools in mise.toml | One grouped pull request | A person merges it |
| OSV security advisories | One pull request per advisory | Follows the ecosystem’s merge rules |
| GitHub Actions | One grouped pull request, including major updates | A person merges it |
| Major updates for other dependencies | Listed on the Dependency Dashboard until approved | A person approves and merges it |
| Lockfile refreshes | Weekly pull request | A person merges it |
Renovate writes lockfiles using Node 24, npm 11.19.0, and uv 0.12.22, as set under constraints. Keep those values aligned with the workflow toolchain versions.
The configuration also pins or ignores selected updates:
- MongoDB remains below version 8 because MongoDB 8.x does not start on Linux 6.19 or later (SERVER-121912).
- Python base image major and minor updates wait for approval and must stay aligned with the Python version range and CI.
- Go language version updates wait for approval and must stay aligned with the
go.moddirective. - OpenTremor images and workspace packages are ignored; release-please manages their versions.
Commits use chore(deps) and ci(deps). The chore section is hidden in the release-please changelog, so dependency updates do not add a changelog entry.
Work on the documentation
Section titled “Work on the documentation”Docs live in the sibling OpenTremor-docs directory. From the workspace root:
make up-dev # serves docs with live reload at /docsmake docs # builds the docs site in a container and checks module compositionAllow another hostname for the docs dev server
Section titled “Allow another hostname for the docs dev server”Astro’s dev server uses Vite, which blocks unrecognised Host headers. If a proxy or custom hostname returns Blocked request. This host ("…") is not allowed., set DOCS_ALLOWED_HOSTS to a comma-separated list of hostnames. Set it to * to allow all hosts.
DOCS_ALLOWED_HOSTS=docs.example.com npm run dev -- --hostThis variable applies to npm run dev. Production serves static build output and does not need it. The workspace development Compose file sets default allowed hosts for its docs service.