Installation

Prerequisites

ChainGraph requires:

• Node.js: Version 22.14.0
• Package Manager: pnpm 10.16.1 or higher

Quick Installation

Clone the repository and install dependencies:

git clone https://github.com/badaitech/chaingraph.git
cd chaingraph
pnpm install

Running in Development Mode

Start the complete development environment (frontend and backend):

pnpm run dev

This command launches:

• Frontend development server with hot reloading
• Backend development process in watch mode

Running Components Individually

You can also run each component separately:

Backend only:

pnpm run dev:back

Frontend only:

pnpm run dev:front

Execution worker:

pnpm run dev:execution-worker

PostgreSQL Database Storage (Optional)

ChainGraph can use PostgreSQL for persistent storage instead of in-memory storage.

1. Start PostgreSQL Database

Use the included Docker Compose configuration:

docker compose up -d postgres

This starts a PostgreSQL instance on port 5432.

2. Configure Database Connection

Create a .env file in the project root:

DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable

3. Run Database Migrations

Before starting ChainGraph with PostgreSQL storage, run migrations:

pnpm run migrate

This creates all required tables and indexes in your PostgreSQL database.

4. Start ChainGraph

Once migrations are complete, start ChainGraph normally:

pnpm run dev

Your flows, nodes, and execution data will now be stored persistently in PostgreSQL.

Building for Production

Build the entire project:

pnpm run build

Build specific packages:

# Build frontend only
pnpm run build:front

# Build backend only
pnpm run build:back

Preview the production build:

pnpm run preview

Docker Deployment

Building Docker Images

Build Docker images using the Makefile:

# Build backend image
make docker-build-backend

# Build frontend image
make docker-build-frontend

# Build both images
make docker-build-all

Or manually:

# Backend
docker build -t chaingraph-backend -f apps/chaingraph-backend/Dockerfile .

# Frontend
docker build -t chaingraph-frontend -f apps/chaingraph-frontend/Dockerfile .

Running with Docker Compose

Launch both containers:

make docker-compose-up

Or manually:

docker-compose up -d      # Start containers
docker-compose down       # Stop and remove containers

This starts:

• Backend on port 3001
• Frontend on port 5173

Debugging Setup

WebStorm

1. Open Run/Debug Configurations
2. Create a new Bun configuration:
   • File: apps/chaingraph-backend/src/index.ts
   • Bun parameters: --conditions=development
3. Set breakpoints in TypeScript files and start debugging

VS Code

Add to .vscode/launch.json:

{
  "type": "node",
  "request": "launch",
  "name": "Debug Backend",
  "runtimeExecutable": "bun",
  "runtimeArgs": ["--conditions=development", "--watch", "run", "src/index.ts"],
  "cwd": "${workspaceFolder}/apps/chaingraph-backend"
}

Frontend Debugging (Browser)

1. Start dev server: pnpm run dev:front
2. Open Chrome/Firefox and navigate to http://localhost:3004
3. Open DevTools (F12) → Sources tab
4. Press Cmd+P (or Ctrl+P) to quick-open files
5. Set breakpoints in .tsx/.ts files

Authentication for GitHub Packages

To use published ChainGraph packages, configure npm authentication:

1. Create a personal access token (PAT) with the read:packages scope on GitHub
2. Add to your .npmrc file:

@badaitech:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT

Replace YOUR_GITHUB_PAT with your actual GitHub personal access token.

Verification

After installation, verify everything works:

# Run tests
pnpm test

# Check types
pnpm typecheck

# Lint code
pnpm lint

Next Steps

• Quick Start Guide - Build your first flow
• Architecture Overview - Understand the system design
• API Reference - Explore the API documentation

Troubleshooting

Issue: pnpm install fails with peer dependency errors

Solution: These warnings are expected and don't prevent the application from running. They're related to React type versions in the monorepo.

---

Issue: Database migrations fail

Solution: Ensure PostgreSQL is running and the DATABASE_URL in .env is correct. Check the connection with:

psql "postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable"

---

Issue: Port already in use

Solution: Check if another process is using the port:

lsof -i :3001  # Backend
lsof -i :3004  # Frontend

Kill the process or configure a different port in the respective app's configuration.