Skip to content
DashboardWebsite

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.

ToolPurpose
Docker with ComposeRuns the local stack, builds, and tests in containers
git, make, python3bootstrap.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.

Terminal window
git clone [email protected]:opentremor/opentremor.git && cd opentremor
./bootstrap.sh # clones every required OpenTremor-* component beside this repository

Components use path dependencies such as ../OpenTremor-x, so keep them side by side as bootstrap.sh does.

Terminal window
make up-dev # API, dashboard, docs, MongoDB, and task scheduler with live reload

The 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.

From the workspace root, run the core test suite with all thirteen packs installed:

Terminal window
make test

This 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:

Terminal window
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.

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 dashboard

Formatting changes files. This command mounts the core repository as writable:

Terminal window
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/'

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.

AreaChecks
Platformuv sync --locked, verifies opentremor_core is absent, then runs pytest
CoreTests once with zero packs and once with all thirteen packs installed
Packs, task scheduler, and MCPuv sync --locked and pytest for each component
Dashboardnpm ci, lint, TypeScript check, and build
Docsnpm ci and build; requires all twenty module manifests to compose
DeploymentsHelm lint and render for each values profile; validates all three Compose files
Terraform providergo 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.

Renovate opens dependency update pull requests on Monday mornings (UTC), as configured in .github/renovate.json5. It discovers manifests across the workspace.

UpdatePull requestMerge behavior
Python, npm, and Go minor or patch updatesGrouped by ecosystemRenovate merges after checks pass and the version is three days old
Container image minor or patch updatesOne grouped pull requestA person merges it
Development tools in mise.tomlOne grouped pull requestA person merges it
OSV security advisoriesOne pull request per advisoryFollows the ecosystem’s merge rules
GitHub ActionsOne grouped pull request, including major updatesA person merges it
Major updates for other dependenciesListed on the Dependency Dashboard until approvedA person approves and merges it
Lockfile refreshesWeekly pull requestA 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.mod directive.
  • 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.

Docs live in the sibling OpenTremor-docs directory. From the workspace root:

Terminal window
make up-dev # serves docs with live reload at /docs
make docs # builds the docs site in a container and checks module composition

Allow 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.

Terminal window
DOCS_ALLOWED_HOSTS=docs.example.com npm run dev -- --host

This 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.