AviationWX.org-Bridge

README

AviationWX.org Bridge

Remote bridge device for capturing webcam snapshots and uploading them to AviationWX.org. Designed for low-power single-board computers (SBCs) such as the Raspberry Pi 4 and comparable boards.

Overview

AviationWX.org Bridge is a lightweight daemon that:

• Captures webcam snapshots from local network cameras (HTTP, ONVIF, RTSP)
• Queues images locally with accurate observation timestamps
• Uploads to upload.aviationwx.org via SFTP
• Uses tmpfs (RAM) for image buffering to avoid SD card wear
• Provides a modern web console for configuration and monitoring

Perfect for: Airport operators wanting to provide webcam feeds to pilots for weather assessment and flight safety.

Network: The bridge is a local LAN service (trusted private network or VPN). It is not designed to be reachable from the public internet; do not port-forward the web console. See Network exposure in the deployment guide.

---

Installation

Choose the path that matches your environment:

Path A: Supervised Install (Set and Forget)

Best for: Dedicated single-board computers at remote locations with minimal IT support. Works on a Raspberry Pi or a comparable SBC (see Hardware Requirements).

Run one command and the bridge looks after itself: the host supervisor checks for updates on boot and daily, applies new releases when GitHub has a newer version, rolls back a bad update when health checks fail, and restarts on its own after a crash or capture stall. This is the recommended path for most installs.

One command installs everything:

curl -fsSL https://raw.githubusercontent.com/alexwitherspoon/AviationWX.org-Bridge/main/scripts/install.sh | sudo bash

This script will:

1. Install Docker (if not already installed)
2. Install a lightweight update supervisor
3. Pull and start the AviationWX.org Bridge container
4. Configure automatic security updates
5. Set up automatic restart on boot

After installation:

• Web console: http://<your-device-ip>:1229
• Default password: aviationwx (change this immediately!)
• Updates are checked on boot and once per day (systemd timer)
• New GitHub releases apply automatically when the supervisor finds a newer version (see Updates)

---

Path B: Docker (IT-Managed)

Best for: Professional environments with existing Docker infrastructure and IT teams. This path runs the container directly, without the host supervisor, so updates and rollback are handled by your own tooling. The image is a standard Linux container, so it runs on any Docker engine - Linux, macOS, or Windows.

docker pull ghcr.io/alexwitherspoon/aviationwx-org-bridge:latest

docker run -d \
  --name aviationwx-org-bridge \
  --restart=unless-stopped \
  -p 1229:1229 \
  -v /opt/aviationwx/data:/data \
  --tmpfs /dev/shm:size=200m \
  ghcr.io/alexwitherspoon/aviationwx-org-bridge:latest

Docker Compose:

services:
  aviationwx-org-bridge:
    image: ghcr.io/alexwitherspoon/aviationwx-org-bridge:latest
    container_name: aviationwx-org-bridge
    restart: unless-stopped
    ports:
      - "1229:1229"
    volumes:
      - ./data:/data
    tmpfs:
      - /dev/shm:size=200m  # Adjust based on camera count/resolution

Your responsibility:

• Manage updates via your existing tooling (Portainer, Watchtower, Kubernetes, etc.)
• Monitor container health
• Handle rollbacks if needed

We provide:

• Semantic versioned Docker images (:latest, :1.0.0, :1.0)
• Health: /readyz (capture readiness, used by Docker); /healthz (process status)
• Changelog with breaking changes clearly marked

---

Updates

Supervised Install (Path A)

The host supervisor (aviationwx-supervisor.sh) applies container updates. The in-bridge update checker (hourly GitHub poll) only drives the web console banner and /api/status; it does not pull images.

When	Behavior
Boot	boot-update runs before the container starts
Daily	aviationwx-daily-update.timer fires once per day at midnight local time, with up to 30 minutes jitter
Manual	sudo aviationwx update or web UI Update (writes /data/trigger-update)

Gate	Behavior
Newer version	When installed semver is behind the GitHub release for your channel (latest by default in global.json), the supervisor pulls the image and recreates the container
Release age	Releases younger than 2 hours are skipped unless you force an update or the host rebooted after a watchdog recovery
Rollback	Failed health checks roll back to last-known-good.txt
Release metadata	Supervisor reads min_host_version and deprecates from the GitHub release body. critical and force_update in release notes are informational today; they are not enforced by the supervisor script

Manual update:

sudo aviationwx update

Check status:

sudo aviationwx status
# or
sudo /usr/local/bin/aviationwx-supervisor.sh status

Update availability in the web UI comes from GET /api/status (update.update_available, update.latest_version).

Docker (Path B)

The web console still notifies you when a newer release is available. One-click apply is disabled unless AVIATIONWX_SELF_UPDATE=1 (supervised installs set this automatically). Update the image with your orchestration tooling:

docker pull ghcr.io/alexwitherspoon/aviationwx-org-bridge:latest
docker stop aviationwx-org-bridge
docker rm aviationwx-org-bridge
docker run -d ... # (same run command as before)

