# Financial Aggregator - Deployment Guide

Docker-based MQTT aggregation server for ESP32 financial dashboards.

## Architecture

```
[Yahoo/Finnhub APIs] --> [Aggregator] --> [Mosquitto] <-- [ESP32 devices]
                                                    ^
                                                    |
                                               [Caddy/TLS]
```

## Quick Start

### 1. Prerequisites

- Debian 12 VM (1 CPU, 1GB RAM, 10GB disk minimum)
- Domain with DNS pointing to VM IP
- Ports 80, 443, 1883, 9001 open

### 2. Install Docker

```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
```

### 3. Configure

```bash
cd /path/to/financial-aggregator/server

cp aggregator/.env.example aggregator/.env
```

Edit `aggregator/.env`:
```env
MQTT_HOST=mosquitto
MQTT_PORT=1883
MQTT_USER=esp32
MQTT_PASS=<your_secure_password>
MQTT_TOPIC=finance/prices
FINNHUB_API_KEY=d74t3bpr01qg1eo6pln0
```

### 4. Create MQTT Password

```bash
docker run --rm -v $(pwd)/mosquitto:/mosquitto eclipse-mosquitto:2 \
  mosquitto_passwd -c /mosquitto/passwd esp32
```

Enter password when prompted (must match `.env`).

### 5. Configure Domain

Edit `caddy/Caddyfile` - replace placeholders:
- `your-email@example.com` → Your email for Let's Encrypt
- `mqtt.yourdomain.com` → Your actual domain

### 6. Deploy

```bash
docker compose up -d
```

### 7. Verify

```bash
docker compose logs -f aggregator
```

Should see: `Published 3 prices: {'btc': ..., 'gold': ..., 'silver': ...}`

## VM Setup (Proxmox)

### Create VM

```bash
# In Proxmox web UI:
# 1. Create VM: Debian 12, 1 CPU, 1GB RAM, 10GB disk
# 2. Start VM, open console
# 3. Login as root
```

### Network Configuration

```bash
# Edit network config
nano /etc/network/interfaces

# Add static IP:
# iface eth0 inet static
#     address 192.168.1.100/24
#     gateway 192.168.1.1
#     dns-nameservers 8.8.8.8

systemctl restart networking
```

### Update System

```bash
apt update && apt upgrade -y
apt install -y curl git
```

## DNS Configuration

Add A record for your domain:
```
mqtt.yourdomain.com.  IN  A  <VM_IP_ADDRESS>
```

## Troubleshooting

### Check container status

```bash
docker compose ps
```

### View logs

```bash
docker compose logs -f caddy
docker compose logs -f mosquitto
docker compose logs -f aggregator
```

### Test MQTT connection

```bash
docker run --rm -it eclipse-mosquitto:2 \
  mosquitto_sub -h mqtt.yourdomain.com -p 9001 \
  -u esp32 -P <password> -t "finance/#" -v
```

### Common Issues

| Issue | Solution |
|-------|----------|
| Caddy certificate fails | Verify DNS points to VM, check port 80/443 open |
| Mosquitto auth fails | Re-run `mosquitto_passwd`, restart containers |
| Aggregator can't connect | Check Mosquitto logs, verify `.env` matches passwd |
| ESP32 won't connect | Verify MQTT user/pass, check firewall allows port 9001 |

## Security Notes

- **Never commit** `.env` or `passwd` files to git
- **Use strong passwords** for MQTT users
- **Rotate API keys** periodically
- **Restrict firewall** to only necessary ports
- **Monitor logs** for suspicious activity

## Ports

| Port | Service | Purpose |
|------|---------|---------|
| 80 | Caddy | HTTP (redirects to HTTPS) |
| 443 | Caddy | HTTPS/TLS termination |
| 1883 | Mosquitto | MQTT (internal) |
| 9001 | Mosquitto | WebSocket (via Caddy) |

## Resource Usage

Approximate for 20+ devices:
- CPU: ~5% average
- RAM: ~300MB
- Disk: ~2GB
- Network: ~10KB/minute inbound, ~50KB/minute outbound

## Scaling

The architecture supports 200+ devices:
- Mosquitto: handles 10K+ concurrent connections
- Aggregator: single instance sufficient
- Caddy: handles TLS termination efficiently

For larger deployments, consider:
- MQTT cluster (Mosquitto replication)
- Load balancer for aggregators
- Redis for message distribution