> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novosky.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment

> Hardware options, MT5 REST API setup, VPS configuration, and process management with PM2.

## Architecture options

NOVOSKY offers three deployment options. The Go binary option is the simplest for end-users — no Python, no model management, just a single executable.

<Tabs>
  <Tab title="Go binary (simplest)">
    The compiled binary has all ML models embedded. Customers receive three files.

    **What the customer gets:**

    | File                | Description                                             |
    | ------------------- | ------------------------------------------------------- |
    | `novosky_go`        | Compiled binary — models, license, and configs embedded |
    | `config.json`       | User-editable runtime configuration                     |
    | `.env`              | Secrets (MT5 token, Telegram, Supabase)                 |
    | `libonnxruntime.so` | ONNX runtime library (provided alongside binary)        |

    **Hardware requirements (trading only — no retraining):**

    | Component | Minimum                                 |
    | --------- | --------------------------------------- |
    | CPU       | 1 core                                  |
    | RAM       | 512 MB                                  |
    | Disk      | 100 MB                                  |
    | OS        | Linux (Ubuntu 20.04+) or Windows (WSL2) |

    The Go binary is orders of magnitude lighter than the Python bot. No scikit-learn, no LightGBM, no GPU needed.

    **Setup:**

    ```bash theme={null}
    # Place all four files in the same directory
    chmod +x novosky_go
    cp .env.example .env   # fill in MT5 token, Telegram token
    ./novosky_go --dry     # verify connectivity
    ./novosky_go           # live
    ```

    See [Go binary](/developer/go-binary) for the full reference.
  </Tab>

  <Tab title="Option A — Single machine">
    One Linux VPS handles everything: the MT5 API Docker container (via Wine), the trading bot, and weekly retraining.

    | Component | Minimum        | Recommended               |
    | --------- | -------------- | ------------------------- |
    | CPU       | 4 cores        | 8 cores                   |
    | RAM       | 6 GB           | 8 GB                      |
    | Disk      | 40 GB SSD      | 80 GB SSD                 |
    | OS        | Ubuntu 24.04   | Ubuntu 24.04              |
    | Network   | 50 Mbps stable | 100 Mbps stable           |
    | GPU       | —              | NVIDIA (any CUDA-capable) |

    Retraining on the minimum spec (CPU-only, 4 cores) takes \~2–2.5 h. With an NVIDIA GPU the full retrain drops to \~30–45 min. The trading bot itself uses under 300 MB RAM at runtime.

    **Cloud equivalents:** Hetzner CCX23 (~~€15/mo, 8 vCPU/16GB), DigitalOcean 8 GB Droplet (~~\$48/mo), AWS t3.xlarge, Azure D4s v5.

    For GPU training: AWS g4dn.xlarge (T4, \~\$0.50/h spot) or Hetzner GPU server.
  </Tab>

  <Tab title="Option B — Two machines (recommended)">
    **Machine 1 — MT5 API server (Windows)**

    | Component | Spec                                    |
    | --------- | --------------------------------------- |
    | OS        | Windows 10/11 or Windows Server 2019    |
    | CPU       | 2 cores                                 |
    | RAM       | 4 GB                                    |
    | Disk      | 40 GB (MT5 stores tick history)         |
    | Network   | Stable broadband, low latency to broker |

    Runs: MetaTrader 5 terminal + MT5 REST API Docker container on port 6542. Can be a cheap Windows VPS from Vultr, Contabo, or your broker's hosted VPS.

    **Machine 2 — Trading + ML VM (Linux)**

    | Component | Minimum      | Recommended               |
    | --------- | ------------ | ------------------------- |
    | CPU       | 4 cores      | 8 cores                   |
    | RAM       | 6 GB         | 8 GB                      |
    | Disk      | 40 GB SSD    | 80 GB SSD                 |
    | OS        | Ubuntu 24.04 | Ubuntu 24.04              |
    | GPU       | —            | NVIDIA (any CUDA-capable) |

    Runs: `trading.py`, `weekly_optimize.py`, all ML training. Connects to Machine 1 via `API_URL` in `.env`.

    **Why split?** MT5 only runs on Windows. The training stack (scikit-learn, XGBoost, LightGBM) is much easier on Linux. Splitting also means a model retrain crash never affects live trading.
  </Tab>
</Tabs>

### GPU note

Training uses a GPU when one is available via LightGBM's CUDA backend and XGBoost's `device=cuda`. Without a GPU, training falls back to CPU automatically — no configuration change needed.

