Developer Setup

QDash development starts from a local repository checkout and uses either DevContainer or Nix for the project toolchain.

Prerequisites

Required Tools

Tool	Version	Description
Docker	-	Container virtualization platform
Docker Compose	v2.24+	Management of multiple Docker containers
go-task	v3.41+	Task runner for development commands
uv	-	Python package manager

Optional Tools (for local development)

Tool	Version	Description
Python	3.10-3.12	Backend development
Bun	1.4.0+	Frontend package manager and runtime
Node.js	24+	Alternative frontend runtime

Clone the Repository

git clone https://github.com/oqtopus-team/qdash.git
cd qdash

A DevContainer can start without .env. Before running Qubex-backed calibration tasks, follow Operator Setup for .env and CONFIG_PATH configuration.

DevContainer

The recommended way to develop is using the DevContainer:

docker compose -f compose.devcontainer.yaml up -d

The DevContainer can start without a local .env; Docker Compose uses .env when present. The checked-in VS Code configuration runs its remote session as the vscode user so files created in the checkout remain writable from the host. Docker Compose direct sessions can still use root when needed.

On Linux, build the vscode user with the host UID and GID so files created in the checkout remain writable from both the host and the container:

LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) docker compose -f compose.devcontainer.yaml up -d --build

The container mounts /var/run/docker.sock so devcontainer users can run the local Docker Compose tasks from inside the workspace. In the default VS Code session, tools under /home/vscode/.local and agent configuration under /home/vscode/.claude and /home/vscode/.codex are persisted in Docker volumes, so they survive container rebuilds. Codex itself is installed under /opt/codex, which remains writable by the vscode user for CLI updates without being hidden by the persisted .local volume. Host-side deployment commands keep their Python environment and updater runtime state outside the checkout, so they do not reuse root-owned DevContainer artifacts.

Then attach to the container using VS Code's DevContainer extension or:

docker compose -f compose.devcontainer.yaml exec --user vscode devcontainer zsh

Check the Git identity inside the container before committing because host-level Git settings are not copied into the DevContainer automatically:

git config --global user.name
git config --global user.email

Set them in the container if either command is empty.

Nix Host Shell

Nix can provide the local CLI toolchain without starting the DevContainer. This is useful when you want to run Python tests, UI checks, or Docker Compose tasks from the host shell while keeping the service stack in Docker.

Install Nix with flakes enabled, then enter the development shell:

nix develop

The shell provides Python 3.11, uv, Bun, Node.js 24, go-task, Docker CLI/Compose, jq, PostgreSQL client tools, and the secret scanning tools used by the project. It also sets UV_PYTHON to the Nix-provided Python 3.11 so uv sync does not accidentally select Python 3.12 on macOS, where some workflow backend dependencies may fail to build. It does not start MongoDB, PostgreSQL, Prefect, API, or UI services by itself; use the existing Docker Compose tasks for those services.

After entering the Nix shell for the first time, install project dependencies:

task dev-local-setup

Then start the lightweight development stack:

task dev-local

This starts MongoDB, PostgreSQL, Prefect, the deployment service, and the user flow worker with Docker Compose, then runs the API and UI on the host. The UI is available at http://localhost:5714.

Stop the host API/UI processes and Docker Compose services:

task dev-local-down

Refresh Dependencies

The DevContainer installs Python, frontend, and Lefthook dependencies automatically during creation. To refresh dependencies manually, run:

task dev-local-setup

Run the Development Stack

task dev-local

This starts the supporting services in Docker Compose and runs the API and UI directly on the host. Use this flow when editing backend or frontend code frequently.

The component tasks are:

• task dev-services: start MongoDB, PostgreSQL, Prefect, deployment-service, and user-flow-worker
• task dev-api-local: run the FastAPI app on the host against Docker services
• task dev-ui-local: run the Next.js app on the host against the local API

Access Points

Service	URL
QDash UI	http://localhost:5714
API Documentation	http://localhost:5715/docs
Prefect Dashboard	http://localhost:4200
MongoDB Admin	http://localhost:8081

Use Developer Commands for linting, tests, builds, generation, and documentation tasks. Use Operator Setup when you need the full Compose deployment rather than the host-side development stack.

Secret Scanning Tools

DevContainer users are automatically set up with Betterleaks, Trufflehog, and Lefthook. For local development outside the DevContainer, install the tools manually:

macOS:

brew install betterleaks trufflehog lefthook

Linux:

Download binaries from GitHub Releases:

• Betterleaks Releases
• Trufflehog Releases
• Lefthook Releases

After installing the tools, enable the git hooks:

lefthook install

The pre-commit hook requires Betterleaks. Install it before enabling Lefthook; otherwise commits fail closed instead of bypassing the staged leak scan.