WarDragon Analytics - Quick Start Guide

Get up and running with WarDragon Analytics in 5 minutes.

Prerequisites

Before you begin, ensure you have:

Docker (version 20.10 or later)
```
docker --version
```

Docker Compose (version 2.0 or later)

docker-compose --version
# OR
docker compose version

One or more WarDragon kits running DragonSync with API enabled (default port 8088)
Network connectivity between Analytics host and WarDragon kit(s)
System Requirements:
- 2GB RAM minimum (4GB recommended for multi-kit)
- 50GB disk space (for 30 days of data from 5 kits)
- Linux, macOS, or Windows with WSL2

Installing Docker on Ubuntu

If you don't have Docker installed, here's the recommended setup for Ubuntu:

# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository to Apt sources
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

# Install Docker packages
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (avoids needing sudo for docker commands)
sudo usermod -aG docker $USER

Important: After adding your user to the docker group, log out and back in for the change to take effect.

Installation

1. Clone the Repository

git clone https://github.com/alphafox02/WarDragonAnalytics.git
cd WarDragonAnalytics

2. Configure Environment Variables

Copy the example environment file and edit it:

cp .env.example .env
nano .env  # or use your preferred editor

Set these required variables:

# Database password (change this!)
DB_PASSWORD=your_secure_db_password_here

# Grafana admin password (change this!)
GRAFANA_PASSWORD=your_secure_grafana_password_here

# Optional: Custom ports
# WEB_PORT=8090
# GRAFANA_PORT=3000
# DB_PORT=5432

IMPORTANT: Use strong, unique passwords! These will secure your database and Grafana access.

3. Configure WarDragon Kits

Copy the example kits configuration:

cp config/kits.yaml.example config/kits.yaml
nano config/kits.yaml

Edit to add your kit(s):

kits:
  - id: kit-001
    name: "Mobile Unit Alpha"
    api_url: "http://192.168.1.100:8088"
    location: "Field Operations"
    enabled: true

  - id: kit-002
    name: "Fixed Site Bravo"
    api_url: "http://10.0.0.50:8088"
    location: "Headquarters"
    enabled: true

For single-kit local deployment (Analytics on same device as DragonSync):

kits:
  - id: local-kit
    name: "Local WarDragon Kit"
    api_url: "http://127.0.0.1:8088"
    enabled: true

4. Make Scripts Executable