---

Configuration

Access the web console at http://<device-ip>:1229/ to configure:

• Camera sources (URL, authentication)
• Capture intervals (1 second to 30 minutes)
• Local timezone (for EXIF interpretation)
• Image processing (resize, quality)
• Queue management settings

SFTP Credentials

Contact contact@aviationwx.org to obtain upload credentials.

Example Config

{
  "version": 2,
  "timezone": "America/Chicago",
  "cameras": [
    {
      "id": "kord-west",
      "name": "KORD West Runway",
      "type": "http",
      "enabled": true,
      "snapshot_url": "http://192.168.1.100/snapshot.jpg",
      "capture_interval_seconds": 60,
      "upload": {
        "protocol": "sftp",
        "host": "upload.aviationwx.org",
        "port": 2222,
        "username": "your-username",
        "password": "your-password"
      }
    }
  ]
}

---

Features

• Multiple Camera Types: HTTP snapshot, ONVIF, RTSP (via ffmpeg)
• Historic Replay: Queue images for time-series display on aviationwx.org
• Accurate Timestamps: UTC observation times with EXIF validation (via exiftool)
• Web Console: Modern dashboard with camera preview and management
• Secure Upload: SFTP with fail2ban-aware retry logic
• Low Memory: Runs lean on small SBCs (1GB minimum, 3GB or more recommended)
• NTP Health: Automatic time validation and drift detection
• Auto Updates: Supervisor applies GitHub releases on boot and daily, with rollback (Path A)
• Hot-Reload: Camera, timezone, and SNTP config changes apply instantly (no restart)

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     AviationWX.org Bridge                       │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Camera    │  │   Camera    │  │    Web Console      │  │
│  │   Worker    │  │   Worker    │  │    (port 1229)      │  │
│  └──────┬──────┘  └──────┬──────┘  └─────────────────────┘  │
│         │                │                                   │
│         ▼                ▼                                   │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │              File Queue (tmpfs /dev/shm)                │ │
│  │   ├── camera-1/                                         │ │
│  │   │   ├── 20231225T143022Z.jpg                          │ │
│  │   │   └── 20231225T143122Z.jpg                          │ │
│  │   └── camera-2/                                         │ │
│  │       └── 20231225T143052Z.jpg                          │ │
│  └─────────────────────────────────────────────────────────┘ │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │              Upload Worker (round-robin)                │ │
│  │   → SFTP to upload.aviationwx.org                        │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

---

Hardware Requirements

The bridge ships as a standard multi-arch Linux container (ARM64 or x86-64, or 32-bit ARMv7). The Docker path runs anywhere a Docker engine runs Linux containers: a single-board computer, mini-PC, server, or VM, on Linux, macOS, or Windows. The supervised install (Path A) additionally requires a Linux host with systemd. The specs below describe the recommended single-board computer.

RAM is the binding constraint, not CPU.

Minimum:

• 1GB RAM
• A 64-bit quad-core CPU in the class of the Raspberry Pi 4 (Cortex-A72 at ~1.5 GHz) or newer; a comparable x86 such as an Intel N100 also clears the bar
• 8GB storage (SD, eMMC, or USB)
• Network access to cameras and the internet

Strongly recommended:

• 3GB or more RAM, for headroom with multiple cameras and higher resolutions
• 16GB+ storage (SD, eMMC, or NVMe)
• Wired ethernet for reliability

Example boards: The Raspberry Pi 4 and 5 are the best-documented choices. Comparable single-board computers also work, including the Radxa ROCK series, Orange Pi 5 series, Libre Computer boards, or an Intel N100-class mini-PC. These are examples, not endorsements; any board that runs 64-bit Linux with Docker and meets the minimum above is a good fit. The Raspberry Pi has the broadest community and OS support, while other boards often offer more RAM, storage, or I/O.

---

Security

• Container runs as non-root user
• Minimal Linux capabilities
• SFTP for secure uploads
• Web console protected by password authentication
• Read-only filesystem (only /data writable)
• Automatic updates via host supervisor (Path A)

---

Troubleshooting

View logs

# Container logs
docker logs aviationwx-org-bridge

# Supervisor logs (Path A, supervised install only)
cat /data/aviationwx/supervisor.log

Restart the bridge

docker restart aviationwx-org-bridge

Force rollback (Path A only)

sudo /usr/local/bin/aviationwx-container-start.sh "$(cat /data/aviationwx/last-known-good.txt)"

Complete reinstall

docker stop aviationwx-org-bridge
docker rm aviationwx-org-bridge
# Re-run installation command

---

Documentation

• Development - Build, test, run locally
• Deployment Guide - Production deployment details
• Queue & Memory Management - How storage and memory are managed
• Config Reference - Full configuration options
• Changelog - Version history

---

Web Console Screenshots

Dashboard

Cameras

Add Camera

Settings

Logs

---

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE

---

Made for pilots, by pilots ✈️

Contact: contact@aviationwx.org