Proxmox VM Deployment

Running the telemetry backend on a Proxmox home lab instead of a Mac Mini.

Why Proxmox?

Architecture

ESP32 (Car)
    │
    ▼
HiveMQ Cloud (MQTT)
    │
    ▼
┌─────────────────────────────────────────┐
│         Proxmox VM (Ubuntu)             │
│  ┌───────────────────────────────────┐  │
│  │       Docker Compose Stack        │  │
│  │  ┌─────────┐  ┌──────────────┐   │  │
│  │  │ Bridge  │  │  TimescaleDB │   │  │
│  │  │(Python) │──│  (PostgreSQL)│   │  │
│  │  └─────────┘  └──────┬───────┘   │  │
│  │                      │           │  │
│  │               ┌──────▼───────┐   │  │
│  │               │   Grafana    │   │  │
│  │               │  (Dashboard) │   │  │
│  │               └──────────────┘   │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Stack Components

Docker Compose Services

services:
  timescaledb:     # Port 5432 - Database
  grafana:         # Port 3000 - Dashboard
  bridge:          # No port - MQTT subscriber

Directory Structure

deploy/
├── docker-compose.yml
├── .env                  # Your credentials (git-ignored)
├── .env.example          # Template
├── init-db.sql           # Database schema
├── README.md
├── bridge/
│   ├── Dockerfile
│   ├── requirements.txt
│   └── mqtt_to_timescale.py
└── grafana/
    └── provisioning/
        ├── datasources/
        │   └── timescaledb.yml
        └── dashboards/
            └── dashboards.yml

Setup Guide

1. Create Proxmox VM

Recommended specs:

• CPU: 2 cores
• RAM: 4 GB
• Storage: 32 GB
• OS: Ubuntu 22.04 or Debian 12

2. Install Docker

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

# Verify
docker --version
docker compose version

3. Deploy Stack

# Clone repo or copy deploy folder
cd /opt
git clone <repo> tsi-telemetry
cd tsi-telemetry/deploy

# Configure
cp .env.example .env
nano .env  # Add your HiveMQ credentials

# Start
docker compose up -d

4. Verify

# Check all services running
docker compose ps

# Check bridge logs
docker compose logs -f bridge

# Check database
docker compose exec timescaledb psql -U postgres -d telemetry \
  -c "SELECT COUNT(*) FROM car_metrics;"

Environment Variables

# .env file
HIVEMQ_HOST=xxxxx.s1.eu.hivemq.cloud
HIVEMQ_PORT=8883
HIVEMQ_USER=esp32
HIVEMQ_PASSWORD=your_password
DB_PASSWORD=telemetry123
GRAFANA_USER=admin
GRAFANA_PASSWORD=your_grafana_password

Networking

Accessing from LAN

Find your VM's IP:

ip addr show

Access Grafana: http://<vm-ip>:3000

Port Forwarding (if needed)

On your router, forward:

• Port 3000 → VM:3000 (Grafana)

Or use a reverse proxy like Traefik or nginx.

Management

Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f bridge
docker compose logs -f timescaledb
docker compose logs -f grafana

Restart

# All services
docker compose restart

# Specific service
docker compose restart bridge

Update

docker compose pull
docker compose up -d

Backup Database

# Backup
docker compose exec timescaledb pg_dump -U postgres telemetry > backup_$(date +%Y%m%d).sql

# Restore
cat backup.sql | docker compose exec -T timescaledb psql -U postgres -d telemetry

Proxmox-Specific Tips

Snapshots

Take a VM snapshot before major changes:

Proxmox UI → VM → Snapshots → Take Snapshot

Resource Monitoring

Monitor VM resources in Proxmox UI or inside VM:

htop
docker stats

Auto-start on Boot

Docker Compose services have restart: unless-stopped so they'll auto-start.

Ensure Docker starts on boot:

sudo systemctl enable docker

Comparison: Mac Mini vs Proxmox

Troubleshooting

Container won't start

docker compose logs <service>
docker compose up <service>  # Run in foreground

Database connection refused

Wait for TimescaleDB to be healthy:

docker compose ps  # Should show "healthy"

Bridge not receiving messages

1. Check credentials in .env
2. Verify HiveMQ cluster is running
3. Test from command line:

   docker compose exec bridge python -c "
   import os
   print(f'Host: {os.environ.get(\"HIVEMQ_HOST\")}')"
   

Out of disk space

# Clean up Docker
docker system prune -a