Download the PHP package drakelid/librenms-weather-risk-map-widget without Composer

Weather Risk Map

A LibreNMS dashboard widget that shows which network sites are about to be hit by bad weather.

It reads the GPS coordinates already stored on your LibreNMS devices, correlates them with forecasts and official severe-weather warnings, and reports an infrastructure risk level — not a weather report.

Contents

1. Quick start
2. Risk levels
3. How it works
4. Weather data sources
5. Installation
6. Configuration
7. The risk algorithm
8. Map and UI behaviour
9. Testing
10. Troubleshooting
11. Files created and modified
12. Known limitations
13. Future improvements
14. Verification status

1. Quick start

[!IMPORTANT] Run every command as the librenms user (sudo su - librenms first). LibreNMS refuses artisan as anyone else, and running it as root or your own account leaves cache files the web server cannot write — which surfaces later as an unrelated-looking 500.

There is usually no composer on PATH. Use LibreNMS's own wrapper: php scripts/composer_wrapper.php …

First get the package onto the server, beside the LibreNMS directory:

Then, as librenms, from /opt/librenms:

Add one required line to .env:

Then clear caches and verify:

Add it to a dashboard: Overview → edit (pencil) → Add Widget → Weather Risk Map.

[!IMPORTANT] The .env line is not optional. MET Norway answers 403 to any request whose User-Agent lacks a real contact email. weather-risk-map:diagnose fails loudly while the shipped placeholder is still in place.

[!CAUTION] A LibreNMS core update will uninstall this plugin. daily.sh runs git checkout -- composer.json composer.lock, which destroys the path repository above. See §5 before putting this into production — it is not optional operational trivia, the widget silently disappears.

Full details in §5 Installation.

[!TIP] Deploying to a live LibreNMS server? Follow docs/PRODUCTION-INSTALL.md instead — a step-by-step guide including backups, verification, the persistence guard and a rollback procedure.

2. Risk levels

[!NOTE] Marker fill is weather risk. LibreNMS operational status is drawn separately — a device that is down keeps its weather colour and gains a dark border. The two are never conflated.

3. How it works

The widget renders before its data

The dashboard requests each widget over AJAX and swaps in the returned HTML. If the widget controller waited on the weather APIs, a slow provider would visibly stall it.

So the widget controller performs no weather I/O at all. The shell paints immediately and fetches its payload separately.

Device count does not drive API traffic

Three collapses happen in sequence:

A 2,000-device Norwegian ISP across ~150 sites typically resolves to 30–60 forecast requests per 15 minutes, plus one warnings request per 5 minutes. Both are cached, so a NOC wall with eight browsers open generates the same traffic as one.

A hard max_cells_per_refresh ceiling bounds the worst case. Cells beyond it reuse cached data rather than being dropped.

The cache has two tiers

Every entry is written twice:

• fresh: — short TTL, the normal serving copy
• stale: — long TTL, the failure fallback

A single-tier cache loses its data exactly when the provider goes down and you need it most. On failure the widget serves the stale copy and labels it with its age. A failure marker additionally stops a dead provider being retried by every dashboard refresh from every logged-in operator.

4. Weather data sources

MET Norway — primary (met-norway)

Chosen because it is authoritative for Norway, it is the only candidate publishing official warning polygons with severity, and MetAlerts' single-request national coverage is what makes local polygon matching possible.

Terms-of-service compliance is implemented, not just intended:

• ✅ Identifying User-Agent with a contact email — MET returns 403 without one
• ✅ Coordinates truncated to 4 decimals — MET returns 403 with more
• ✅ Expires honoured — heldByExpires() refuses to re-request inside the window even when the local TTL is shorter
• ✅ If-Modified-Since sent with the exact previous Last-Modified; a 304 refreshes the TTL without re-downloading
• ✅ 20 req/s application-wide — geo-cell grouping keeps us orders of magnitude below it
• ✅ CC BY 4.0 attribution rendered in the widget footer

Open-Meteo — secondary (open-meteo)

Kept behind the same interface for two reasons:

• Its forecast endpoint accepts comma-separated coordinate lists, so all cells arrive in one request.
• It gives worldwide coverage for devices outside MET Norway's warning area.

It publishes no official warnings, so supportsWarnings() returns false and warnings keep coming from MET Norway.

Lightning — an honest limitation

[!WARNING] No free, reliable public API provides real-time lightning strike data.

Lightning is modelled as risk from thunder indications in the forecast — probability_of_thunder where available, otherwise the …andthunder symbol suffix. It is flagged inferred in the payload and rendered as "(risk, not detected strikes)" in the UI. Nothing is presented as a detected strike.

5. Installation

Leaflet and Leaflet.markercluster are already bundled with LibreNMS (html/js/leaflet.js, html/js/leaflet.markercluster.js), and the widget reuses core's init_map() / get_map() / destroy_map() helpers. There are no JavaScript dependencies and no asset build step.

Prerequisites that are easy to get wrong

Steps

Set the contact email — required, see §1:

