📢 This documentation relates to the Open-Source Trading Engine upgrade which is launching shortly →
OS Trading Engine
Self-Hosting
Docker Compose

Docker Compose Deployment

Deploy Nexgent's infrastructure services (PostgreSQL and Redis) using Docker Compose, then run the application natively.

This guide is ideal for local development and simple production setups on a single server.

Prerequisites

Quick Start

Clone the Repository

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

Start Infrastructure Services

docker-compose up -d

This starts:

  • PostgreSQL on port 5432
  • Redis on port 6379

Verify services are running:

docker-compose ps

You should see both nexgent-postgres and nexgent-redis with status "Up".

Install Dependencies

pnpm install

Configure Environment Variables

cd packages/backend
cp env.example .env

Edit .env with minimum required values:

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

Generate Secrets

# From project root
pnpm generate-secret          # Frontend (NextAuth)
pnpm generate-secret:backend  # Backend (JWT)

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 separately
pnpm dev:backend   # Backend on http://localhost:4000
pnpm dev:frontend  # Frontend on http://localhost:3000

Verify Installation

Docker Compose Configuration

The included docker-compose.yml:

services:
  postgres:
    image: postgres:14-alpine
    container_name: nexgent-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: nexgent
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
 
  redis:
    image: redis:7-alpine
    container_name: nexgent-redis
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
 
volumes:
  postgres_data:

Production Deployment

For production on a single server, use the same Docker Compose setup with additional configuration.

1. Update Environment Variables

Backend .env:

# Database
DATABASE_URL="postgresql://postgres:STRONG_PASSWORD@localhost:5432/nexgent?schema=public"
 
# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
 
# Server
PORT=4000
NODE_ENV=production
CORS_ORIGIN=https://your-domain.com
 
# Security
JWT_SECRET="your-production-jwt-secret"
 
# External APIs
JUPITER_API_KEY=your-jupiter-api-key
SOLANA_RPC_URL=https://your-rpc-endpoint

Frontend .env.local:

NEXTAUTH_URL=https://your-domain.com
NEXTAUTH_SECRET="your-production-nextauth-secret"
NEXT_PUBLIC_API_URL=https://api.your-domain.com

2. Secure Docker Compose

Create docker-compose.prod.yml:

services:
  postgres:
    image: postgres:14-alpine
    container_name: nexgent-postgres
    environment:
      POSTGRES_USER: nexgent
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: nexgent
    ports:
      - "127.0.0.1:5432:5432"  # Only localhost
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: always
 
  redis:
    image: redis:7-alpine
    container_name: nexgent-redis
    command: redis-server --requirepass ${REDIS_PASSWORD}
    ports:
      - "127.0.0.1:6379:6379"  # Only localhost
    restart: always
 
volumes:
  postgres_data:

Run with environment variables:

POSTGRES_PASSWORD=your-strong-password \
REDIS_PASSWORD=your-redis-password \
docker-compose -f docker-compose.prod.yml up -d

3. Build for Production

# Build all packages
pnpm build
 
# Start production servers
pnpm start

4. Use a Process Manager

Install PM2 for process management:

npm install -g pm2

Create ecosystem.config.js:

module.exports = {
  apps: [
    {
      name: 'nexgent-backend',
      cwd: './packages/backend',
      script: 'dist/index.js',
      instances: 1,
      env: {
        NODE_ENV: 'production',
      },
    },
    {
      name: 'nexgent-frontend',
      cwd: './packages/frontend',
      script: 'node_modules/.bin/next',
      args: 'start',
      instances: 1,
      env: {
        NODE_ENV: 'production',
      },
    },
  ],
};

Start with PM2:

pm2 start ecosystem.config.js
pm2 save
pm2 startup  # Auto-start on boot

5. Set Up Reverse Proxy

Use Nginx as a reverse proxy. See Production Checklist for SSL configuration.

Managing Services

Start Services

docker-compose up -d

Stop Services

# Stop (keeps data)
docker-compose stop
 
# Stop and remove containers (keeps data)
docker-compose down
 
# Stop and remove everything (DELETES ALL DATA)
docker-compose down -v

View Logs

# All services
docker-compose logs -f
 
# Specific service
docker-compose logs -f postgres
docker-compose logs -f redis

Check Health

docker-compose ps

Both services should show "healthy" status.

Database Management

Access PostgreSQL

# Via Docker exec
docker exec -it nexgent-postgres psql -U postgres -d nexgent
 
# Via psql (if installed locally)
psql -h localhost -U postgres -d nexgent

Prisma Studio

cd packages/backend
pnpm db:studio

Opens a visual database browser at http://localhost:5555 (opens in a new tab).

Run Migrations

# Development
pnpm --filter backend db:migrate
 
# Production (apply only, no prompts)
pnpm --filter backend db:migrate:deploy

Reset Database

# Stop everything and delete data
docker-compose down -v
 
# Start fresh
docker-compose up -d
pnpm --filter backend db:migrate

Troubleshooting

Port Already in Use

Check what's using the port:

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

Or change ports in docker-compose.yml:

ports:
  - "5433:5432"  # Map to different host port

Container Won't Start

# Check logs
docker-compose logs postgres
 
# Remove and recreate
docker-compose down
docker-compose up -d

Can't Connect to Database

  1. Verify container is running: docker-compose ps
  2. Check health status shows "healthy"
  3. Verify .env credentials match docker-compose.yml
  4. Ensure Docker Desktop is running

Permission Denied (Linux)

sudo usermod -aG docker $USER
# Log out and back in
Railway (Recommended)Vercel + Railway