Getting Started
Installation
TradeClaw runs anywhere Node.js 22 and Docker are available. The recommended path is Docker Compose — it brings up the app, scanner, database, and cache with a single command.
Prerequisites
Docker ≥ 24
For the containerized stack
Node.js 22+
For local development
pnpm 9+
Monorepo package manager
PostgreSQL 16
Provided by Docker Compose
Option 1 — Docker Compose
Starts four services: the Next.js app, a background signal scanner, TimescaleDB, and Redis. This is the production-grade path and the one we recommend for self-hosting.
1. Clone & configure
git clone https://github.com/naimkatiman/tradeclaw
cd tradeclaw
# Copy the example env file
cp apps/web/.env.example apps/web/.env.local2. Edit .env.local
At minimum, set NEXT_PUBLIC_BASE_URL to your domain or http://localhost:3000. All other variables are optional for a basic run.
3. Start the stack
docker compose up -d
# Tail logs
docker compose logs -f app
# Open the app
open http://localhost:3000docker-compose.yml
services:
db:
image: timescale/timescaledb:latest-pg16
environment:
POSTGRES_DB: ${DB_NAME:-tradeclaw}
POSTGRES_USER: ${DB_USER:-tradeclaw}
POSTGRES_PASSWORD: ${DB_PASSWORD:-changeme}
volumes:
- db_data:/var/lib/postgresql/data
- ./scripts/init-db.sh:/docker-entrypoint-initdb.d/init.sh
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-tradeclaw}"]
interval: 5s
timeout: 3s
retries: 10
restart: unless-stopped
redis:
image: redis:7-alpine
command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
volumes:
- redis_data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
restart: unless-stopped
app:
build:
context: .
dockerfile: Dockerfile
target: production
ports:
- "${APP_PORT:-3000}:3000"
environment:
DATABASE_URL: postgres://${DB_USER:-tradeclaw}:${DB_PASSWORD:-changeme}@db:5432/${DB_NAME:-tradeclaw}
REDIS_URL: redis://redis:6379
NODE_ENV: production
depends_on:
db:
condition: service_healthy
redis:
condition: service_healthy
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
interval: 10s
restart: unless-stopped
scanner:
build:
context: .
dockerfile: Dockerfile.scanner
environment:
DATABASE_URL: postgres://${DB_USER:-tradeclaw}:${DB_PASSWORD:-changeme}@db:5432/${DB_NAME:-tradeclaw}
SCAN_INTERVAL: ${SCAN_INTERVAL:-60}
SCAN_INSTRUMENTS: ${SCAN_INSTRUMENTS:-all}
depends_on:
db:
condition: service_healthy
restart: unless-stopped
volumes:
db_data:
redis_data:Option 2 — Railway
Railway auto-provisions PostgreSQL and Redis. It's the easiest path if you don't want to manage infrastructure.
- 1.Fork the tradeclaw repo to your GitHub account.
- 2.Create a new Railway project and choose "Deploy from GitHub repo".
- 3.Add a PostgreSQL and Redis plugin from the Railway dashboard.
- 4.Set environment variables in Railway's Variables panel (see Configuration).
- 5.Railway injects
DATABASE_URLandREDIS_URLautomatically from the plugins.
Option 3 — Vercel
Note:Vercel is serverless — the background scanner service won't run continuously. Signals update only on API request. For live scanning, use Docker or Railway.
# Install Vercel CLI
npm i -g vercel
# Deploy from the apps/web directory
cd apps/web
vercel deploy
# Add env variables via Vercel dashboard or CLI
vercel env add NEXT_PUBLIC_BASE_URL
vercel env add DATABASE_URLOption 4 — Local Development
# Install dependencies (from monorepo root)
pnpm install
# Start local DB and Redis via Docker (optional)
docker compose up -d db redis
# Copy and edit env
cp apps/web/.env.example apps/web/.env.local
# Start the Next.js dev server
pnpm --filter web dev
# In a second terminal, start the scanner
pnpm --filter scanner devThe dev server runs at http://localhost:3000 with hot-reload via Turbopack.
Verify the Installation
curl http://localhost:3000/api/health
# Expected response:
# { "status": "ok", "checks": { "database": { "status": "ok" }, "migrations": { "status": "ok" } } }