From ebe4e34047512903dccce906a931d2f4c574bc9e Mon Sep 17 00:00:00 2001 From: root Date: Wed, 10 Jun 2026 10:13:42 -0700 Subject: [PATCH] Package for public GitHub release MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add open-source scaffolding and CI; remove Claude-specific dev notes from the published tree. - Remove CLAUDE.md from tracking (kept locally, now git-ignored). - CHANGELOG.md (Keep a Changelog; v1.0 → v1.1.1). - SECURITY.md (private vuln reporting + operator guidance). - CONTRIBUTING.md (dev setup, conventions, PR flow). - .github/: bug + feature issue templates, PR template. - .github/workflows/ci.yml: byte-compile, validate example config, docker build. - .github/workflows/release.yml: on a version tag, publish a multi-arch (amd64 + arm64) image to GHCR. - README: license/release/CI badges, prebuilt-image (GHCR) run instructions, and a corrected Python-version note (3.9–3.11; netifaces caveat). Badges and image names use an `OWNER` placeholder to replace with the GitHub namespace after the repo is created. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/ISSUE_TEMPLATE/bug_report.md | 29 ++++ .github/ISSUE_TEMPLATE/feature_request.md | 18 +++ .github/PULL_REQUEST_TEMPLATE.md | 19 +++ .github/workflows/ci.yml | 30 ++++ .github/workflows/release.yml | 52 +++++++ .gitignore | 1 + CHANGELOG.md | 48 +++++++ CLAUDE.md | 159 ---------------------- CONTRIBUTING.md | 59 ++++++++ README.md | 24 +++- SECURITY.md | 35 +++++ 11 files changed, 313 insertions(+), 161 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/release.yml create mode 100644 CHANGELOG.md delete mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..764f468 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,29 @@ +--- +name: Bug report +about: Report something that isn't working +title: "[Bug] " +labels: bug +--- + +**Describe the bug** +A clear description of what's wrong. + +**To reproduce** +Steps to reproduce the behavior: +1. … +2. … + +**Expected behavior** +What you expected to happen. + +**Screenshots / logs** +If applicable, add screenshots or server log output. + +**Environment** +- ADS-Bit version (admin header or `GET /api/config`): +- Install method: [ ] bare metal [ ] Docker [ ] Podman +- OS / Python version: +- Receiver / feed (e.g. dump1090, readsb) and how it's reached: + +**Additional context** +Anything else that might help. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..3f0e963 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,18 @@ +--- +name: Feature request +about: Suggest an idea or improvement +title: "[Feature] " +labels: enhancement +--- + +**What problem does this solve?** +A clear description of the need or pain point. + +**Proposed solution** +What you'd like to happen. + +**Alternatives considered** +Any other approaches you thought about. + +**Additional context** +Mockups, examples, or references. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..93099c0 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +## Summary + + + +## Related issues + + + +## How was this tested? + + + +## Checklist + +- [ ] Server starts and the change works locally (`python3 server.py`) +- [ ] If admin assets changed, bumped the `?v=` cache-bust token in `admin/admin.html` +- [ ] If behavior/version changed, updated `VERSION` and `CHANGELOG.md` +- [ ] No secrets or local config committed (`config.json` stays ignored) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..405677f --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,30 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + +jobs: + python: + name: Python checks + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + - name: Install dependencies + run: pip install -r requirements.txt + - name: Byte-compile server + run: python -m compileall -q server.py + - name: Validate example config is valid JSON + run: python -c "import json; json.load(open('config.json.example'))" + + docker: + name: Docker build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Build image + run: docker build -t ads-bit:ci . diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..601f43d --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,52 @@ +name: Release + +# Build and publish a multi-arch image to GitHub Container Registry (GHCR) +# whenever a version tag is pushed (e.g. v1.1.2). Lets users run a prebuilt +# image — including on Raspberry Pi (arm64) — without building locally. + +on: + push: + tags: ["v*"] + +permissions: + contents: read + packages: write + +jobs: + image: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Compute lowercase image name + id: img + run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT" + + - uses: docker/setup-qemu-action@v3 + - uses: docker/setup-buildx-action@v3 + + - name: Log in to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Docker metadata (tags & labels) + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ steps.img.outputs.name }} + tags: | + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=raw,value=latest + + - name: Build and push + uses: docker/build-push-action@v6 + with: + context: . + platforms: linux/amd64,linux/arm64 + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} diff --git a/.gitignore b/.gitignore index c1e815c..d863243 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ __pycache__/ # Claude Code .claude/ +CLAUDE.md # Gitea token .gitea-token diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e09718b --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,48 @@ +# Changelog + +All notable changes to this project are documented here. The format is based +on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to +[Semantic Versioning](https://semver.org/). + +## [1.1.1] - 2026-06-10 + +### Added +- `/health` endpoint (status, version, receiver/flight counts) plus a Docker + `HEALTHCHECK`. +- `ADSBIT_CONFIG` environment variable to override the config file path. + +### Changed +- Docker first-run now works with no manual steps: `config.json` is auto-seeded + from `config.json.example` by `docker-entrypoint.sh` and persisted on a + `./data` directory mount (removing the single-file bind-mount footgun). +- Network auto-scan skips subnets larger than `/20` (e.g. a Docker bridge + `172.17.0.0/16`) so discovery no longer stalls startup on Docker hosts. +- `SIGTERM`/`SIGINT` (`docker stop`, `systemctl stop`) shut down cleanly + without a stack trace. + +## [1.1.0] - 2026-06-09 + +### Added +- In-app pixel editor for sprites (admin → Sprites → EDIT): pencil, eraser, + color picker, fill bucket, line/rectangle/ellipse shapes, rectangular + select with move/cut/copy/paste, reference-image overlay, brush size & + opacity, custom + recent palettes, zoom/pan, grid, undo/redo. +- Receiver health dashboard: live per-receiver status (receiving / no data / + unreachable), connection testing, a select → save → apply flow, selectable + scan results, and a per-interface scan selector. +- Version surfaced at startup, via `GET /api/config`, and in the admin header. + +### Fixed +- Server crash when restarting receiver connections: cancelled receiver tasks + no longer tear down the main event loop. + +## [1.0] - 2026-01 + +### Added +- Initial release: retro SNES-style side-view ADS-B flight tracker with custom + pixel-art sprites, directional backgrounds, weather, sun/moon, admin panel, + first-run setup wizard, and Docker/Podman support. + +[1.1.1]: https://github.com/OWNER/ADS-Bit/releases/tag/v1.1.1 +[1.1.0]: https://github.com/OWNER/ADS-Bit/releases/tag/v1.1.0 +[1.0]: https://github.com/OWNER/ADS-Bit/releases/tag/v1.0 diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index ab55120..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,159 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -ADS-Bit is a retro SNES-style side-view flight tracker that displays ADS-B aircraft data with custom pixel art sprites. - -## Running the Server - -```bash -# Start the server (port configured in config.json, default 2001) -python3 server.py - -# Or use the startup script -./start.sh -``` - -Access at http://localhost:{web_port} (configured in config.json) - -### Deployment / fielding notes - -- **Config path** is overridable via the `ADSBIT_CONFIG` env var (defaults to `config.json` beside `server.py`). Docker uses `/app/data/config.json` on a mounted volume. -- **`/health`** (no auth) returns status/version/receiver/flight counts — used by the Docker `HEALTHCHECK` and any external monitoring. -- **`VERSION`** constant in `server.py` is the single source of truth; surfaced at startup, via `GET /api/config`, and in the admin header. Bump it for releases. -- **Auto-scan** (`scan_for_receivers`) skips subnets larger than `MIN_SCAN_PREFIX` (/20) so a docker `/16` doesn't stall startup; the manual scan endpoint enforces the same limit. -- **`docker-entrypoint.sh`** seeds `config.json` from `config.json.example` on first run, so a fresh `docker compose up` needs no manual steps. SIGTERM/SIGINT shut down cleanly (no traceback). - -## Architecture - -### Components - -- **server.py** - Python WebSocket server using aiohttp - - Reads configuration from config.json - - Auto-scans for ADS-B receivers or connects to configured IPs - - Parses SBS/BaseStation format messages from receivers (port 30003) - - Polls dump1090 JSON API (`/dump1090/data/aircraft.json`) every 5s for ADS-B emitter categories - - Broadcasts flight data (including emitter category) to WebSocket clients every 1 second - - Cleans up flights not seen in 60 seconds - - Serves static files, admin panel, setup wizard, and APIs - - Authentication via bcrypt password hashing and session cookies - -- **config.json** - Configuration file for receiver and location settings - - See CONFIG.md for full documentation - -- **ads-bit.js** - JavaScript rendering engine (Canvas-based) - - Handles WebSocket connection and flight data updates - - Renders 10 FPS retro-style canvas animation - - Layer order (bottom to top): sky gradient → clouds → sun → moon → directional background → grid → aircraft → labels - - Directional backgrounds include horizon, so low sun/moon is realistically occluded - - Aircraft sprites flip horizontally when heading west (track 90°-270°) - - View direction rotates between N/E/S/W (arrow keys or A/D), changing the background - -- **index.html** - Main HTML interface with embedded styles - -- **admin/** - Admin panel (login + tabbed settings UI) - - Theme management: rename display names, upload per-direction background PNGs, create new themes - - Display names stored in `config.json` `theme_names` map (folder name -> display name) - - Receivers tab: live per-receiver health (via `GET /api/admin/receiver-status` and `POST /api/admin/test-receivers`), a select → SAVE & APPLY → auto-test flow, selectable scan results, and a per-interface scan selector - - Version (from `server.py` `VERSION`) is surfaced via public `GET /api/config` and shown in the admin header - - **pixel-editor.js** - In-app Canvas2D pixel editor (Sprites tab "EDIT" button) - - Edits sprites at native 500x333; tools: pencil, eraser, color picker, fill bucket, pan, line, rectangle, ellipse (outline/filled), rectangular select - - Select & move: marquee + floating layer, drag/arrow-nudge, Ctrl+C/X/V clipboard, Delete, Enter/Esc commit - - Zoom/pan, undo/redo (snapshot-per-stroke), grid overlay, brush size & opacity, retro + custom (localStorage) + recent palettes, adjustable reference-image overlay - - Exports a 500x333 PNG via `srcCanvas.toBlob` and POSTs to the existing `/api/admin/sprites/{type}` upload endpoint (no new server route) - - Keyboard: B/E/I/F/L/R/O/M tools, Space=pan, +/-/0 zoom, Ctrl+Z/Y undo/redo, Ctrl+C/X/V, arrows nudge, G grid, Esc close - - **Asset cache-busting:** `admin.html` references `admin.css`/`admin.js`/`pixel-editor.js` with a `?v=YYYYMMDD[x]` query — bump it whenever those files change so browsers reload them - -- **setup/** - First-run setup wizard (multi-step configuration) - -### Sprite Assets - -All PNG sprites face right (eastward) and are flipped in-canvas for westbound aircraft: -- 9 aircraft types: smallProp, regionalJet, narrowBody, wideBody, heavy, helicopter, balloon, glider, uav -- Directional backgrounds: north.png, south.png, east.png, west.png (1536x1024, shown based on view direction) -- Celestial: sun.png, moon_6_phases.png (2x3 sprite sheet) -- Weather: happycloud.png (clear), raincloud.png (rain/snow) - -### Aircraft Type Detection Logic - -Two-tier system: real ADS-B emitter categories when available, heuristic fallback otherwise. - -#### Tier 1: ADS-B Emitter Category (from dump1090 JSON API) - -The server polls `http://{receiver_ip}/dump1090/data/aircraft.json` every 5 seconds. The SBS/BaseStation protocol (port 30003) does **not** include emitter category, but the dump1090/readsb JSON API exposes the raw ADS-B transponder category field. When available, this is authoritative and always preferred over heuristics. - -Mapping from DO-260B emitter categories to sprite types: -| ADS-B Category | Description | Sprite | -|---|---|---| -| A1 | Light (< 15,500 lbs) | smallProp | -| A2 | Small (15,500 - 75,000 lbs) | regionalJet | -| A3 | Large (75,000 - 300,000 lbs) | narrowBody | -| A4 | High vortex large (B757) | narrowBody | -| A5 | Heavy (> 300,000 lbs) | wideBody or heavy (by altitude/speed) | -| A6 | High performance (> 5g, > 400 kts) | narrowBody | -| A7 | Rotorcraft | helicopter | -| B1 | Glider / sailplane | glider | -| B2 | Lighter-than-air | balloon | -| B4 | Skydiver drop plane | smallProp | -| B6 | UAV | uav | - -Once an emitter category is received for an aircraft, it is locked in and heuristic re-evaluation is skipped. - -#### Tier 2: Heuristic Fallback (when no emitter category available) - -Priority order when ADS-B category is not available (some transponders don't broadcast it): -1. **Helicopter callsigns**: known operator prefixes (LFE, MED, CHP, PHI, ERA, BHS) or keywords (LIFE, MERCY, COPTER, etc.) -2. **Heavy/Wide body callsigns**: major airline ICAO prefixes (CPA, UAE, ETH, QTR, SIA, AAL, DAL, UAL, FDX, UPS, etc.) + altitude/speed thresholds -3. **Altitude/speed extremes**: altitude > 42000 ft or speed > 550 kts = heavy; > 40000 ft or > 500 kts = wideBody -4. **N-number (US GA registration)**: pattern `N` + digit + 2-4 alphanumerics = smallProp (or narrowBody if above 25000 ft) -5. **Regional airline callsigns**: SKW, RPA, ASH, PDT, CHQ, ENY, JIA, CPZ -6. **Speed/altitude heuristics**: speed < 60 + alt < 5000 = helicopter; alt < 18000 + speed < 300 = smallProp or regionalJet -7. **Altitude-only**: < 10000 ft = smallProp, < 25000 ft = regionalJet, higher = narrowBody -8. **Default**: narrowBody (re-evaluated when better data arrives) - -Important: `speed=0` or `altitude=0` means data not yet received, not actual zero. The system re-categorizes when better data arrives (speed > 0 and callsign present). - -### View Direction Controls - -The viewer can rotate between cardinal directions (N/E/S/W), showing aircraft in a 90° field of view: -- **Keyboard**: Left/Right arrow keys or A/D keys -- **UI**: Arrow buttons on the interface -- Each direction displays a unique background image (north.png, east.png, south.png, west.png) -- Sun and moon positions are calculated based on actual azimuth and only appear when in the current field of view - -### External APIs - -- **Open-Meteo**: Weather and sunrise/sunset data (updates every 10 minutes) -- **ADS-B Receivers**: SBS/BaseStation protocol on port 30003 (flight data) -- **dump1090 JSON API**: `http://{receiver}/dump1090/data/aircraft.json` on port 80 (emitter categories, polled every 5s) - -## Dependencies - -Python packages required: -- aiohttp (web server and WebSocket) -- netifaces (network interface scanning) -- bcrypt (password hashing) - -No package.json - frontend is vanilla JavaScript with no build step. - -## Key Code Patterns - -- Canvas version parameter on assets (`?v=36`) for cache busting -- Aircraft direction: `const isFacingLeft = flight.track > 90 && flight.track < 270` -- Moon phases use sprite sheet cropping with 2x3 grid (3 columns, 2 rows) -- Flight data stored in global `flights` dict keyed by ICAO hex code - -## Debugging - -```bash -# Check for running server instances -ps aux | grep server.py - -# Kill all instances -pkill -9 -f server.py - -# Test receiver connectivity (replace with your receiver IP) -nc -zv 30003 -``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5276325 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +# Contributing to ADS-Bit + +Thanks for your interest in improving ADS-Bit! Contributions of all kinds — +bug reports, features, sprites, themes, docs — are welcome. + +## Development setup + +ADS-Bit is a Python (aiohttp) backend with a vanilla-JavaScript frontend. +There is **no build step** for the frontend. + +```bash +git clone +cd ADS-Bit +pip install -r requirements.txt # Python 3.9–3.11 recommended (see note below) +cp config.json.example config.json # optional; the setup wizard runs otherwise +python3 server.py # serves on http://localhost:2001 +``` + +Or with Docker (no local Python needed): + +```bash +docker compose up -d +``` + +> **Python version note:** the `netifaces` dependency can be hard to build on +> Python 3.12+. Use Python 3.9–3.11, or just use the Docker image (Python 3.11). + +## Project layout + +- `server.py` — aiohttp server: receiver connections, flight state, APIs, auth. +- `ads-bit.js` / `index.html` — Canvas-based retro viewer. +- `admin/` — admin panel, including the in-browser `pixel-editor.js`. +- `setup/` — first-run setup wizard. +- `images/`, `backgrounds/` — sprite and theme assets. + +## Conventions + +- **Frontend assets are cache-busted** via a `?v=YYYYMMDD[x]` query in + `admin/admin.html`. If you change `admin.css`, `admin.js`, or + `pixel-editor.js`, bump that token so browsers reload them. +- The `VERSION` constant in `server.py` is the single source of truth; bump it + for releases and add a `CHANGELOG.md` entry. +- Keep the retro aesthetic (Press Start 2P, blue/gold palette) for UI work. +- Match the style of surrounding code; no frontend framework or build tooling. + +## Submitting changes + +1. Fork and create a topic branch (`feature/…`, `fix/…`, `chore/…`). +2. Make focused commits with clear messages. +3. Verify locally: the server starts, the page loads, and your change works. + For Docker changes, confirm `docker build` succeeds. +4. Open a pull request describing what changed and how you tested it. + +CI will byte-compile the server, validate `config.json.example`, and build the +Docker image on every PR. + +## Reporting bugs / requesting features + +Use the issue templates. For security issues, see [SECURITY.md](SECURITY.md). diff --git a/README.md b/README.md index 828ab04..f62c62f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,11 @@ # ADS-Bit +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Release](https://img.shields.io/github/v/release/OWNER/ADS-Bit)](https://github.com/OWNER/ADS-Bit/releases) +[![CI](https://github.com/OWNER/ADS-Bit/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/ADS-Bit/actions/workflows/ci.yml) + +> **Setup note:** replace `OWNER` with your GitHub username/org throughout this README (badges and image names) after creating the repository. + A retro SNES-style side-view flight tracker that displays ADS-B aircraft data with custom pixel art sprites. ![ADS-Bit Screenshot](screenshots/screenshot.png) @@ -41,7 +47,21 @@ On first run, visit http://localhost:2001 and the setup wizard will guide you th - [Docker](https://docs.docker.com/get-docker/) with Compose V2, **or** [Podman](https://podman.io/) with `podman-compose` -### First Run +### Run the prebuilt image (no clone needed) + +Once a release is published, a multi-arch image (amd64 + arm64, e.g. Raspberry Pi) +is available from GitHub Container Registry: + +```bash +docker run -d --name ads-bit --network host --restart unless-stopped \ + -e ADSBIT_CONFIG=/app/data/config.json \ + -v "$PWD/data:/app/data" \ + ghcr.io/OWNER/ads-bit:latest +``` + +Then open http://localhost:2001 and complete the setup wizard. + +### Build from source ```bash # Build and start — no config step needed @@ -92,7 +112,7 @@ Host networking (`network_mode: host`) is used so the server can auto-scan your ## Requirements -- Python 3.8+ +- Python 3.9–3.11 (3.12+ may require build tools for `netifaces`; the Docker image uses 3.11) - ADS-B receiver providing SBS/BaseStation format on port 30003 (dump1090, readsb, etc.) - Modern web browser with Canvas support diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..bb58643 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,35 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +|---------|-----------| +| 1.1.x | ✅ | +| < 1.1 | ❌ | + +## Reporting a Vulnerability + +Please **do not** open a public issue for security vulnerabilities. + +Instead, use GitHub's private vulnerability reporting: +**Security → Report a vulnerability** on the repository. + +Include as much detail as you can: +- Affected version (see the version in the admin header or `GET /api/config`) +- Steps to reproduce / proof of concept +- Impact and any suggested remediation + +You can expect an acknowledgement within a few days. Please allow reasonable +time for a fix before any public disclosure. + +## Security Notes for Operators + +ADS-Bit is intended for trusted LANs, not direct exposure to the public +internet. If you must expose it: + +- Set a strong admin password (changed from the setup default). +- Put it behind HTTPS via a reverse proxy or tunnel (e.g. Caddy, nginx, + Tailscale). The built-in server speaks plain HTTP. +- Never commit your `config.json` — it contains the admin password hash and + session secret. It is git-ignored by default; fresh installs start from + `config.json.example`.