Environment Variables

Overview

NeuraTrade uses environment variables for system configuration. Copy .env.example to .env in your repository root and configure the values for your deployment.

Never commit .env files to version control. Use strong, randomly generated secrets in production.

Quick Start

cp .env.example .env
# Edit .env with your configuration

Core Configuration

NeuraTrade Home Directory

NEURATRADE_HOME

string

required

Absolute path to NeuraTrade config and data directory. This is where SQLite DB, Redis data, and logs will be stored.Note: Use an absolute path. Shell shortcuts like ~ are not expanded by all launch scripts.

NEURATRADE_HOME=/home/youruser/.neuratrade

Network Configuration

BACKEND_HOST_PORT

number

required

Single port exposed to host for backend API (use 5-digit port to avoid conflicts). Access NeuraTrade at http://localhost:{port}.

BACKEND_HOST_PORT=58080

SERVER_PORT

number

default:"8080"

Internal server port for the backend API service.

SERVER_HOST

string

default:"0.0.0.0"

Server bind address. Use 0.0.0.0 to accept connections from all interfaces.

ENVIRONMENT

string

default:"development"

Application environment mode.Options: development, production, test

Database Configuration

SQLite (Default)

SQLite has a known startup issue with collector workers (neura-v7e6). Consider using PostgreSQL for full functionality.

DATABASE_DRIVER

string

default:"sqlite"

Database driver selection.Options: sqlite, postgres

SQLITE_PATH

string

required

Absolute path to SQLite database file. Should match your NEURATRADE_HOME setting.

SQLITE_PATH=/home/youruser/.neuratrade/neuratrade.db

PostgreSQL (Production)

DATABASE_HOST

string

default:"localhost"

PostgreSQL server hostname.

DATABASE_PORT

number

default:"5432"

PostgreSQL server port.

DATABASE_USER

string

default:"postgres"

PostgreSQL username.

DATABASE_PASSWORD

string

required

PostgreSQL password.

Change this in production - never use default passwords.

DATABASE_DBNAME

string

default:"neuratrade"

PostgreSQL database name.

DATABASE_SSLMODE

string

default:"disable"

PostgreSQL SSL mode.Options: disable, require, verify-ca, verify-full

DATABASE_URL

string

Complete PostgreSQL connection string (preferred for managed databases like Digital Ocean).Format: postgres://username:password@host:port/dbname?sslmode=require

When set, this overrides individual database settings.

Connection Pool Settings

DATABASE_MAX_OPEN_CONNS

number

default:"25"

Maximum number of open database connections (PostgreSQL only).

DATABASE_MAX_IDLE_CONNS

number

default:"5"

Maximum number of idle database connections in the pool.

DATABASE_CONN_MAX_LIFETIME

duration

default:"300s"

Maximum lifetime of a database connection.

DATABASE_CONN_MAX_IDLE_TIME

duration

default:"60s"

Maximum time a connection can remain idle.

Redis Configuration

REDIS_HOST

string

default:"localhost"

Redis server hostname.

REDIS_PORT

number

default:"6379"

Redis server port.

REDIS_PASSWORD

string

Redis authentication password (optional).

REDIS_DB

number

default:"0"

Redis database number (0-15).

CCXT Service Configuration

CCXT_SERVICE_URL

string

default:"http://localhost:3001"

URL for the CCXT exchange integration service.

CCXT_TIMEOUT

duration

default:"30s"

Timeout for CCXT service requests.

PORT

number

default:"3001"

Port for the CCXT service (used by ccxt-service component).

Telegram Configuration

TELEGRAM_BOT_TOKEN

string

required

Telegram bot token from @BotFather.Get your token: https://t.me/BotFather

TELEGRAM_WEBHOOK_URL

string

Public URL for webhook mode (production).

TELEGRAM_WEBHOOK_URL=https://your-domain.com/api/v1/telegram/webhook

TELEGRAM_WEBHOOK_SECRET

string

Secret to validate incoming webhook requests.Generate with: openssl rand -base64 32

TELEGRAM_USE_POLLING

boolean

default:"true"

Use polling mode (development) vs webhook mode (production).

TELEGRAM_WEBHOOK_PATH

string

default:"/telegram/webhook"

Path for the webhook endpoint.

TELEGRAM_PORT

number

default:"3002"

Port for the Telegram service.

TELEGRAM_API_BASE_URL

string

default:"http://localhost:8080"

URL of the backend-api service for Telegram to call.

RUN_TELEGRAM_SERVICE

boolean

default:"true"

Enable/disable the Telegram service.

TELEGRAM_EXTERNAL_SERVICE

boolean

default:"true"

Use external TypeScript Telegram service (disables legacy Go-based bot).

Security Configuration

JWT_SECRET

string

required

Secret key for JWT token signing (minimum 32 characters).Generate with: openssl rand -base64 32

Change this in production - never use default values.

BCRYPT_COST

number

default:"12"

BCrypt hashing cost factor (higher = more secure but slower).Range: 4-31 (recommended: 10-14)

ADMIN_API_KEY

string

required

API key for securing admin endpoints.Generate with: openssl rand -base64 32

External API Keys

COINMARKETCAP_API_KEY

string

CoinMarketCap API key for market data (optional).

Logging Configuration

LOG_LEVEL

string

default:"info"

