maboni82/nextdns-optimized-analytics-backend repository overview

⁠🚀 NextDNS Optimized Analytics - Backend API

⁠FastAPI-powered DNS analytics engine for NextDNS log processing and visualization

⁠🔍 What This Container Does

This is the backend API server for NextDNS Optimized Analytics — a comprehensive DNS analytics solution that goes beyond NextDNS's standard interface. Built with FastAPI and Python 3.14, this container handles:

• 🔄 Automated NextDNS log fetching via API integration with configurable intervals
• 📊 Advanced analytics with time-series data, domain statistics, and TLD aggregation
• 🗄️ PostgreSQL data storage with optimized queries and Alembic migrations
• 🔍 Sophisticated filtering including domain exclusion, wildcard patterns, and search
• ⚡ Real-time API endpoints for frontend visualization
• 🛡️ Secure authentication with JWT, API key protection, and rate limiting
• 📈 System monitoring with detailed health checks (CPU, memory, disk, uptime)

⁠🚀 Quick Start

⁠Using Docker Compose (Recommended)

services:
  backend:
    image: maboni82/nextdns-optimized-analytics-backend:latest
    ports:
      - "5001:5000"
    environment:
      - POSTGRES_HOST=db
      - POSTGRES_DB=nextdns
      - POSTGRES_USER=nextdns_user
      - POSTGRES_PASSWORD=secure_password_here
      - API_KEY=your_nextdns_api_key
      - PROFILE_IDS=profile1,profile2
      - LOCAL_API_KEY=your_secure_key
    depends_on:
      - db

⁠Standalone Docker Run

docker run -d \
  --name nextdns-backend \
  -p 5001:5000 \
  -e POSTGRES_HOST=db \
  -e POSTGRES_DB=nextdns \
  -e POSTGRES_USER=nextdns_user \
  -e POSTGRES_PASSWORD=secure_password_here \
  -e API_KEY=your_nextdns_api_key \
  -e PROFILE_IDS=profile1,profile2 \
  -e LOCAL_API_KEY=your_secure_key \
  maboni82/nextdns-optimized-analytics-backend:latest

⁠🏷️ Version Tags

We follow a YY.M.PATCH versioning scheme where the patch number resets each month:

• latest — Latest stable build (automatically updated on every push to main)
• 26.2.1, 26.2.2, ... — Specific patch versions within a month
• 26.2 — Monthly release snapshot (created on the 1st of each month)

⁠🌐 API Endpoints

Once running, access the interactive API documentation at:

• Swagger UI: http://localhost:5001/docs
• ReDoc: http://localhost:5001/redoc
• Health Check: http://localhost:5001/health
• Detailed Health: http://localhost:5001/health/detailed

Key endpoints include:

• /logs — Query DNS logs with advanced filtering
• /stats/overview — Real-time dashboard statistics
• /stats/timeseries — Time-based analytics data
• /stats/domains — Top blocked/allowed domains
• /stats/tlds — Top-level domain statistics
• /stats/devices — Device-level statistics
• /profiles — Available NextDNS profiles

⁠🔧 Configuration

⁠Required Environment Variables

# Database
POSTGRES_HOST=db                      # Database hostname
POSTGRES_DB=nextdns                   # Database name
POSTGRES_USER=nextdns_user            # Database user
POSTGRES_PASSWORD=your_db_password    # Database password

# NextDNS API
API_KEY=your_nextdns_api_key          # NextDNS API key
PROFILE_IDS=profile1,profile2         # Comma-separated profile IDs

# API Authentication
LOCAL_API_KEY=your_secure_key         # Local API authentication key

⁠Optional Environment Variables

# Database
POSTGRES_PORT=5432                    # Database port (default: 5432)
PGSSLMODE=require                     # SSL mode for managed databases

# Data Fetching
FETCH_INTERVAL=60                     # Minutes between log fetches (default: 60)
FETCH_LIMIT=100                       # Records per API request (default: 100, max: 1000)

# Logging
LOG_LEVEL=INFO                        # DEBUG, INFO, WARNING, ERROR, CRITICAL

# CORS
ALLOWED_ORIGINS=http://localhost:5002 # Comma-separated allowed origins

# Web Interface Authentication (optional login system)
AUTH_ENABLED=false                    # Enable/disable web UI login
AUTH_USERNAME=admin                   # Login username (default: admin)
AUTH_PASSWORD=your_password           # Login password
AUTH_SECRET_KEY=your-secret-key       # JWT signing key (min 32 chars)
AUTH_SESSION_TIMEOUT=60               # Session timeout in minutes (default: 60)

⁠🏗️ Built With

• FastAPI — Modern, high-performance Python web framework
• SQLAlchemy — Database ORM with PostgreSQL
• Alembic — Database schema migrations
• Pydantic — Data validation and serialization
• APScheduler — Automated log fetching on configurable schedule
• PyJWT — Secure JWT authentication
• SlowAPI — Rate limiting for brute force protection
• Python 3.14 — Latest Python runtime on Debian slim

⁠🔒 Security

• Runs as a non-root user inside the container
• Built-in healthcheck endpoint
• Rate limiting via SlowAPI
• JWT authentication with configurable session timeouts
• Automated vulnerability scanning via Docker Scout and Safety
• Regular dependency updates via Dependabot

⁠🔗 Related

• Frontend: nextdns-optimized-analytics-frontend⁠
• Source Code: GitHub Repository⁠
• Documentation: Complete Setup Guide⁠

⁠🏢 Maintained By

BondIT ApS⁠ — Danish IT consultancy specializing in network analytics and DNS solutions.

Made with ❤️ and ☕ in Denmark 🇩🇰