Then: Overview → dashboard → edit (pencil) → Add Widget → Weather Risk Map.

Verify the route registered — this is the single best health check, because a missing route renders as core's generic "Problem with backend":

Surviving a LibreNMS core update

[!CAUTION] Installed this way, the plugin will be removed by the next nightly update.

daily.sh does the following, in order:

composer.json is tracked in LibreNMS's git, so the checkout destroys the path repository. LibreNMS then re-requires the plugin by name from composer.plugins.json — but composer_get_plugins in daily.php reads only the require block and ignores any repositories you add there. With no repository, the package cannot resolve and is dropped.

The same pass runs --update-no-dev, which strips LibreNMS's dev dependencies. That removes PHPUnit and breaks the flare log driver in the default logging stack, so subsequent errors are not written to laravel.log at all — which makes the failure considerably harder to diagnose than it should be.

Three ways to handle it:

1. Publish the package (the real fix). If drakelid/librenms-weather-risk-map-widget resolves from Packagist, daily.sh's composer require works untouched and no repository entry is needed anywhere. A path repository is a development arrangement; this is what LibreNMS's plugin system expects.

2. Re-apply automatically. Idempotent, so it is safe hourly regardless of when daily.sh runs:

3. Disable automatic updates — arguably correct for a NOC system anyway:

[!NOTE] Defining the repository in Composer's global config does not work. Composer documents only disabling a repository globally; there is no supported way to define one that applies to another project. This was tested and failed.

Notes

• If your installation caches config or routes, re-run php artisan config:cache / route:cache after clearing.

• No service restart is needed beyond the cache clears — unless you run OPcache with validate_timestamps=0, in which case reload PHP-FPM:

• After a git pull in the package directory, run php artisan view:clear (or optimize:clear) and hard-refresh the browser. The widget's CSS and JavaScript are inlined into the Blade output, so a cached page keeps running the old script.

Optional: pre-warm the cache

Worth it only for a permanently displayed NOC dashboard. Deliberately not scheduled by default, so an installation that never opens the widget generates no API traffic:

6. Configuration

Widget settings

Per widget, per user — edited in the widget's own settings panel.

[!NOTE] On the refresh field. The spec suggested a 5/10/15/30/60-minute dropdown. The panel instead inherits LibreNMS's own numeric refresh input from widgets.settings.base, because that is the convention every other widget follows and what core's save path validates. The default is 600 s (10 min) as specified; any value is accepted.

Installation config

config/weather-risk-map.php — provider selection, User-Agent, language, cache TTLs, HTTP timeout, request budget, default thresholds and sensitivity profiles. Every value is overridable by environment variable.

Infrastructure sensitivity

Shifts individual hazards up or down for devices in a given LibreNMS device group. Ships empty, so nothing changes until you opt in.

Profiles reference device groups by numeric id, never by name:

Find your group ids with:

Offsets shift the hazard on the 0–5 scale and are clamped at both ends. When a device belongs to several profiled groups the largest offset wins — erring toward showing more risk, never less.

7. The risk algorithm

Fully documented in the class docblock of src/Services/WeatherRiskService.php. In summary:

1 — Calculated risk. Every forecast hour in the window is scored against configurable thresholds per hazard. The result is the worst hour and the time it occurs. Wind scores sustained speed and gusts on separate scales, because a 25 m/s gust in a 12 m/s wind is a different engineering problem from steady 25 m/s.

2 — Official warning risk. Warnings whose polygon contains the device, and whose validity overlaps the window, contribute their published severity: yellow → Moderate, orange → High, red → Severe.

3 — Combination.

Official warnings raise but never lower a calculated risk — a genuinely dangerous local value is not suppressed just because no warning was issued. When calculated risk wins, the assessment is still flagged official so the operator sees a warning exists.

4 — Sensitivity. Device-group offsets applied.

5 — Escalation. Two or more hazards at Severe promote the device to Extreme 🟣. Compound events are what actually take sites off the air.

Default thresholds

All overridable per widget.

Icing is derived from the physical precondition — precipitation while air temperature sits in the −6 °C … +1 °C band — and is flagged inferred.

8. Map and UI behaviour

• Marker colour = weather risk. LibreNMS down state is a dark double border; disabled devices are dimmed. Never conflated.
• Clusters take the colour of their worst member, so one red site among 26 green ones stays visible when zoomed out.
• Warning polygons use 16 % fill opacity and sit behind the markers, so devices stay readable underneath.
• Warning popups show type, severity, official title, description, consequences, recommendations, start/end, source and fetch time — each rendered only if the source actually published it. Nothing is fabricated.
• Automatic positioning fits the bounds of the visible devices; a single device gets zoom 11. No country or city is hard-coded.
• Summary counters are clickable severity filters; hazard chips toggle hazards client-side.
• Table rows are clickable and centre/zoom the map on that device, expanding its cluster first.
• Dark mode. Leaflet ships hard-coded light chrome, so popups, tips, bars, layer control and attribution are each re-declared for the dark theme, and tiles get a slight brightness reduction so markers stay legible.