Logging verbosity level.Options: debug, info, warn, error

LOG_FORMAT

string

default:"json"

Log output format.Options: json, text

Feature Flags

FEATURE_TELEGRAM_BOT

boolean

default:"true"

Enable Telegram bot integration.

FEATURE_WEB_INTERFACE

boolean

default:"true"

Enable web interface.

FEATURE_REAL_TRADING

boolean

default:"false"

Enable real trading (disable for paper trading only).

Only enable this when you’re ready for live trading with real funds.

FEATURE_PAPER_TRADING

boolean

default:"true"

Enable paper trading simulation.

Monitoring Configuration

METRICS_ENABLED

boolean

default:"true"

Enable Prometheus metrics collection.

METRICS_PORT

number

default:"9090"

Port for exposing Prometheus metrics.

Market Data Configuration

MARKET_DATA_COLLECTION_INTERVAL

duration

default:"30s"

Interval for collecting market data from exchanges.

MARKET_DATA_BATCH_SIZE

number

default:"100"

Number of symbols to process in each batch.

Arbitrage Configuration

ARBITRAGE_MIN_PROFIT_THRESHOLD

number

default:"0.5"

Minimum profit threshold percentage for arbitrage opportunities.

ARBITRAGE_MAX_TRADE_AMOUNT

number

default:"1000.0"

Maximum trade amount for arbitrage in quote currency.

ARBITRAGE_CHECK_INTERVAL

duration

default:"10s"

Interval for checking arbitrage opportunities.

Technical Analysis Configuration

TA_CALCULATION_INTERVAL

duration

default:"60s"

Interval for calculating technical indicators.

Test Environment (Development Only)

These variables should only be used in development/testing environments.

TEST_JWT_SECRET

string

JWT secret for testing (development only).

TEST_DB_PASSWORD

string

Database password for testing (development only).

Environment Variable Precedence

Explicitly set environment variables
.env file in repository root
Default values from .env.example
Application defaults

Security Best Practices

Follow these security guidelines for production deployments:

Generate Strong Secrets: Use openssl rand -base64 32 for all secrets
Never Commit Secrets: Add .env to .gitignore
Use Environment-Specific Configs: Separate .env files for dev/staging/prod
Rotate Credentials: Regularly update API keys and secrets
Limit Permissions: Use read-only database users where possible
Enable SSL/TLS: Use secure connections for databases and external services
Monitor Access: Enable audit logging for admin operations

Example Production Configuration

.env

# Core
NEURATRADE_HOME=/var/lib/neuratrade
BACKEND_HOST_PORT=58080
ENVIRONMENT=production

# Database (PostgreSQL)
DATABASE_DRIVER=postgres
DATABASE_URL=postgres://neuratrade:[email protected]:5432/neuratrade?sslmode=require

# Redis
REDIS_HOST=redis.example.com
REDIS_PORT=6379
REDIS_PASSWORD=STRONG_REDIS_PASSWORD

# Security
JWT_SECRET=GENERATED_SECRET_HERE
ADMIN_API_KEY=GENERATED_API_KEY_HERE

# Telegram
TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN
TELEGRAM_USE_POLLING=false
TELEGRAM_WEBHOOK_URL=https://neuratrade.example.com/api/v1/telegram/webhook
TELEGRAM_WEBHOOK_SECRET=GENERATED_WEBHOOK_SECRET

# Features
FEATURE_REAL_TRADING=true
FEATURE_PAPER_TRADING=false

# Monitoring
METRICS_ENABLED=true
LOG_LEVEL=info

Get Started

Core Features

Configuration

Guides

Environment Variables

Overview

Quick Start

Core Configuration

NeuraTrade Home Directory

Network Configuration

Database Configuration

SQLite (Default)

PostgreSQL (Production)

Connection Pool Settings

Redis Configuration

CCXT Service Configuration

Telegram Configuration

Security Configuration

External API Keys

Logging Configuration

Feature Flags

Monitoring Configuration

Market Data Configuration

Arbitrage Configuration

Technical Analysis Configuration

Test Environment (Development Only)

Environment Variable Precedence

Security Best Practices

Example Production Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Guides

​Overview

​Quick Start

​Core Configuration

​NeuraTrade Home Directory

​Network Configuration

​Database Configuration

​SQLite (Default)

​PostgreSQL (Production)

​Connection Pool Settings

​Redis Configuration

​CCXT Service Configuration

​Telegram Configuration

​Security Configuration

​External API Keys

​Logging Configuration

​Feature Flags

​Monitoring Configuration

​Market Data Configuration

​Arbitrage Configuration

​Technical Analysis Configuration

​Test Environment (Development Only)

​Environment Variable Precedence

​Security Best Practices

​Example Production Configuration

Build docs developers (and LLMs) love

Overview

Quick Start

Core Configuration

NeuraTrade Home Directory

Network Configuration

Database Configuration

SQLite (Default)

PostgreSQL (Production)

Connection Pool Settings

Redis Configuration

CCXT Service Configuration

Telegram Configuration

Security Configuration

External API Keys

Logging Configuration

Feature Flags

Monitoring Configuration

Market Data Configuration

Arbitrage Configuration

Technical Analysis Configuration

Test Environment (Development Only)

Environment Variable Precedence

Security Best Practices

Example Production Configuration