Quickstart (Local Dev)

Get Nexgent running locally in under 15 minutes.

This guide covers local development setup. For cloud hosting deployment, see Quickstart (Cloud Hosting).

Prerequisites

Before starting, ensure you have:

Node.js 18.0.0 or higher (download (opens in a new tab))
pnpm 8.0.0 or higher (install (opens in a new tab))
Docker Desktop installed and running (download (opens in a new tab))
Git for cloning the repository

Setup

Clone the Repository

git clone https://github.com/Nexgent-ai/nexgent-open-source-trading-engine.git
cd nexgent

Start Infrastructure

Start PostgreSQL and Redis using Docker Compose:

docker-compose up -d

Verify services are running:

docker-compose ps
# Both nexgent-postgres and nexgent-redis should show "Up"

Install Dependencies

pnpm install

Configure Environment Variables

cd packages/backend
cp env.example .env

The defaults work with Docker Compose. Key settings:

# Database (Docker Compose defaults)
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/nexgent?schema=public"
 
# Redis (Docker Compose defaults)
REDIS_HOST=localhost
REDIS_PORT=6379
 
# Server
PORT=4000
NODE_ENV=development
CORS_ORIGIN=http://localhost:3000
 
# JWT Secret (generate below)
JWT_SECRET="your-secret-here"

Generate Secrets

From the project root:

# Generate frontend secret (NextAuth)
pnpm generate-secret
 
# Generate backend secret (JWT)
pnpm generate-secret:backend

Copy the generated secrets into your .env files.

Run Database Migrations

pnpm --filter backend db:migrate

This creates all necessary database tables.

Start the Application

# Start both frontend and backend
pnpm dev

Or start them separately:

pnpm dev:backend   # Backend on http://localhost:4000
pnpm dev:frontend  # Frontend on http://localhost:3000

Verify Installation

Check Backend Health

curl http://localhost:4000/api/v1/health
# Should return: {"status":"ok"}

Access the Dashboard

Open http://localhost:3000 (opens in a new tab) in your browser.

You should see the login page:

Create an Account

Click Register
Enter your email and password
You'll be redirected to the dashboard

What's Running

After setup, you have:

Service	URL	Purpose
Frontend	http://localhost:3000 (opens in a new tab)	Next.js dashboard
Backend	http://localhost:4000 (opens in a new tab)	Express API + WebSocket
PostgreSQL	localhost:5432	Database
Redis	localhost:6379	Cache + job queues

Troubleshooting

Port Already in Use

netstat -ano | findstr :4000
taskkill /PID <pid> /F

Docker Services Not Starting

# Check logs
docker-compose logs postgres
docker-compose logs redis
 
# Restart services
docker-compose down
docker-compose up -d

Database Connection Error

Verify Docker is running: docker-compose ps
Check DATABASE_URL in .env matches Docker Compose credentials
Run migrations again: pnpm --filter backend db:migrate

Frontend Can't Connect to Backend

Verify backend is running: curl http://localhost:4000/api/v1/health
Check NEXT_PUBLIC_API_URL in frontend .env.local
Check CORS_ORIGIN in backend .env includes http://localhost:3000

Useful Commands

# Start everything
pnpm dev
 
# Stop Docker services
docker-compose stop
 
# View database with Prisma Studio
pnpm --filter backend db:studio
 
# Run tests
pnpm test
 
# Build for production
pnpm build

Nexgent vs. Alternatives Quickstart (Cloud Hosting)