GearBeacon V1.0.0

GearBeacon 1.0.0 — First stable release

GearBeacon 1.0.0 is the first stable release of a private, single-owner, self-hosted Ubiquiti and UniFi Store inventory monitor. Run it on your own Windows PC, Mac, Linux server, NAS, or Docker host and manage it from a responsive web browser.

There is no GearBeacon cloud account, hosted database, public registration, subscription, analytics, or telemetry. Monitoring and notifications run on your server, so a browser does not need to remain open.

What GearBeacon does

Regional UniFi Store monitoring

• Monitors the United States, Canada, Europe, and United Kingdom UniFi Stores from one installation.
• Keeps watchlists, product state, activity, and monitoring health separated by region.
• Discovers catalog products with their name, SKU, category, price, availability, image, and regional Store link.
• Provides a searchable and filterable Browse catalog with category tabs, paging, image retry/fallback behavior, and dark/light themes.
• Shows detailed product drawers with availability, price, SKU, region, first-observed and last-checked times, last change, price history, recent changes, and a direct UniFi Store link.
• Detects restocks, sellouts, price changes, other status changes, newly listed products, and products removed from a complete catalog.

Reliable change detection

• Records a restock immediately when it appears in a complete, valid catalog.
• Requires two matching complete observations before committing a sellout, price change, ordinary status change, or catalog disappearance.
• Preserves the last-known-good value while a potentially destructive change is awaiting confirmation.
• Marks a product Unlisted after two complete catalogs omit it instead of silently deleting it.
• Prevents partial or malformed catalogs from advancing missing-product evidence or creating false transitions.
• Persists pending confirmation evidence across restarts.
• Honors upstream Retry-After guidance and uses exponential backoff with jitter after failures.

Watchlists and alert rules

• Adds products directly from Browse or imports them from pasted UniFi Store URLs, SKUs, product slugs, TXT, CSV, or JSON files.
• Reviews regional matches, duplicates, and already-watched products before an import changes the watchlist.
• Searches, filters, sorts, selects, pauses, resumes, and removes watched products individually or in bulk.
• Supports global alert defaults and per-product overrides for restocks, sellouts, price changes, status changes, price drops, and target prices.
• Supports temporary or indefinite alert pauses.
• Allows selected restocks to bypass quiet hours and digest scheduling for immediate delivery.

Activity, evidence, and history

• Keeps a durable Stock activity feed with exact before-and-after transitions, prior-state duration, price movement, region, detection time, and notification outcome.
• Provides confirmation evidence for each event, including the policy used, observation count, first-observed time, confirmed time, and server-alert result.
• Supports text, region, event-type, date, and notification-outcome filters with pagination.
• Exports retained activity to CSV or JSON.
• Stores change-only product observations for price history and recent-change views.
• Uses independently configurable product-history and activity-retention periods.

Notifications

GearBeacon can deliver alerts through:

• Responsive HTML and plain-text SMTP email
• ntfy, including self-hosted servers
• Discord webhooks
• Gotify
• Generic JSON webhooks
• Browser notifications

Notification jobs are stored durably in SQLite before delivery. Failed deliveries use bounded exponential retries and remain visible in Operations, where the owner can retry them. GearBeacon also supports notification grouping, per-product cooldowns, timezone-aware quiet hours, daily digests, test notifications, and an optional All activity updates mode for every new Activity entry—including unwatched products.

Email notifications include event-specific layouts for restocks, target prices, price drops, sellouts, status changes, new products, operational warnings, tests, and grouped digests. Appearance controls include compact/standard/detailed layouts, automatic/light/dark themes, subject prefixes, price calculations, alert explanations, embedded product images, digest limits, and desktop/mobile previews. Email contains no tracking pixels, scripts, remote fonts, or analytics.

Generic webhooks support optional bearer authentication and HMAC-SHA256 signatures over the exact body and timestamp. SMTP uses implicit TLS on port 465 or requires STARTTLS by default on other ports, validates certificates by default, and never sends credentials over an unencrypted connection.

Operational health

• Shows an overall Healthy, Degraded, or Action Required state.
• Displays per-region check timing, catalog results, product/watch counts, pending confirmations, and retry state.
• Reports queued, delivered, and failed notifications with next-delivery timing and failure details.
• Tracks database size, available disk space, backup health, secondary-copy health, recovery readiness, access-security warnings, runtime architecture, build commit, and container image information.
• Can alert the owner about repeated monitor failures, exhausted notification deliveries, scheduled-backup failures, and low disk space.
• Provides filtered downloadable logs without exposing raw secrets to the browser.
• Runs installation diagnostics covering SQLite integrity, data and backup access, encryption-key decryption, restore readiness, free space, notification delivery, Store connectivity, and access-mode security.
• Generates a privacy-redacted support bundle that excludes owner credentials, integration secrets, webhook URLs, local paths, private host addresses, and product/watchlist data.

Upgrade-safe data and recovery

