Skip to content

Onboarding

This guide takes a new engineer from a clean machine to running the full stack locally and making a first contribution.

Prerequisites

  • Python 3.11+ and Node.js 20+.
  • A Frappe Bench environment for ERPNext v15.
  • Supporting services: MariaDB and Redis.

Frappe and ERPNext run natively on Linux and macOS. On Windows, they run inside WSL2 (Ubuntu); the marketing site and platform service may run on either the Windows host or inside WSL. See Platform notes.

1. Obtain the repositories

The repositories are cloned side by side under a common parent directory:

ndakita_build            # Frappe application
ndakita_build_platform   # Platform service
ndakita_group_site       # Marketing website
ndakita-docs             # This documentation

Each repository's README and docs/ directory are the authoritative, component-level references. This site is the map between them.

2. Frappe Bench and the ERP application

Set up a Frappe Bench (frappe-bench) with ERPNext v15, the ndakita_build application, and the whitelabel layer installed on a development site. The application seeds construction defaults automatically on install and migrate. See the ndakita_build repository for the detailed procedure.

Linux / macOS

bench get-app ndakita_build <repo-url>
bench new-site ndakitabuild.localhost
bench --site ndakitabuild.localhost install-app erpnext ndakita_build
bench start

Windows

Run the same commands inside WSL2 (Ubuntu), where the bench lives.

3. Platform service

cd ndakita_build_platform
python -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env          # defaults are development-ready (SQLite, mock provisioning)
.venv/bin/uvicorn api.main:app --host 0.0.0.0 --port 8001
  • BENCH_MODE=mock simulates provisioning without building a site; suitable for platform and API development.
  • BENCH_MODE=real performs real provisioning and requires an available bench (BENCH_PATH).
  • Binding to --host 0.0.0.0 is recommended so the service is reachable from a browser on the host machine.

4. Marketing website

cd ndakita_group_site
npm install
npm run dev                   # http://localhost:3000

.env.local sets NEXT_PUBLIC_PLATFORM_API_URL, the address of the platform service.

5. End-to-end tenant creation

Create a tenant through the sign-up form or POST /public/signup, poll the status endpoint until trial, and retrieve the administrator credentials with the platform CLI (python -m cli tenant credentials <slug>) until email delivery is configured. Point the development bench at the new site (bench use <slug>.localhost) and sign in. The platform README documents this procedure in full.

Platform notes

Development server serves one site

The Frappe development server serves a single default site. Select the active site with bench use <site>; host-based subdomain routing applies only in production, where the web server routes each subdomain to its own site.

Windows (WSL2)

  • The bench runs inside WSL2. Services intended to be reached from a browser on the Windows host should bind to 0.0.0.0.
  • Where WSL localhost forwarding is unavailable, reach WSL services by the WSL interface address rather than localhost. Helper scripts in the workspace root assist with port cleanup and address discovery.

Contribution conventions

  • The Frappe application never modifies ERPNext or Frappe core; customisations use hooks, fixtures, and overrides, and fixtures are exported after changes.
  • Run the relevant test suite before opening a change: bench ... run-tests --app ndakita_build for the application, and pytest for the platform.
  • Follow the commit and branching conventions defined in each repository.