Developer Setup Guide

Welcome to the Business M Developer Guide. This runbook walks you through configuring your local development environment to run both our modular monolithic core and decoupled macroservice configurations.

1. Zero-Install Devcontainer Quickstart

The fastest way to get a localized demo running or to develop on native Linux is to use our pre-configured VS Code Dev Container. While native host setups are recommended for OS-agnostic builds (like compiling native Windows .exe or macOS .app/.dmg installers), the Dev Container provides a zero-install sandbox that comes pre-configured with all tools and background services.

Prerequisites for Dev Container

Docker (Desktop or Engine) installed and running.
VS Code with the Dev Containers extension installed.

Steps to Launch

Open in VS Code: Open the cloned repository root folder in VS Code.
Reopen in Container: When prompted, click Reopen in Container (or run Dev Containers: Reopen in Container from the Command Palette).
Automatic Provisioning: The container will build, configure itself, install dependencies, and run all background sidecars (Postgres, Redis, NATS, k3s) automatically.

Running the Server inside the Dev Container:

Monolithic (Indie) Mode:

m dev --procfile=monolith.devcontainer.Procfile --env-file=monolith.devcontainer.env --no-backend --port=8000

Distributed (Enterprise) Mode:

m dev --procfile=macroservices.devcontainer.Procfile --env-file=macroservices.devcontainer.env --port=8000 --no-backend

2. Native Host Setup (Recommended for packaging)

To develop across operating systems natively—which is required to build and package native Windows (.exe), macOS (.app/.dmg), and Linux (.deb) installers natively via Tauri—configure your native host machine directly:

2.1 Local Prerequisites

Verify that your development machine has the following tools installed:

Operating System: Linux, macOS, or Windows (All platforms natively supported for development, execution, and packaging).
Python 3.12+: Asynchronous runtime environment.
uv: Ultra-fast Python package and environment manager. Install uv.
Node.js LTS (v24): Required to compile frontends and Vite federation bundles.
pnpm: Required to manage node packages (npm install -g pnpm).
PostgreSQL LTS: Relational storage engine.

3. Workspace Initialization

3.1 Clone the Workspace

Clone the monorepo from GitLab and navigate to the workspace root:

git clone https://gitlab.com/castlecraft/business-m
cd business-m

3.2 Initialize Python Dependencies

Setting up your virtual environment and installing all package dependencies happens in a single command:

uv sync

This creates a unified .venv virtual environment in the workspace root and installs dependencies for all sub-libraries (libs/*) and applications (apps/*) in editable mode.

3.3 Virtual Environment Activation

Bash / Zsh (macOS/Linux):
Terminal window
```
source .venv/bin/activate
```
Fish Shell (macOS/Linux):
Terminal window
```
. ./.venv/bin/activate.fish
```
PowerShell (Windows):
Terminal window
```
.venv\Scripts\Activate.ps1
```
Command Prompt (Windows):
Terminal window
```
.venv\Scripts\activate.bat
```

3.4 Initialize Frontend Packages

Install workspace-wide node packages:

pnpm install

4. Provisioning the Engine Layer & Services (Local Host)

4.1 Quick Setup: Docker Compose Engine Stack

To simplify local host development, we package the entire localized infrastructure Engine Layer (including PostgreSQL, Redis, and NATS) into a single Docker Compose context.

To spin up all services instantly, run:

docker compose -f deploy/compose/dev/dev.compose.yml up -d

Manual database creation is not required.

Extensible & Pluggable Engines (e.g., TigerBeetle & Kurrent DB): High-performance infrastructure engines like TigerBeetle (used for double-entry financial ledger operations) and Kurrent DB (event-sourcing and immutable audit trails) are fully pluggable.

TigerBeetle & Kurrent DB Configuration: Choose between postgres and tigerbeetle/kurrent in config.py.

Running locally:

docker compose -f deploy/compose/dev/macroservices.compose.yml up -d tigerbeetle kurrentdb

4.2 Fallback: Native Host Service Deployment

If running Docker is a challenge on your development machine, you can run the engines natively on your host:

Install the Core Engines: PostgreSQL, Redis, and NATS.
Verify Ports: Ensure these native processes are active on their standard ports:
- PostgreSQL: 5432
- Redis: 6379
- NATS: 4222

5. Launching the Local Host Server

Launch the development orchestrator CLI specifying the desired local deployment track:

Option A: Monolithic (Indie) Mode

To run all modules inside a single process on your host:

m dev --procfile=monolith.Procfile --env-file=monolith.env --no-backend --port=8000

Option B: Distributed (Enterprise) Mode

To run domain services as decoupled out-of-process macroservices on your host:

m dev --procfile=macroservices.Procfile --env-file=macroservices.env --port=8000 --no-backend

Development Portal URL: http://localhost:5173

6. Standard Developer Workflows

The m CLI provides built-in code scaffolding templates.

6.1 Scaffolding New Components

Scaffold a new App:
Terminal window
```
m new app my_custom_app
```

Scaffold a new DocType model:

m new doctype MyFeatureSchema --app business_m

Scaffold a new frontend panel:
Terminal window
```
m new frontend my_custom_frontend
```

6.2 Running the Test Suites

To execute unit and integration test suites workspace-wide:

uv run pytest

To run localized tests within a specific sub-package:

cd libs/finance
uv run pytest

7. Code Style & Verification

We enforce quality and security standards across the codebase using the high-level verification commands provided by m studio CLI:

Code Formatting (ruff format):
Terminal window
```
m format
```
Linting & Style Checks (ruff lint):
Terminal window
```
m lint
```
Static Type Checking (mypy / typecheckers):
Terminal window
```
m typecheck
```
Security Vulnerability Audits (bandit):
Terminal window
```
m security
```