| Setup                       | Retrain time (all 4 models) |
| --------------------------- | --------------------------- |
| CPU-only, 4 cores           | \~2–2.5 hours               |
| CPU-only, 8 cores           | \~1–1.5 hours               |
| NVIDIA GPU (T4 / RTX 3060+) | \~30–45 minutes             |

<Note>
  If running on Azure or another hypervisor VM, GPU passthrough requires a specific VM type (e.g. Azure NC-series, not the default B/D/E series which have only virtual VGA). CPU-only is perfectly viable for weekly retraining.
</Note>

***

## MT5 REST API setup

The bot does not use the MetaTrader5 Python package. All broker communication goes through a self-hosted HTTP API running on port 6542.

<Steps>
  <Step title="Install MetaTrader 5 on your Windows VM">
    Download and install MT5 from your broker's website. Log in with your trading account credentials.
  </Step>

  <Step title="Install Docker">
    ```powershell theme={null}
    # Windows PowerShell (run as Administrator)
    winget install Docker.DockerDesktop
    ```

    Or install Docker Desktop from docker.com. Make sure it starts on boot.
  </Step>

  <Step title="Pull and run the MT5 REST API container">
    ```powershell theme={null}
    docker pull novosky/mt5-api:latest
    docker run -d \
      --name mt5-api \
      --restart always \
      -p 6542:6542 \
      -e MT5_LOGIN=<your_account_number> \
      -e MT5_PASSWORD=<your_password> \
      -e MT5_SERVER=<broker_server_name> \
      -e API_TOKEN=<choose_a_secret_token> \
      novosky/mt5-api:latest
    ```

    Replace `<your_account_number>`, `<your_password>`, `<broker_server_name>` with your MT5 credentials.
    Set `<choose_a_secret_token>` to a long random string — this is the `API_TOKEN` in your `.env` on the Linux VM.
  </Step>

  <Step title="Verify connectivity">
    From your Linux VM:

    ```bash theme={null}
    curl http://<windows_vm_ip>:6542/ping
    # Expected: {"status": "ok", "time": 1714000000}
    ```
  </Step>
</Steps>

<Note>
  If you are using a broker-provided hosted VPS with MT5 pre-installed, skip Docker and configure the API container to connect to the already-running MT5 terminal.
</Note>

***

## Linux VM setup

```bash theme={null}
# Run the automated VM setup script
./setup-vm.sh

# Or manually:
sudo apt update && sudo apt upgrade -y
sudo apt install -y python3.11 python3.11-venv git htop tmux libgomp1

# Clone repo
git clone <repo> && cd novosky
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Set up .env
cp .env.example .env
# Edit .env with your credentials
```

***

## Process management (PM2)

PM2 keeps the trading bot running continuously and restarts it if it crashes (but **not** after a hard halt — `sys.exit(99)` is intentional).

```bash theme={null}
# Install PM2
npm install -g pm2

# Start the bot
pm2 start ecosystem.config.js
pm2 save
pm2 startup   # install as system service

# Check status
pm2 status
pm2 logs novosky --lines 50

# Restart after config or code changes
pm2 restart ecosystem.config.js --update-env

# Restart after a hard halt (check the reason first)
pm2 restart novosky
```

`ecosystem.config.js` is pre-configured for `trading.py`. It reads `.env` automatically at startup.

<Warning>
  After a hard halt (`sys.exit(99)`), do not restart automatically. First check the reason in the logs, update `starting_balance_usd` in `config.json` to your current balance, then restart manually.
</Warning>

<Warning>
  PM2 snapshots the environment at first start. If you change any value in `.env` — for example rotating a Telegram bot token or updating `API_URL` — a plain `pm2 restart` will keep using the old cached values. Always restart with `--update-env` after any `.env` change:

  ```bash theme={null}
  pm2 restart ecosystem.config.js --update-env
  ```

  To verify what PM2 is actually using before debugging a token or connection error:

  ```bash theme={null}
  pm2 env 0 | grep TELEGRAM
  pm2 env 0 | grep API_URL
  ```
</Warning>

***

## Cron setup (weekly optimize)

The first optimize run installs the cron job automatically. To verify or install manually:

```bash theme={null}
# Check existing cron jobs
crontab -l

# Manual install
crontab -e
# Add:
# 0 2 * * 0 cd /path/to/novosky && .venv/bin/python scripts/weekly_optimize.py --profile balanced >> logs/weekly_optimize.log 2>&1
```

***

## Firewall

The MT5 REST API on your Windows VM should only be accessible from your Linux trading VM. Restrict port 6542 accordingly:

```
# Windows Firewall — inbound rule
Allowed source IP: <linux_vm_ip>
Port: 6542 (TCP)
```

Do not expose port 6542 publicly.