Skip to content

Latest commit

 

History

History
335 lines (222 loc) · 11.8 KB

SETUP_GUIDE.md

File metadata and controls

335 lines (222 loc) · 11.8 KB

Mooquant Setup Guide

Prerequisites

Mooquant is a monorepo with a React/Vite/Tauri frontend and a FastAPI Python backend. A normal local development setup requires Node.js and npm, Python, uv, Rust and the Tauri system prerequisites, QuestDB, and Moomoo OpenD.

For market and account data, Moomoo OpenD must be installed, running, authenticated, and reachable from the backend host. By default, the backend expects OpenD at 127.0.0.1:11111.

For time-series persistence, QuestDB must be running locally or reachable from the backend. The recommended local QuestDB HTTP endpoint is http://127.0.0.1:9000, and the recommended PostgreSQL-compatible PGWire endpoint is 127.0.0.1:8812.

Mooquant reads QuestDB connection settings from .env or process environment variables. QuestDB itself reads its own server settings from QuestDB’s server.conf. These two files are not automatically linked, so the credentials configured in QuestDB must match the credentials configured for Mooquant.

Node.js and npm

Install Node.js and npm before installing the frontend dependencies. Using nvm is recommended because it lets you install and switch Node.js versions per project.

See the official nvm repository for installation instructions:

https://github.com/nvm-sh/nvm

After installing nvm, install and use a suitable Node.js version.

nvm install --lts
nvm use --lts
node --version
npm --version

If this repository includes a .nvmrc file, use the version declared there instead.

nvm install
nvm use

uv and Python

Install uv for Python dependency management. On macOS, one common installation method is Homebrew.

brew install uv
uv --version

See the official uv installation guide for other installation methods:

https://docs.astral.sh/uv/getting-started/installation/#homebrew

Mooquant requires Python 3.14 or newer for the backend. You can install Python from the official Python macOS installer or use uv to install Python.

Official Python macOS downloads:

https://www.python.org/downloads/macos/

uv Python installation guide:

https://docs.astral.sh/uv/guides/install-python/

For a uv-managed Python installation, install Python with:

uv python install 3.14

Tauri prerequisites

Install the Tauri system prerequisites for your operating system before running the desktop shell. Tauri requires Rust and platform-specific system dependencies.

See the official Tauri prerequisites guide:

https://v2.tauri.app/start/prerequisites/

After installing Rust, confirm that Cargo is available.

rustc --version
cargo --version

QuestDB setup

Install QuestDB before launching the backend. On macOS, one common local setup is Homebrew.

brew install questdb
questdb start

See the official QuestDB quick start for Homebrew and other installation methods:

https://questdb.com/docs/getting-started/quick-start/#homebrew

For a Homebrew QuestDB installation on Apple Silicon macOS, the QuestDB configuration file is commonly located at:

/opt/homebrew/var/questdb/conf/server.conf

Configure QuestDB’s PostgreSQL wire protocol credentials and bind QuestDB to localhost for local desktop use:

# PostgreSQL wire protocol credentials used by Mooquant/FastAPI.
pg.user=your_user_name
pg.password=your_long_local_password

# Important for a local desktop app: do not expose PGWire to the LAN.
pg.net.bind.to=127.0.0.1:8812

# Optional: keep the QuestDB Web Console local-only as well.
http.net.bind.to=127.0.0.1:9000

After editing server.conf, restart QuestDB.

questdb stop
questdb start

The recommended local QuestDB endpoints are:

HTTP:       http://127.0.0.1:9000
PGWire:     127.0.0.1:8812
ILP/other:  http::addr=127.0.0.1:9000;

Mooquant does not read QuestDB’s server.conf file. Mooquant reads its own connection settings from .env or process environment variables. The values must match the QuestDB server configuration.

Moomoo OpenD setup

Install Moomoo OpenD from the official Moomoo OpenAPI download page:

https://www.moomoo.com/download/OpenAPI

Start Moomoo OpenD, sign in, and confirm that it is listening on the configured host and port. By default, Mooquant expects OpenD at:

Host: 127.0.0.1
Port: 11111

Before using live or real-account features, confirm your OpenD trading environment, account selection, permissions, and security-firm settings. The code includes defaults, but local configuration should always be reviewed before connecting to a real trading account.

Clone the repository

Clone the repository and enter the project directory.

git clone https://github.com/ta-ke-o/mooquant.git
cd mooquant

Project setup

Install the frontend dependencies from the repository root.

npm ci

This also installs the npm tooling used by the project scripts, including dotenv-cli if it is listed in package.json. The backend npm scripts use dotenv-cli to read the FastAPI host and port from .env.

Install the Python backend dependencies from the src-python directory.

cd src-python
uv sync
cd ..

Create a local .env file for Mooquant in the repository root. The values should match the QuestDB credentials configured in server.conf. The VITE_API_BASE_URL value is optional for the default local setup, but it is included here so that .env and .env.example use the same keys.

# Backend: QuestDB PGWire connection.
QUESTDB_PG_HOST=127.0.0.1
QUESTDB_PG_PORT=8812
QUESTDB_PG_USER=your_user_name
QUESTDB_PG_PASSWORD=your_long_local_password
QUESTDB_PG_DATABASE=qdb

# Backend: FastAPI bind address.
# Keep 127.0.0.1 for normal local desktop use.
MOOQUANT_API_HOST=127.0.0.1
MOOQUANT_API_PORT=8000

# Optional. The frontend defaults to http://127.0.0.1:8000 when unset.
VITE_API_BASE_URL=http://127.0.0.1:8000

