jahmed22/avd-estimator repository overview

⁠🚀 Enterprise AVD Network Estimator

A professional, self-hosted network validation and telemetry tool designed specifically for testing readiness, throughput, and latency for Azure Virtual Desktop (AVD) and enterprise VDI environments.

Unlike standard speed tests, this tool offers true multi-stream TCP throughput testing, a Global RTT Scanner, intelligent AVD Readiness scoring, and persistent historical logging.

⁠📑 Table of Contents

1. Key Features⁠
2. Architecture Overview⁠
3. Prerequisites⁠
4. Quick Start Deployment⁠
5. Environment Variables⁠
6. Admin Dashboard & Broadcasts⁠
7. Multi-Region Global Setup⁠
8. Troubleshooting⁠

⁠✨ Key Features

• 📊 Enterprise Dashboard: Clean, responsive UI with real-time SVG gauge charts, fluid mobile scaling, and a Dark/Light mode toggle.
• 🧠 AVD Readiness Engine: Automatically classifies network results into human-readable VDI readiness scores (e.g., "Optimal for 4K Multi-Monitor" vs. "Basic Office Apps").
• 🌍 Global RTT Scanner: Instantly ping all your global deployment nodes simultaneously to find the lowest latency path.
• 💾 Dual-Persistence Logging: Automatically saves test telemetry (Client IP, OS, Browser, Latency, Throughput) to both a internal MariaDB database and a localized host-mounted CSV file.
• 🔒 Secure Admin Portal: Built-in protected dashboard to view historical logs.
• 📢 Global System Broadcast: Push real-time alert banners to all active users from the admin panel (e.g., maintenance warnings).
• 🐳 Fully Containerized: Configure branding, admin credentials, and regional nodes dynamically via Docker Environment variables—no code changes required.

⁠🏗️ Architecture Overview

The Estimator uses a Single-Image Architecture orchestrated by Docker Compose.

1. Frontend: React 18 + Tailwind CSS v4 + Vite. Uses the LibreSpeed Web Worker engine to prevent UI freezing during aggressive multi-stream testing.
2. Backend: Node.js + Express. Handles garbage data generation for downloads, stream draining for uploads, and API endpoints for logging.
3. Database: MariaDB 10.11. Securely stores test history and admin settings.

⁠⚙️ Prerequisites

• A Linux/Ubuntu server or VM (Azure, AWS, On-Prem)
• Docker⁠ installed
• Docker Compose⁠ installed
• Ports 8080 (or your chosen web port) open on your Network Security Group (NSG) / Firewall.

⁠🚀 Quick Start Deployment

We highly recommend deploying the AVD Estimator using docker-compose to automatically provision the MariaDB database alongside the application.

⁠1. Create your docker-compose.yml

Create a new directory and create the compose file:

version: '3.8'

services:
  db:
    image: mariadb:10.11
    restart: always
    environment:
      MARIADB_ROOT_PASSWORD: rootpassword
      MARIADB_DATABASE: avd_metrics
      MARIADB_USER: avduser
      MARIADB_PASSWORD: avdpass
    volumes:
      - mariadb_data:/var/lib/mysql

  estimator:
    image: jahmed22/avd-estimator:latest
    restart: always
    ports:
      - "8080:8080"
    environment:
      - REGION_NAME=East US Node
      - APP_NAME=Enterprise AVD Tester
      - BUILT_BY=Your Name
      - ADMIN_USER=admin
      - ADMIN_PASS=Secure123
      - DB_HOST=db
      - DB_USER=avduser
      - DB_PASSWORD=avdpass
      - DB_NAME=avd_metrics
      # Add other global nodes here to enable the dropdown and Global RTT Scanner
      - SERVER_LIST=[{"name":"India Node","url":"[http://10.10.](http://10.10.)x.x:8080"}]
    volumes:
      # Maps the CSV logs to your host machine for easy extraction
      - /mnt/azure_storage/avd_logs:/app/logs
    depends_on:
      - db

volumes:
  mariadb_data:

⁠2. Launch the Stack

Run the following command in the same directory as your docker-compose.yml:

docker compose up -d

The application will initialize and be available at http://<your-server-ip>:8080.

⁠🎛️ Environment Variables

Customize the tool completely without touching the underlying code.

⁠🛡️ Admin Dashboard & Broadcasts

To access the backend logs and manage user alerts:

1. Navigate to http://<your-server-ip>:8080/admin
2. Log in using the credentials defined in your ADMIN_USER and ADMIN_PASS variables.
3. Features:

• Log Viewer: View a formatted table of all historical tests, including exact Client IPs, OS/Browser fingerprints, latency, and speeds.
• Global Broadcast: Type a message into the broadcast box and hit publish. A pulsing alert banner will immediately appear on the testing dashboard for all users (useful for maintenance windows).

⁠🌍 Multi-Region Global Setup

To build a global testing network, deploy this container to multiple virtual machines across different Azure/AWS regions.

On each node, populate the SERVER_LIST JSON variable with the URLs of the other nodes.

The UI will automatically:

1. Generate a dropdown menu allowing users to select and test their throughput against any region.
2. Populate the Global RTT Scanner so users can ping all endpoints with a single click.

⁠🔧 Troubleshooting

1. "Bind for 0.0.0.0:8080 failed: port is already allocated"

• You have another container or service running on port 8080. Stop it or change the left side of the port mapping in your docker-compose.yml (e.g., "8081:8080").

2. I changed the Database Password, but the app can't connect.

• MariaDB creates a persistent volume on its first boot. If you change the password in the compose file later, MariaDB ignores it and keeps the original.
• Fix: Bring down the stack and wipe the volumes using docker compose down -v, then bring it back up.

3. The UI loads, but clicking "Start" does nothing.

• Ensure the target server's port is explicitly open on your cloud provider's Network Security Group (NSG) or Firewall.
• If testing across nodes, ensure the URL in your SERVER_LIST includes http:// and the correct port.

⁠Author

Designed and developed by Junaid Ahmed.