financial_aggregator/server/DEPLOYMENT.md

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

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

3. Configure

cd /path/to/financial-aggregator/server

cp aggregator/.env.example aggregator/.env

Edit aggregator/.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

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

docker compose up -d

7. Verify

docker compose logs -f aggregator

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

VM Setup (Proxmox)

Create VM

# 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

# 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

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

docker compose ps

View logs

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

Test MQTT connection

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