🚀 Quick Start Guide

Get SkysPy up and running in under 5 minutes with Docker.

✈️ Introduction

SkysPy is a real-time aircraft tracking and monitoring platform that processes ADS-B data from your local receiver.

🏗️ Architecture Overview

flowchart TB
    subgraph Frontend["🖥️ Frontend"]
        WEB[Web Dashboard<br/>React SPA]
    end

    subgraph Backend["⚙️ Backend"]
        API[Django API<br/>Daphne ASGI]
        CELERY[Celery Workers<br/>Background Tasks]
    end

    subgraph DataSources["📡 Data Sources"]
        UF[Ultrafeeder<br/>readsb]
    end

    subgraph Storage["💾 Storage"]
        PG[(PostgreSQL<br/>Database)]
        REDIS[(Redis<br/>Cache/Broker)]
    end

    UF <-->|ADS-B Data| API
    WEB <-->|REST/Socket.IO| API
    API <--> CELERY
    API <--> PG
    API <--> REDIS
    CELERY <--> PG
    CELERY <--> REDIS

📋 Prerequisites

📘

Before you begin

Ensure you have the following installed on your system before proceeding with the installation.

📡 ADS-B Data Source

SkysPy requires an ADS-B data source. Choose one of the supported options:

⚠️

No ADS-B Receiver?

Don't worry! You can use development mode with mock data to explore all of SkysPy's features before investing in hardware.

⚡ Quick Start (5-Minute Setup)

Follow these four simple steps to get SkysPy running:

flowchart LR
    A["1️⃣<br/>Clone"] --> B["2️⃣<br/>Configure"]
    B --> C["3️⃣<br/>Launch"]
    C --> D["4️⃣<br/>Enjoy!"]

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#fce4ec

1️⃣ Clone the Repository

git clone https://github.com/your-org/skyspy.git
cd skyspy

2️⃣ Configure Environment

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env with your preferred text editor:

# 📍 Required: Set your antenna location (latitude/longitude)
FEEDER_LAT=47.9377
FEEDER_LON=-121.9687

# 📡 Required: Your ADS-B data source
ULTRAFEEDER_HOST=ultrafeeder
ULTRAFEEDER_PORT=80

# 🔐 Optional: Set a secure secret key for production
DJANGO_SECRET_KEY=your-secure-random-key-here

# 👤 Optional: Configure admin credentials
DJANGO_SUPERUSER_USERNAME=admin
[email protected]
DJANGO_SUPERUSER_PASSWORD=changeme

✅

Minimal Configuration

At minimum, you only need these three settings to get started:

3️⃣ Start with Docker

Launch all services with a single command:

docker compose up -d

📘

What gets started?

This command launches the complete SkysPy stack:

Monitor the startup progress:

docker compose logs -f api

✅

Success Indicator

Wait until you see this message:

Starting Daphne ASGI server...

4️⃣ Access the Dashboard

🎉 You're ready! Open your browser and navigate to:

You should see the SkysPy dashboard with a live map showing aircraft in your area.

🔑 Default Access Points

🎯 First Steps

✅

SkysPy is Running!

Now let's explore what you can do with it.

🗺️ View Aircraft

The main dashboard displays all aircraft currently being tracked:

Aircraft Detail includes:

• 📍 Live position and telemetry
• 🛤️ Flight path history
• 📸 Aircraft photos (when available)
• 📡 ACARS messages (if receiving)

🔍 Filtering Aircraft

Use the filter bar to narrow down aircraft:

🔔 Create an Alert

Set up custom alerts to notify you when specific conditions are met:

1️⃣ Navigate to Alerts in the sidebar

2️⃣ Click Create Rule

3️⃣ Configure your alert:

# Example: Alert when any military aircraft is detected
Name: Military Aircraft Alert
Conditions:
  - Field: military
    Operator: equals
    Value: true
Notifications:
  - Type: Browser notification

📋 Common Alert Examples

📬 Notification Channels

📘

Apprise Integration

SkysPy supports 80+ notification services via Apprise.

# Example notification URLs (add to .env)
APPRISE_URLS=telegram://bot_token/chat_id,discord://webhook_id/webhook_token

🔌 Access the API

SkysPy provides a comprehensive REST API for integration.

📡 REST Endpoints

💻 Example API Requests

Get all aircraft:

curl http://localhost:8000/api/v1/aircraft/

Get specific aircraft by ICAO hex:

curl http://localhost:8000/api/v1/aircraft/A12345/

Get system status:

curl http://localhost:8000/api/v1/system/status/

⚡ Socket.IO Connections

For real-time updates, connect via Socket.IO:

Example Socket.IO connection (JavaScript):

import { io } from 'socket.io-client';

const socket = io('http://localhost:8000', {
  path: '/socket.io/',
});

socket.on('aircraft:update', (data) => {
  console.log('Aircraft update:', data);
});

📚 Interactive API Documentation

🧪 Development Mode

📘

For Development & Testing

Use the dev profile to run SkysPy without a real ADS-B receiver.

# Start with mock ADS-B data
make dev

This starts additional services:

🌐 Development URLs

Stop development services:

make dev-down

🛠️ Common Commands

🐳 Docker Compose

# ▶️ Start all services
docker compose up -d

# 📋 View logs
docker compose logs -f api
docker compose logs -f celery-worker

# ⏹️ Stop all services
docker compose down

# 🔄 Rebuild after code changes
docker compose up -d --build

# 📡 Include ACARS listener
docker compose --profile acars up -d

⌨️ Makefile Shortcuts

# 🧪 Run tests
make test

# 🚀 Start development environment
make dev

# ⏹️ Stop development environment
make dev-down

# 📋 View development logs
make dev-logs

# 🧹 Clean up containers and volumes
make clean

🗄️ Database Operations

# 🐍 Access Django shell
docker compose exec api python manage.py shell

# 📦 Run migrations
docker compose exec api python manage.py migrate

# 👤 Create superuser
docker compose exec api python manage.py createsuperuser

# ✈️ Populate aviation data
docker compose exec api python manage.py populate_data

🔧 Troubleshooting

❌ Common Issues

🛫 No Aircraft Showing

⚠️

Aircraft not appearing on the map?

Follow these diagnostic steps:

1️⃣ Check your ADS-B source is reachable:

curl http://your-ultrafeeder-host/tar1090/data/aircraft.json

2️⃣ Verify environment variables:

docker compose exec api env | grep ULTRAFEEDER

3️⃣ Check Celery worker is processing:

docker compose logs celery-worker | tail -50

🐘 Database Connection Errors

❌

Can't connect to PostgreSQL?

# Check PostgreSQL is healthy
docker compose ps postgres

# View PostgreSQL logs
docker compose logs postgres

🔌 Socket.IO Connection Failed

⚠️

Socket.IO not connecting?

Ensure you're using http:// (not https://) for local connections:

// ✅ Correct for local development
const socket = io('http://localhost:8000', {
  path: '/socket.io/',
});

// ❌ Wrong - HTTPS not configured locally
const socket = io('https://localhost:8000', {
  path: '/socket.io/',
});

💚 Health Check

Verify all services are healthy:

# Check service health
docker compose ps

# API health endpoint
curl http://localhost:8000/health/

# System status
curl http://localhost:8000/api/v1/system/status/

📚 Next Steps

✅

Congratulations!

You have SkysPy up and running. Explore these guides to unlock its full potential:

⚙️ Environment Variables Reference

✅ Essential Settings

🔐 Authentication

🎛️ Features

📬 Notifications

📘

Complete Reference

For the complete environment variable reference, see the Configuration Guide.

💬 Support