chmod +x scripts/*.sh

Starting Services

Start all services in one command:

./scripts/start.sh

This will:

Pull the latest Docker images
Build the application containers
Start all services in detached mode (including MQTT broker)
Display access URLs

Note: MQTT ingest is enabled by default on port 1883. Configure DragonSync on your kits to push data to this server's IP. See MQTT Ingest Guide for details and security hardening.

Expected output:

WarDragon Analytics - Starting Services
==========================================

Pulling latest Docker images...
Building application images...
Starting containers...

==========================================
WarDragon Analytics is running!
==========================================

Access the services at:
  Web UI:  http://localhost:8090
  Grafana: http://localhost:3000
  MQTT:    mqtt://localhost:1883

Accessing the Interfaces

Web UI (http://localhost:8090)

Main Map: Real-time drone tracks from all kits
Kit Management: Add/remove/configure kits
Export: CSV and KML export for analysis

Grafana (http://localhost:3000)

Default Login:
- Username: admin
- Password: (from your .env file)
Pre-built Dashboards:
- Operations Overview
- Kit Health Monitoring
- Drone Analytics
- Signal Analysis

Testing with Sample Data

Use the included test data generator to simulate drone detections:

python3 app/test_data_generator.py

This will:

Generate realistic drone tracks
Simulate FPV signal detections
Populate the database with test data
Allow you to verify the UI and dashboards

Check the data in:

Web UI: http://localhost:8090
Grafana: http://localhost:3000

Viewing Logs

Tail logs from all services:

./scripts/logs.sh

View logs for a specific service:

./scripts/logs.sh collector      # Collector service only
./scripts/logs.sh timescaledb    # Database only
./scripts/logs.sh web            # Web UI only
./scripts/logs.sh grafana        # Grafana only

Follow logs with custom options:

./scripts/logs.sh -f --tail=50   # Last 50 lines, follow mode

Managing Services

Stop all services (preserve data):

./scripts/stop.sh

Restart services:

./scripts/stop.sh
./scripts/start.sh

Check container status:

docker-compose ps

Database Operations

Backup database:

./scripts/backup.sh

Backups are saved to ./backups/ with timestamp:

wardragon_analytics_20260119_143022.sql.gz

Restore a backup:

gunzip -c backups/wardragon_analytics_20260119_143022.sql.gz | \
  docker-compose exec -T timescaledb psql -U wardragon -d wardragon

Reset database (delete all data):

./scripts/reset-db.sh

WARNING: This permanently deletes all collected data!

Cleanup

Stop containers but keep data:

./scripts/stop.sh

Stop containers and remove them (keep data volumes):

docker-compose down

Complete cleanup (removes all data):

./scripts/cleanup.sh

You'll be prompted to confirm before data deletion.

Keep containers stopped but preserve volumes:

./scripts/cleanup.sh --keep-volumes

Troubleshooting

Services won't start

Check Docker is running:
```
docker ps
```

Check port conflicts:

sudo lsof -i :8090
sudo lsof -i :3000
sudo lsof -i :5432

View error logs:
```
./scripts/logs.sh
```

Cannot connect to WarDragon kit

Verify kit API is accessible:
```
curl http://192.168.1.100:8088/status
```
Check network connectivity:
```
ping 192.168.1.100
```
Verify DragonSync API is enabled on the kit (check DragonSync config)
Check firewall rules on both Analytics host and kit

Database connection errors

Check TimescaleDB container is running:
```
docker-compose ps timescaledb
```
Verify .env DB_PASSWORD matches:
```
grep DB_PASSWORD .env
```
Check database logs:
```
./scripts/logs.sh timescaledb
```

Out of disk space

Check disk usage:
```
df -h
docker system df
```
Clean up old Docker data:
```
docker system prune -a --volumes
```
Reduce data retention (edit timescaledb/init.sql retention policies)

Data Retention

By default, Analytics retains:

Raw data: 30 days (drones, signals)
System health: 90 days
Hourly aggregates: 1 year

To modify retention, edit timescaledb/init.sql and reinitialize:

-- Example: Change to 7 days
SELECT add_retention_policy('drones', INTERVAL '7 days');

Then reset the database:

./scripts/reset-db.sh

Production Deployment Tips

Run on server/cloud instance:

Use strong passwords in .env

Configure firewall to restrict access:

sudo ufw allow from 192.168.1.0/24 to any port 8090
sudo ufw allow from 192.168.1.0/24 to any port 3000

Enable HTTPS with reverse proxy (nginx/Caddy)

Set up automated backups:

# Add to crontab
0 2 * * * cd /path/to/WarDragonAnalytics && ./scripts/backup.sh /mnt/backups

Multi-kit deployment:

Configure all kits in config/kits.yaml
Ensure Analytics host is reachable from all kits
Monitor kit health in Grafana "Kit Health" dashboard
Scale resources if needed (edit docker-compose.yml resource limits)

Next Steps

Explore Grafana dashboards - See pre-built analytics and visualizations
Configure alerts - Set up webhook alerting (Slack, Discord) in .env
Export data - Use CSV export for offline analysis
Enable authentication - Set AUTH_ENABLED=true for password protection
Set up automated backups - Run ./scripts/setup-backup-cron.sh
Customize dashboards - Create your own Grafana panels
Read the docs:

Utility Scripts Reference

Script	Description	Example
`start.sh`	Start all services	`./scripts/start.sh`
`stop.sh`	Stop services gracefully	`./scripts/stop.sh`
`logs.sh`	Tail service logs	`./scripts/logs.sh collector`
`backup.sh`	Backup database	`./scripts/backup.sh /mnt/usb/backups`
`reset-db.sh`	Reset database (delete all data)	`./scripts/reset-db.sh`
`cleanup.sh`	Complete cleanup	`./scripts/cleanup.sh`

Getting Help

Issues: GitHub Issues
DragonSync: alphafox02/DragonSync
Documentation: architecture.md

License

Apache 2.0 (same as DragonSync)

Happy tracking!

FilesExpand file tree

quickstart.md

Latest commit

History