Getting Started

Self-Hosting Guide

Run TradeClaw in production on your own server with Docker, nginx, SSL certificates, and proper monitoring. This guide covers a production-grade deployment from scratch.

Architecture Overview

A production TradeClaw deployment consists of:

Web App

Next.js standalone server on port 3000

Reverse Proxy

nginx handling TLS termination and compression

Data Store

File-based JSON in /data directory (no external DB required)

SSE Stream

Server-Sent Events for live price feed on /api/prices/stream

Server Requirements

CPU1 vCPU2+ vCPU

RAM512 MB1 GB+

Disk1 GB5 GB+

OSAny LinuxUbuntu 22.04 / Debian 12

Docker24.0+Latest stable

Node.js22.0+22 LTS (if running without Docker)

Docker Production Setup

The recommended approach. Uses the multi-stage Dockerfile with a minimal production image.

1. Clone and configure

bash

git clone https://github.com/naimkatiman/tradeclaw.git
cd tradeclaw
cp .env.example .env

2. Edit environment variables

.env

# Required
NODE_ENV=production
NEXT_PUBLIC_APP_URL=https://your-domain.com

# Optional — enable features
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_WEBHOOK_URL=https://your-domain.com/api/telegram/webhook

# Alpha Screener (SaaS upsell, optional)
NEXT_PUBLIC_ALPHA_SCREENER_URL=https://alpha-screener.com
ALPHA_SCREENER_API_KEY=your_key

3. Build and run

bash

docker compose up -d --build

# Verify health
curl http://localhost:3000/api/health

Nginx Reverse Proxy

Place nginx in front of TradeClaw for TLS termination, compression, and caching.

/etc/nginx/sites-available/tradeclaw

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Gzip compression
    gzip on;
    gzip_types text/plain application/json application/javascript text/css;
    gzip_min_length 1000;

    # SSE support — disable buffering for stream endpoints
    location /api/prices/stream {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
    }

    # All other requests
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Cache static assets
        location /_next/static/ {
            proxy_pass http://127.0.0.1:3000;
            expires 365d;
            add_header Cache-Control "public, immutable";
        }
    }
}

SSL with Let's Encrypt

bash

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Get certificate
sudo certbot --nginx -d your-domain.com

# Auto-renewal (certbot adds a systemd timer automatically)
sudo certbot renew --dry-run

Health Monitoring

TradeClaw exposes a /api/health endpoint that returns uptime, version, the available build identity, and readiness checks. It returns HTTP 200 only when PostgreSQL and the required schema migration are ready, otherwise HTTP 503.

GET /api/health

{
  "status": "ok",
  "version": "0.1.0",
  "uptime": 86400,
  "node": "v22.0.0",
  "build": "<revision-or-deployment-id>",
  "timestamp": "2026-03-27T10:00:00.000Z",
  "checks": {
    "database": { "status": "ok" },
    "migrations": { "status": "ok", "required": "053_drop_monetization.sql" }
  }
}

Pair with services like UptimeRobot, Better Uptime, or a simple cron curl:

bash

# crontab -e
*/5 * * * * curl -sf https://your-domain.com/api/health || echo "TradeClaw down" | mail -s "Alert" [email protected]

Updating TradeClaw

bash

cd tradeclaw
git pull origin main
docker compose down
docker compose up -d --build

# Verify
curl http://localhost:3000/api/health

Data persistence: Signal history, paper trading positions, and plugin configurations are stored in data/. This directory is volume-mounted in Docker and survives rebuilds.

Running Without Docker

bash

# Install dependencies
pnpm install

# Build production
pnpm build

# Start (uses Next.js standalone output)
cd apps/web
node .next/standalone/apps/web/server.js

Use a process manager like PM2 or systemd to keep the process alive:

/etc/systemd/system/tradeclaw.service

[Unit]
Description=TradeClaw Trading Platform
After=network.target

[Service]
Type=simple
User=tradeclaw
WorkingDirectory=/opt/tradeclaw/apps/web
ExecStart=/usr/bin/node .next/standalone/apps/web/server.js
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3000

