# AegisTrade AI — cPanel Deployment & Compatibility Guide

## 1. Critical Financial Safety Advisory

> [!WARNING]
> **Shared cPanel Hosting is NOT Recommended for Live Autonomous Trading.**
>
> AegisTrade AI's Prime Directive is **Capital Preservation**. Standard shared cPanel hosting introduces critical operational risks that can lead to unmanaged financial losses:
> 1. **Aggressive Process Reapers (CloudLinux LVE / CageFS)**: Shared hosting environments automatically kill background Python processes and long-running threads that exceed 60–120 seconds of CPU or memory quotas.
> 2. **WebSocket & Connection Drops**: Real-time market streaming and heartbeat watchdogs require persistent socket connections. Shared hosting drops idle connections.
> 3. **Delayed Stop-Loss & Order Reconciliation**: If cPanel terminates your process while a position is open, the bot cannot monitor or reconcile exchange stops.
> 4. **WSGI vs. ASGI**: cPanel's native "Setup Python App" relies on Phusion Passenger (WSGI), whereas FastAPI is built on ASGI (asynchronous event loop).

---

## 2. Recommended Deployment Scenarios

If you want or need to use cPanel, use one of the two safe architectures below:

### Scenario A: cPanel on a Dedicated Cloud VPS (Best Option)
If your cPanel is installed on a VPS (WHM/cPanel) with root access:
- Run AegisTrade AI as a persistent **systemd background service** or **Docker container** on port `8000`.
- Use cPanel Apache/Nginx reverse proxy to forward traffic from your domain to `http://127.0.0.1:8000`.
- This ensures 100% process uptime, full WebSocket support, and zero risk of process termination.

### Scenario B: Shared cPanel Hosting (Research, Backtesting & Web Terminal Only)
If you only have shared cPanel hosting:
- Use it to host the **Web Terminal Dashboard, Backtesting Workbench, and AI Model Center**.
- Run live/demo automated order execution on a dedicated $4–$6/month Linux VPS (Hetzner, DigitalOcean, Linode, AWS Lightsail).

---

## 3. Step-by-Step Shared cPanel Setup (Using "Setup Python App")

If deploying to cPanel via **Phusion Passenger**:

### Step 1: Upload Project Files
1. In cPanel **File Manager**, create a folder outside `public_html` (e.g. `/home/username/aegistrade-ai`).
2. Upload and extract `aegistrade-ai.zip`.
3. Copy `.env.example` to `.env` and fill in your configuration:
   ```bash
   APP_ENV=production
   TRADING_MODE=PAPER
   DATABASE_URL=sqlite:////home/username/aegistrade-ai/data/aegistrade.db
   ```

### Step 2: Configure "Setup Python App" in cPanel
1. Open cPanel and navigate to **Software > Setup Python App**.
2. Click **Create Application**:
   - **Python version**: Select `3.9`, `3.10`, or `3.11`.
   - **Application root**: `aegistrade-ai`
   - **Application URL**: `trading.yourdomain.com` (or subdirectory)
   - **Application startup file**: `passenger_wsgi.py`
   - **Application Entry point**: `application`
3. Click **Create**.

### Step 3: Install Dependencies
1. cPanel will display a command to enter the virtual environment, e.g.:
   ```bash
   source /home/username/virtualenv/aegistrade-ai/3.11/bin/activate && cd /home/username/aegistrade-ai
   ```
2. Open cPanel **Terminal** (or SSH), run the activation command, and install dependencies:
   ```bash
   pip install --upgrade pip
   pip install -r requirements.txt
   pip install a2wsgi
   ```
   *(Note: `a2wsgi` is required to bridge FastAPI's ASGI interface to cPanel Passenger's WSGI interface).*

### Step 4: Configure `.htaccess`
In your domain's document root (e.g. `/home/username/public_html` or subdomain folder), verify that `.htaccess` delegates requests to Passenger:
```apache
PassengerAppRoot "/home/username/aegistrade-ai"
PassengerPython "/home/username/virtualenv/aegistrade-ai/3.11/bin/python"
PassengerAppType wsgi
PassengerStartupFile passenger_wsgi.py

# Forward authorization headers for JWT
RewriteEngine On
RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
```

### Step 5: Prevent Background Sleeping (Cron Heartbeat)
Because shared cPanel freezes inactive Python apps, create a cPanel Cron Job (**cPanel > Advanced > Cron Jobs**) running every minute to ping the health endpoint and keep the worker active:
```bash
* * * * * curl -s https://trading.yourdomain.com/api/v1/health > /dev/null
```

---

## 4. Alternative: Deploy Static Frontend on cPanel + Backend on VPS

You can host the high-performance React dashboard on cPanel as a static site and connect to a VPS backend:
1. In `aegistrade-ai`, the compiled frontend is located in `frontend/dist/`.
2. Copy the contents of `frontend/dist/` into cPanel's `public_html/`.
3. In `public_html/.htaccess`, add:
   ```apache
   <IfModule mod_rewrite.c>
     RewriteEngine On
     RewriteBase /
     RewriteRule ^index\.html$ - [L]
     RewriteCond %{REQUEST_FILENAME} !-f
     RewriteCond %{REQUEST_FILENAME} !-d
     RewriteRule . /index.html [L]
   </IfModule>
   ```
4. Point API calls in `src/services/api.ts` to your secure VPS backend endpoint (`https://api.yourdomain.com`).