• Stores persistent state in an operating-system application-data directory or Docker /data volume rather than the application directory.
• Uses transactional, append-only SQLite migrations with automatic safety backups before schema upgrades and imports.
• Creates validated scheduled, manual, pre-import, and pre-update backups.
• Verifies primary backups with SQLite integrity checks and consistent snapshots.
• Can copy backups to a separate disk, mounted share, or NAS location.
• Supports passphrase-encrypted secondary recovery exports using AES-256-GCM with a scrypt-derived key.
• Tests the latest primary or secondary backup non-destructively without changing the active database.
• Exports encrypted transfer files, previews imports, and preserves watchlists, rules, history, and settings through supported upgrades.
• Keeps a successful primary backup valid even if its optional secondary copy fails.

Private owner access and security

GearBeacon has three explicit access modes:

Mode	Default bind	Owner password	Intended use
Local	127.0.0.1	Optional	One computer
Private	0.0.0.0	Required	Trusted LAN, private VPN, server, or container
Proxy	127.0.0.1	Required	HTTPS reverse proxy on the same host

• Refuses unauthenticated local mode on a non-loopback address.
• Uses a one-time setup token for the first authenticated setup.
• Protects owner access with scrypt password hashing, throttled sign-in, hashed sessions, CSRF validation, origin validation, secure cookie controls, session inspection/revocation, and password rotation/recovery.
• Restricts reverse-proxy forwarded-header trust to a same-host loopback proxy and supports secure cookies and HSTS when an HTTPS public URL is configured.
• Encrypts saved notification credentials with an installation key stored outside SQLite and protected with restricted filesystem permissions.
• Applies a restrictive Content Security Policy and standard browser security headers.
• Fetches product images only from an exact Ubiquiti host allowlist with redirect, timeout, size, and content-type limits.

GearBeacon is designed for local networks, private VPNs, or a maintained HTTPS reverse proxy with restricted access. Do not expose it directly to the unrestricted internet.

Browser experience and accessibility

• Responsive dashboard for desktop, tablet, and mobile browsers; no native mobile application is required.
• Tested at a 390-pixel viewport and 200% browser zoom without horizontal page overflow.
• Supports keyboard navigation, visible focus indicators, accessible tab and dialog behavior, focus containment/restoration, Escape handling, live status announcements, and axe WCAG scans.
• Supports dark and light themes plus reduced-motion preferences.
• Remembers navigation and filters locally in the browser.
• Preserves the last loaded dashboard during brief disconnections and reports offline, reconnecting, and restored states.
• Includes copy actions for SKUs and Store links, clear filter reset states, compact Activity rows, image fallbacks, and a keyboard-accessible animated To top control.

Installation options

Standalone packages

Standalone downloads include their own Node.js runtime:

• Windows x64: GearBeacon-v1.0.0-windows-x64.zip
• macOS Apple Silicon: GearBeacon-v1.0.0-macos-arm64.tar.gz
• macOS Intel: GearBeacon-v1.0.0-macos-x64.tar.gz
• Linux ARM64: GearBeacon-v1.0.0-linux-arm64.tar.gz
• Linux x64: GearBeacon-v1.0.0-linux-x64.tar.gz

Each package can run directly or be installed for automatic startup using the included Windows service, macOS LaunchDaemon, or Linux systemd helper. Uninstallers preserve GearBeacon data unless their explicit data-removal option is used.

Docker Compose

docker compose up -d
docker compose logs gearbeacon

The published image is ghcr.io/alexphillips-dev/gearbeacon:1.0.0 and supports linux/amd64 and linux/arm64. Compose publishes only 127.0.0.1:8787 by default, runs GearBeacon as an unprivileged user, and keeps persistent data in the gearbeacon-data volume.

Source installation

The source archive and repository checkout require Node.js 22.13 or newer. Start with run-windows.bat on Windows or ./run-mac-linux.sh on macOS/Linux, then open http://localhost:8787.

Guided first run

The setup wizard walks through:

1. Creating the private owner password.
2. Selecting Store regions and an access mode.
3. Configuring optional notification channels.
4. Choosing backup interval and retention and testing Store/notification access.
5. Reviewing the final URL, security state, and any required restart.

Release integrity

This release was built from protected main commit c35322143fe66dcc7bd567de62c8345711d2eabe after exact-commit CI, security scanning, candidate packaging, and live regional catalog checks passed.

• Every standalone archive includes an adjacent SHA-256 checksum and SPDX JSON software bill of materials.
• Release archives were extracted and their applications started in automated smoke tests before publication.
• Downloadable artifacts include GitHub build provenance attestations.
• The multi-platform container was published with SBOM and provenance metadata.
• CodeQL and container vulnerability scanning completed successfully for the release commit.

Important notes

• GearBeacon is independent software and is not affiliated with or endorsed by Ubiquiti Inc. Ubiquiti and UniFi are trademarks of their respective owner.
• GearBeacon uses read-only Store catalog access. It does not sign in to a UniFi account, scrape account notifications, store Store credentials, or automate purchasing or checkout.
• Standalone packages in 1.0.0 are not code-signed, and the macOS packages are not notarized. Verify the adjacent SHA-256 checksum before installation and follow your operating system's procedure for locally trusted software.
• Update checks show available releases, but GearBeacon never silently downloads or installs an update. Update helpers require explicit owner action and validated-backup confirmation.
• GearBeacon is licensed under the Apache License 2.0.

For detailed deployment, reverse-proxy, backup, recovery, update, rollback, environment-variable, and API guidance, see the GearBeacon README.