[Install]
WantedBy=multi-user.target

PreviousConfiguration NextTrading Signals

Edit this page on GitHub

Getting Started

Self-Hosting Guide

Run TradeClaw in production on your own server with Docker, nginx, SSL certificates, and proper monitoring. This guide covers a production-grade deployment from scratch.

Architecture Overview

A production TradeClaw deployment consists of:

Web App

Next.js standalone server on port 3000

Reverse Proxy

nginx handling TLS termination and compression

Data Store

File-based JSON in /data directory (no external DB required)

SSE Stream

Server-Sent Events for live price feed on /api/prices/stream

Server Requirements

CPU1 vCPU2+ vCPU

RAM512 MB1 GB+

Disk1 GB5 GB+

OSAny LinuxUbuntu 22.04 / Debian 12

Docker24.0+Latest stable

Node.js22.0+22 LTS (if running without Docker)

Docker Production Setup

The recommended approach. Uses the multi-stage Dockerfile with a minimal production image.

1. Clone and configure

bash

git clone https://github.com/naimkatiman/tradeclaw.git
cd tradeclaw
cp .env.example .env

2. Edit environment variables

.env

# Required
NODE_ENV=production
NEXT_PUBLIC_APP_URL=https://your-domain.com

# Optional — enable features
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_WEBHOOK_URL=https://your-domain.com/api/telegram/webhook

# Alpha Screener (SaaS upsell, optional)
NEXT_PUBLIC_ALPHA_SCREENER_URL=https://alpha-screener.com
ALPHA_SCREENER_API_KEY=your_key

3. Build and run

bash

docker compose up -d --build

# Verify health
curl http://localhost:3000/api/health

Nginx Reverse Proxy

Place nginx in front of TradeClaw for TLS termination, compression, and caching.

/etc/nginx/sites-available/tradeclaw

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Gzip compression
    gzip on;
    gzip_types text/plain application/json application/javascript text/css;
    gzip_min_length 1000;

    # SSE support — disable buffering for stream endpoints
    location /api/prices/stream {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
    }

    # All other requests
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Cache static assets
        location /_next/static/ {
            proxy_pass http://127.0.0.1:3000;
            expires 365d;
            add_header Cache-Control "public, immutable";
        }
    }
}

SSL with Let's Encrypt

bash

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Get certificate
sudo certbot --nginx -d your-domain.com

# Auto-renewal (certbot adds a systemd timer automatically)
sudo certbot renew --dry-run

Health Monitoring

GET /api/health

{
  "status": "ok",
  "version": "0.1.0",
  "uptime": 86400,
  "node": "v22.0.0",
  "build": "<revision-or-deployment-id>",
  "timestamp": "2026-03-27T10:00:00.000Z",
  "checks": {
    "database": { "status": "ok" },
    "migrations": { "status": "ok", "required": "053_drop_monetization.sql" }
  }
}

Pair with services like UptimeRobot, Better Uptime, or a simple cron curl:

bash

# crontab -e
*/5 * * * * curl -sf https://your-domain.com/api/health || echo "TradeClaw down" | mail -s "Alert" [email protected]

Updating TradeClaw

bash

cd tradeclaw
git pull origin main
docker compose down
docker compose up -d --build

# Verify
curl http://localhost:3000/api/health

Data persistence: Signal history, paper trading positions, and plugin configurations are stored in data/. This directory is volume-mounted in Docker and survives rebuilds.

Running Without Docker

bash

# Install dependencies
pnpm install

# Build production
pnpm build

# Start (uses Next.js standalone output)
cd apps/web
node .next/standalone/apps/web/server.js

Use a process manager like PM2 or systemd to keep the process alive:

/etc/systemd/system/tradeclaw.service

[Unit]
Description=TradeClaw Trading Platform
After=network.target

[Service]
Type=simple
User=tradeclaw
WorkingDirectory=/opt/tradeclaw/apps/web
ExecStart=/usr/bin/node .next/standalone/apps/web/server.js
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3000

[Install]
WantedBy=multi-user.target

PreviousConfiguration NextTrading Signals

Edit this page on GitHub