Setup Tradleware

This guide walks you through deploying a fully sovereign Tradleware instance — from cloning the repo to placing your first live (or dry-run) trade. Covers crypto bots, IBKR stock trading, and Gotify push notifications.

Prerequisites

• Docker and Docker Compose installed (docs.docker.com)
• A Linux machine, Raspberry Pi 4/5, or any amd64/arm64 server
• At least one supported exchange account (OKX, Crypto.com, Independent Reserve, or IBKR)
• Basic terminal comfort (nano, cp, docker)

Step 1 — Clone the Repository

The Docker image is pulled automatically on first run. All you need from GitHub is the docker-compose.yml and the config templates:

git clone --depth 1 https://github.com/cslev/tradleware
cd tradleware

--depth 1 fetches only the latest snapshot — no full git history, minimal download.

Step 2 — Configure Your Environment (.env)

Copy the example and open it for editing:

cp .env.example .env
nano .env

Minimum changes required

DASHBOARD_USERNAME="yourusername"
DASHBOARD_PASSWORD="your-secure-password"

# Randomize the webhook endpoint to block automated bot scans
# Generate with: pwgen -n 14
WEBHOOK_PATH="ka8Moh4aiNgai4"

Full .env reference

Security tip: TRUSTED_IPS lets devices on your home network open the dashboard without typing a password — perfect for a keyboard-less Raspberry Pi display. Set it to your LAN subnet range, e.g. 192.168.1.0/24, or individual IPs.

Step 3 — Configure Your Crypto Bot(s)

Bot configuration lives in bot_configs/crypto/. Copy only the exchanges you use:

cp bot_configs/crypto/okx.yaml.example       bot_configs/crypto/okx.yaml
cp bot_configs/crypto/cryptocom.yaml.example bot_configs/crypto/cryptocom.yaml
cp bot_configs/crypto/ir.yaml.example        bot_configs/crypto/ir.yaml

Edit each file with your real credentials. Example for okx.yaml:

bots:
  - id: mybtcbot              # lowercase — used as trader_id in webhook payloads
    api_key: your_okx_api_key
    secret_key: your_okx_secret_key
    passphrase: your_okx_passphrase
    subaccount_name: tradingbot  # always use a dedicated subaccount
    hostname: my.okx.com
    stablecoin_fiat_pair: USDT/SGD
    crypto_stablecoin_pair: BTC/USDT
    tradleware_api_key: your_per_bot_secret  # openssl rand -hex 32

Key fields:

