185 lines
3.8 KiB
Markdown
185 lines
3.8 KiB
Markdown
# 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
|