# Optional. Enables CORS for the standalone Vite dev server at port 5173.
# Leave disabled for normal Tauri/local desktop use.
MOOQUANT_DEV_CORS=false

The .env.example file should contain the same keys with safe example values and no real password:

# Backend: QuestDB PGWire connection.
QUESTDB_PG_HOST=127.0.0.1
QUESTDB_PG_PORT=8812
QUESTDB_PG_USER=mooquant
QUESTDB_PG_PASSWORD=
QUESTDB_PG_DATABASE=qdb

# Backend: FastAPI bind address.
# Keep 127.0.0.1 for normal local desktop use.
MOOQUANT_API_HOST=127.0.0.1
MOOQUANT_API_PORT=8000

# Optional. The frontend defaults to http://127.0.0.1:8000 when unset.
VITE_API_BASE_URL=http://127.0.0.1:8000

# Optional. Enables CORS for the standalone Vite dev server at port 5173.
# Leave disabled for normal Tauri/local desktop use.
MOOQUANT_DEV_CORS=false

The application also supports a full QuestDB DSN override through QUESTDB_PG_DSN. If QUESTDB_PG_DSN is set, it takes precedence over the individual QUESTDB_PG_HOST, QUESTDB_PG_PORT, QUESTDB_PG_USER, QUESTDB_PG_PASSWORD, and QUESTDB_PG_DATABASE values.

QUESTDB_PG_DSN=postgresql://your_user_name:your_long_local_password@127.0.0.1:8812/qdb

The backend constructs a PostgreSQL-compatible DSN from the individual QuestDB environment variables in this format:

postgresql://<QUESTDB_PG_USER>:<QUESTDB_PG_PASSWORD>@<QUESTDB_PG_HOST>:<QUESTDB_PG_PORT>/<QUESTDB_PG_DATABASE>

Development hooks and secret scanning

This repository uses Lefthook for local Git hooks. The pre-commit hook runs formatters, linters, and BetterLeaks secret scanning against staged files.

BetterLeaks is not required to run Mooquant, but it is required if you use the repository’s Lefthook pre-commit workflow. If BetterLeaks is not installed, the pre-commit hook will fail when it reaches the BetterLeaks job.

Install BetterLeaks before committing changes:

brew install betterleaks

You can verify the installation with:

betterleaks version

The Lefthook pre-commit job scans staged files for accidentally committed secrets such as .env values, access tokens, account identifiers, password hashes, local credentials, logs, or generated data.

You can also run BetterLeaks manually against the working tree:

betterleaks dir . --redact --verbose

Or against Git history:

betterleaks git . --redact --verbose

A full directory or Git-history scan is best suited to release preparation because it can be slower and may include generated files if the working tree is not clean. Before publishing the repository, run BetterLeaks from a clean checkout and review any findings manually. Placeholder values in documentation may be acceptable, but real credentials, account IDs, trading password hashes, local .env values, logs, snapshots, and generated data should not be committed.

Running Mooquant

Start QuestDB if it is not already running.

questdb start

Start Moomoo OpenD and confirm that it is authenticated and listening at 127.0.0.1:11111, or update your local backend configuration if you use a different OpenD host or port.

Start the FastAPI backend from the repository root. For local development, use:

npm run fastapi:dev

This runs the backend from src-python using uv and FastAPI’s development server. The development server is intended for local development only. It may enable reload behavior and debugging output that should not be used when other machines can reach the backend.

For a non-debug local run, use:

npm run fastapi:run

Both backend scripts read MOOQUANT_API_HOST and MOOQUANT_API_PORT from .env. The recommended host is 127.0.0.1 for normal local desktop use. Do not bind the backend to 0.0.0.0 unless you intentionally need network access and understand the security implications.

In a separate terminal, run the Tauri desktop shell.

npm run tauri dev

The frontend uses http://127.0.0.1:8000 as the default backend API origin, so most local users do not need to change VITE_API_BASE_URL. Set VITE_API_BASE_URL only when the FastAPI backend is running on another host or port.

When using the standalone Vite dev server instead of Tauri, set MOOQUANT_DEV_CORS=true so the backend allows requests from http://localhost:5173 and http://127.0.0.1:5173. Leave this disabled for normal Tauri use.

npm run dev

A typical local development session uses QuestDB, Moomoo OpenD, the FastAPI backend, and either the Tauri desktop shell or the standalone Vite dev server.

Backend-first workflow

This project is intentionally FastAPI-first. The backend should be treated as a normal Python service that can be started, inspected, tested, and deployed independently of Tauri.

Tauri is not responsible for spawning the backend process. The backend is not currently packaged as a Tauri sidecar. This avoids hiding Python service behavior inside the desktop bundle and keeps API development straightforward. It also makes it easier to run backend tests, inspect logs, connect external tools, and use the same API from either the browser-based Vite frontend or the Tauri desktop shell.

Because the backend is not a Tauri sidecar, packaging the desktop shell does not automatically package or launch the Python API. A user running a packaged desktop build must still run the FastAPI backend and its dependencies separately unless a future release adds an installer or process supervisor.

API behavior

The frontend communicates with the backend through HTTP requests and Server-Sent Events. It loads dashboard snapshots from API endpoints such as /api/dashboard and /api/summary, and it subscribes to live streams for summary and table updates.

Live dashboard tables include positions, pending orders, historical orders, funds, quotes, and events. The backend also exposes chart, historical download, strategy tester, bot-log, and live-bot-related functionality.

The backend stores local dashboard data under the data directory by default. Watchlist data is stored at data/watchlist.json, and JSON snapshots are written under data/snapshots.