See bot_configs/crypto/*.yaml.example for all available fields per exchange.

Step 4 — Configure IBKR (Stock Trading)

Skip this section if you are only trading crypto.

IBKR setup uses two files and a separate Docker container for the IB Gateway.

4a — Create config files

cp bot_configs/stock/ibkr.yaml.example bot_configs/stock/ibkr.yaml
cp .env.ibkr.example                   .env.ibkr

4b — Edit .env.ibkr

This file contains your IBKR login credentials. It is only read by the IB Gateway container, never by Tradleware itself:

USERNAME=your_ibkr_username
PASSWORD=your_ibkr_password

# Trading mode: 'paper' or 'live'
IBC_TradingMode=paper

# Read-only API: 'yes' = no orders placed (safe for initial testing)
IBC_ReadOnlyApi=yes

Start with IBC_TradingMode=paper and IBC_ReadOnlyApi=yes until everything is confirmed working.

4c — Edit bot_configs/stock/ibkr.yaml

gateway:
  host: "ib_gateway"   # Docker container name — resolved via tradleware-network DNS
  port: 8888           # Always 8888 — the cslev/ibkr-docker image handles internal routing

bots:
  - id: myapplebot
    account_id: "U1234567"
    symbol: "AAPL"
    extended_hours: false
    fractional_shares: false
    tradleware_api_key: "your_per_bot_secret"  # openssl rand -hex 32

4d — Start the IB Gateway container

Tradleware uses the cslev/ibkr-docker image — a multi-arch (amd64 + arm64) IB Gateway that works natively on both x86 servers and Raspberry Pi:

docker-compose -f docker-compose.ibkr.yml up -d

4e — Monitor the gateway

Allow 30–60 seconds for the gateway to authenticate with IBKR servers:

docker-compose -f docker-compose.ibkr.yml logs -f

You can also monitor the gateway visually via noVNC in your browser — no VNC client required:

http://YOUR_SERVER_IP:6080

4f — Switch to live trading

When you’re ready to go live:

1. Update .env.ibkr:

   IBC_TradingMode=live
   IBC_ReadOnlyApi=no

2. Restart the gateway:

   docker-compose -f docker-compose.ibkr.yml restart

No other changes needed — your bots always connect to port 8888, and the gateway handles routing internally.

Step 5 — Launch Tradleware

docker-compose up -d

Docker pulls cslev/tradleware:latest automatically on first run. This starts:

• The FastAPI backend — validates webhooks and executes exchange API calls
• The Web dashboard — real-time bot status, logs, and fill history
• The Gotify bridge — push notifications for fills and errors (if configured)

Useful commands

# Follow live logs
docker-compose logs -f tradleware

# Stop the stack
docker-compose down

# Update to a new version
docker-compose down
docker-compose pull
docker-compose up -d

Persistent data (bot_configs/ and tradleware_data/logs/) survives restarts — only the container is replaced on updates.

Step 6 — Access the Dashboard

Open your browser and navigate to:

http://YOUR_SERVER_IP:8080

Log in with the DASHBOARD_USERNAME / DASHBOARD_PASSWORD you set in .env. If you added your LAN IP to TRUSTED_IPS, the login step is skipped automatically.

The dashboard shows each bot as a card including:

• Live position and balance
• Recent fill history
• A Webhook Details pane with the exact endpoint URL, a ready-to-use cURL example, and a live test button

Step 7 — Send a Test Webhook

Before connecting TradingView or any live strategy, verify end-to-end with a dry_run webhook — no real order is placed:

curl -X POST http://YOUR_SERVER_IP:8080/YOUR_WEBHOOK_PATH \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_per_bot_secret",
    "trader_id": "mybtcbot",
    "ticker": "BTC/USDT",
    "action": "buy",
    "timestamp": 1700000000,
    "alert_name": "Supertrend Buy Signal",
    "order_size": 10,
    "order_size_type": "percentage",
    "dry_run": true
  }'

You should see the simulated order appear in the dashboard logs. If dry_run is omitted or false, a real order is placed.

Webhook payload reference

Gotify Push Notifications

Gotify is a self-hosted push notification server that sends real-time alerts to your phone whenever a trade executes, an order fails, or anything requires your attention — all without any third-party cloud service.

For a full walkthrough on running Gotify on your Raspberry Pi (including the Android app setup and reverse proxy config), see the author’s detailed guide: How I Run My Entire Digital Life on a Raspberry Pi – Real-Time Notifications with Gotify.

Deploy Gotify on the same Raspberry Pi

The simplest approach is to add Gotify to your existing Docker stack. Create a docker-compose.gotify.yml alongside your existing compose files:

services:
  gotify:
    image: gotify/server-arm64   # use gotify/server for amd64
    container_name: gotify
    restart: unless-stopped
    ports:
      - "8090:80"
    volumes:
      - ./gotify_data:/app/data
    environment:
      - GOTIFY_DEFAULTUSER_PASS=changeme

Use gotify/server instead of gotify/server-arm64 if you are running on an amd64 machine.

Start it:

docker-compose -f docker-compose.gotify.yml up -d

Access the Gotify web UI at:

http://YOUR_SERVER_IP:8090

Log in with username admin and the password you set in GOTIFY_DEFAULTUSER_PASS.

Create a Gotify application token

1. In the Gotify web UI, go to Apps → Create Application
2. Give it a name (e.g. Tradleware)
3. Copy the generated token

Wire Gotify into Tradleware

Add these three lines to your Tradleware .env:

GOTIFY_SERVER_URL=http://YOUR_SERVER_IP:8090
GOTIFY_APP_TOKEN=your_app_token_here
GOTIFY_LOG_LEVEL=30

GOTIFY_LOG_LEVEL=30 means Tradleware will push notifications for WARNING and above — trade fills, order errors, and critical events. Lower it to 20 (INFO) if you want a notification for every successful fill as well.

Restart Tradleware to apply:

docker-compose restart tradleware

Install the Gotify mobile app

Both apps connect directly to your self-hosted Gotify server — no intermediary cloud. Configure them with your server IP/domain and you’ll receive real-time push notifications for every trade event.

Updating Tradleware

docker-compose down
docker-compose pull
docker-compose up -d

Your bot_configs/, .env, and tradleware_data/ are all mounted as volumes and are never touched by the update.

Next Steps

• Set up TradingView webhooks to connect your alerts and start trading