Getting Started

Set up a local Dualis Finance development environment from scratch. This guide covers prerequisites, repository setup, environment configuration, and running the full stack in development mode.

Prerequisites

Ensure the following tools are installed before proceeding. Version constraints are strict — the codebase relies on APIs and behaviors specific to these releases.

Tool	Version	Notes
Node.js	>=20 <22	LTS recommended. Node 22+ is not yet supported.
pnpm	>=9	Workspace package manager. Install via `corepack enable`.
PostgreSQL	16	63 tables — schema managed by Drizzle ORM migrations.
Redis	7.2	Used for caching, sessions, and BullMQ job queues.
Docker	Latest	Recommended for running infrastructure services.
DAML SDK	3.4.11	Required only if you plan to build or modify smart contracts.

Quick Check

Run node -v && pnpm -v && docker -v to verify your toolchain before continuing.

Clone and Install

Clone the monorepo and install all workspace dependencies. pnpm handles cross-package linking automatically.

Terminal

git clone https://github.com/cayvox/dualis-finance.git
cd dualis-finance
pnpm install

The shared package must build first because both api and frontend depend on its exported types. Turborepo handles this ordering automatically:

Terminal

pnpm run build

Environment Configuration

Copy the example environment files and fill in your local values. Each package that requires configuration ships a .env.example.

Terminal

cp packages/api/.env.example packages/api/.env
cp packages/frontend/.env.example packages/frontend/.env

Key variables for the API package:

packages/api/.env

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/dualis
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-development-secret
CANTON_JSON_API_URL=http://localhost:7575
PORT=4000

Secrets

Never commit .env files to version control. The repository's .gitignore already excludes them, but double-check before pushing.

Docker Setup

The project ships four Docker Compose files for different environments:

File	Purpose
`docker-compose.yml`	Local development — PostgreSQL, Redis, and optional Canton sandbox
`docker-compose.devnet.yml`	Devnet deployment with Nginx, SSL, and Canton validator
`docker-compose.test.yml`	Isolated test databases and services for CI
`docker-compose.prod.yml`	Production-ready configuration with resource limits and health checks

Start the local infrastructure stack:

Terminal

docker compose up -d

This brings up PostgreSQL on port 5432 and Redis on port 6379. Run the database migrations next:

Terminal

pnpm --filter @dualis/api run db:migrate

Start Development

With infrastructure running, start the API and frontend in parallel using Turborepo:

Terminal

pnpm run dev

The API server starts on http://localhost:4000 and the frontend on http://localhost:3000. Both support hot reload.

First API Call

Verify the stack is healthy by hitting the health endpoint:

Terminal

curl http://localhost:4000/v1/health

Expected response:

Response

{
  "status": "ok",
  "version": "2.0.0",
  "uptime": 12.34,
  "services": {
    "database": "connected",
    "redis": "connected",
    "canton": "connected"
  }
}

Canton Optional

The API operates in mock mode when Canton is unavailable. Pool data, positions, and rate calculations all function with simulated data, making it possible to develop frontend features without a running Canton node.

Running Tests

The shared math engine has over 230 tests. Run the full suite with Vitest:

Terminal

pnpm --filter @dualis/shared test

To run Canton smart contract tests (requires DAML SDK 3.4.11):

Terminal

cd packages/canton/daml
daml build && daml test

Next Steps

API Reference — Explore the full set of 272 endpoints across 19 domain groups.
SDK — Learn how to use the @dualis/shared package for financial calculations.
Smart Contracts — Dive into the 25 DAML modules that power on-chain settlement.
WebSocket — Subscribe to real-time price and position updates.