Skip to content
Blue Dots Economy Documentation

Getting Started

This guide is the fastest way to get a working DPG instance on your machine.

Prerequisites

Section titled “Prerequisites”
  • Node.js >=24
  • pnpm 11.1.2
  • Docker Desktop or Docker Engine

What You Will Run

Section titled “What You Will Run”

For a normal local setup you run:

  • PostgreSQL
  • Redis
  • the API app
  • optionally the UI app
  • optionally the docs site

1. Install Dependencies

Section titled “1. Install Dependencies”
Terminal window
pnpm install

2. Copy Environment

Section titled “2. Copy Environment”
Terminal window
cp .env.example .env

Use this minimum local setup:

Terminal window
INSTANCE_NAME="dpg-local"
INSTANCE_ENV="development"
API_DOMAIN="http://localhost"
API_PORT="2742"
SERVED_DOMAINS="yellow_dot/student"
NETWORK_CONFIG_SOURCE="local"
NETWORK_CONFIG_LOCAL_FILE="examples/schemas/yellow_dot/network.json"
AUTH_SECRET="replace-this"
REDIS_PASSWORD="replace-this"

3. Start PostgreSQL And Redis

Section titled “3. Start PostgreSQL And Redis”
Terminal window
docker compose up -d db redis

4. Run The API

Section titled “4. Run The API”
Terminal window
pnpm dev:api

To run the API itself as a Docker container against the Compose PostgreSQL and Redis services:

Terminal window
docker compose up -d db redis
DOCKER_NETWORK=dpg_internal pnpm docker:api

The API should be available at:

  • http://localhost:2742
  • http://localhost:2742/api/reference

5. Optional: Run The UI App

Section titled “5. Optional: Run The UI App”
Terminal window
pnpm dev:ui

The UI reads schemas and network items from the API. Set VITE_API_URL in the UI environment when the API is not available at the default local URL.

6. Optional: Run The Docs Site

Section titled “6. Optional: Run The Docs Site”
Terminal window
pnpm dev:docs

7. Create Test Data

Section titled “7. Create Test Data”

Use one of the payloads from:

  • examples/api/yellow_dot.md
  • examples/api/blue_dot.md
  • examples/postman/dpg.postman_collection.json for a generic single-domain collection
  • examples/schemas/*/postman/*.postman_collection.json for schema-specific collections

Remember:

  • POST /api/v1/item/create does not accept item_instance_url
  • POST /api/v1/item/create does not accept item_schema_url
  • those are generated by the backend

Common Local Modes

Section titled “Common Local Modes”

One instance, one domain

Section titled “One instance, one domain”
Terminal window
SERVED_DOMAINS="yellow_dot/student"
NETWORK_CONFIG_SOURCE="local"
NETWORK_CONFIG_LOCAL_FILE="examples/schemas/yellow_dot/network.json"

One instance, many domains

Section titled “One instance, many domains”
Terminal window
SERVED_DOMAINS="yellow_dot/student,yellow_dot/tutor"
NETWORK_CONFIG_SOURCE="local"
NETWORK_CONFIG_LOCAL_FILE="examples/schemas/yellow_dot/network.json"

Multi-network instance

Section titled “Multi-network instance”

For multiple networks in one process, prefer remote config loading:

Terminal window
SERVED_DOMAINS="yellow_dot/student,blue_dot/seeker"
NETWORK_CONFIG_SOURCE="remote"
NETWORK_CONFIG_URLS="yellow_dot=https://registry.example.com/schemas/yellow_dot/network.json,blue_dot=https://registry.example.com/schemas/blue_dot/network.json"

Useful Commands

Section titled “Useful Commands”
  • pnpm dev:api
  • pnpm dev:ui
  • pnpm build:api
  • pnpm build:ui
  • pnpm preview:api
  • pnpm preview:ui
  • pnpm start:api
  • pnpm db:generate:api
  • pnpm db:migrate:api
  • pnpm db:studio:api
  • pnpm dev:docs
  • pnpm build:docs
Section titled “Recommended Learning Path”
  1. Vocabulary
  2. Architecture
  3. Environment
  4. Network Schema Authoring Guide
  5. API Overview
  6. one of the hosting guides