9. Testing

Automated

The package keeps its own vendor/, so the suite is unaffected when a LibreNMS update strips core's dev dependencies:

Expected: OK (110 tests, 264 assertions).

The suite is pure — no database, no Laravel application, no network — so it runs anywhere PHP 8.2+ is available. vendor/bin/pint --test checks style.

[!NOTE] composer is usually not on PATH on a LibreNMS host, and scripts/composer_wrapper.php always chdirs to /opt/librenms, so it cannot be used for this package. Invoke composer.phar directly as above.

Static and syntax checks

Run on the LibreNMS host, where PHP is available:

Manual NOC checks

10. Troubleshooting

Logs go to storage/logs/weather-risk-map.log — a separate channel, so weather noise stays out of the main LibreNMS log.

Raise verbosity temporarily with WEATHER_RISK_MAP_LOG_LEVEL=debug. Normal operation logs only aggregate lines — e.g. one "skipped N devices for unusable coordinates" per refresh — never one line per device.

11. Files created and modified

Modified: none

LibreNMS builds its widget catalogue in DashboardController::listWidgets() by scanning the route table for routes prefixed exactly ajax/dash — the widgets database table was dropped in 2022. Registering a route with that prefix from this package's own service provider is therefore enough to make Weather Risk Map appear in the Add Widget menu.

No core controller, view, route file, language file or migration is touched, so a LibreNMS upgrade cannot overwrite the feature.

Two details make it behave like a built-in widget rather than a bolted-on approximation:

• View naming. The package view directory is registered with View::addLocation() as well as a namespace, so views resolve as widgets.weather-risk-map and widgets.settings.weather-risk-map. Core decides whether a widget is in settings mode with Str::startsWith($view->getName(), 'widgets.settings.'); a namespaced name fails that test and the settings panel would silently drop out of edit mode on the next auto-refresh, discarding unsaved edits. Core's own view paths are registered first, so this cannot shadow a LibreNMS view.
• data-reload="false" on the widget's outer element makes core's refresh timer dispatch a refresh event instead of re-fetching and re-injecting HTML. The Leaflet map is built once and updated in place, not destroyed and recreated every cycle.

Database changes: none

No migrations, no new tables, no new columns. Widget settings use LibreNMS's existing per-user users_widgets.settings JSON column; coordinates are read from the existing locations table. This package stores no device coordinates of its own.

Created

12. Known limitations

1. Lightning is risk, not strikes. No free public API provides real-time strike data. Labelled as such everywhere it appears.
2. Official warnings are Norway-only. MetAlerts covers Norway and its waters. Devices elsewhere still get forecast-based calculated risk — MET's forecast model is global. There is no equivalent single-request pan-European warning feed with polygons.
3. Icing and snow are inferred from temperature, precipitation and symbol codes rather than a dedicated icing product. Flagged inferred.
4. Snow amounts are water-equivalent millimetres, not snow depth — that is what the providers publish.
5. No antimeridian handling in point-in-polygon. MET Norway issues no warnings crossing 180°; the failure mode would be a missed match, never a false one.
6. Warning polygons are simplified to ~0.01° for transmission. Device matching always uses full-resolution geometry server-side; only the drawn outline is thinned.
7. The per-refresh cell budget means a pathological inventory (thousands of distinct sites at 1 km radius) will show some devices from cached rather than current data. The footer reports cell count, so this is visible.
8. Sensitivity is a flat offset table, not a rules engine — by design for v1. SensitivityProfileService::adjust() is the seam where a richer engine slots in.
9. Cluster "worst member" derives from zIndexOffset. Compact, but it couples two concerns; a dedicated marker option would be cleaner if the marker code grows.
10. A LibreNMS core update uninstalls the plugin unless mitigated — daily.sh reverts composer.json, destroying the path repository. See §5. Publishing to a Composer repository is the only fix that needs no ongoing maintenance.

13. Future improvements

The architecture was chosen so none of these require a rewrite:

14. Verification status

The unit suite has been run on the target host and passes:

The widget is confirmed rendering in a live LibreNMS dashboard.

What was authored without a local runtime, and is therefore covered only by the run above plus manual checking:

• The package was written on a machine with no PHP, Composer, Docker or WSL, so nothing was executed during development.
• Every core API it depends on was read directly from the LibreNMS checkout rather than assumed — DashboardController::listWidgets(), WidgetController, the Device / Location / DeviceGroup models, scopeInDeviceGroup, scopeHasAccess, init_map(), widget_settings(), and daily.sh's update sequence.
• The MET Norway contracts were verified against the live API documentation, not recalled from memory.

Still not exercised: §9's manual NOC checks — provider failure and cached fallback, timeout, rate limiting, and the light/dark and clustering passes. Run those before relying on the widget operationally.

Attribution

Weather data from MET Norway and Open-Meteo, both licensed CC BY 4.0. Attribution is rendered in the widget footer at runtime, as their licences require.