Skip to content
Terminal

Local development

You need Bun 1.3.14, Docker with Compose v2, and FFmpeg on your host. The simulator uses a native canvas package; Bun installs the matching package for your platform.

From the repository root:

Terminal window
bun install
bun dev:infra
bun dev

The infrastructure command starts Postgres, MinIO, and SRS in Docker, creates the blob bucket, and applies database migrations. The development command runs Mainframe, its media indexer, the simulator, and Vite on your host.

Surface Address
Terminal http://localhost:5173
Mainframe health http://localhost:8788/api/health
Simulator administration http://localhost:8787/admin
Media indexer health http://localhost:8789/api/health
This documentation http://localhost:4321/, after bun run docs:dev

Sign in to Terminal as operator@mainframe.local with password mainframe-operator. The development admin is admin@mainframe.local with password mainframe-admin. These accounts and known service keys are enabled by MAINFRAME_DEV_FIXTURES=1, which the development scripts set. Never enable that flag on staging or production.

Add a module

Section titled “Add a module”

Run optional modules in another terminal:

Command What it adds
bun dev:feeds Weather and radar-net
bun dev:detections Vision analysis; requires an OpenRouter key
bun dev:tak TAK; requires generated certificates
AUTO_OPERATOR_SERIAL_PREFIX=VNG bun dev:automation Suggestions for the development simulator fleet
bun dev:autel Autel; requires its broker and connection configuration

Use bun run deploy modules to inspect the server profile catalog. The local development scripts and the deployment launcher start different topologies; keep their ports and environment files separate.

Check and stop

Section titled “Check and stop”
Terminal window
bun run check
bun run check:smoke

The first command runs static checks and unit tests. The smoke suite needs the local stack running and exercises the browser. Stop the host processes with Ctrl-C. Run bun dev:infra down to stop the Docker infrastructure while preserving its data volumes.

If a service is already running, inspect it before starting another copy. Mainframe holds a database advisory lock so two Core instances cannot share the same database accidentally.