NanoPi2 Dashboard

Node 14-compatible dashboard server and admin UI for NanoPi2, designed to replace the current MagicMirror runtime while keeping display and server processes decoupled.

Implemented in this branch

• Server listens on 0.0.0.0:8090
• Health endpoints: /health/live, /health/ready
• Dashboard route: / with hybrid layout and rotating focus pane
• Admin auth flow: /login + protected /admin
• Admin APIs:
  • GET /api/admin/status
  • POST /api/admin/config
  • POST /api/admin/sync (sync, pull, push)
• State API: /api/state
• Fronius support:
  • realtime polling
  • archive DailySum totals
  • estimated fallback mode after 10 minutes without archive refresh
  • configurable polling cadence via fronius.realtimeRefreshSeconds and fronius.archiveRefreshSeconds
• Weather/news/bins integration:
  • default weather provider is OpenWeather (weather.provider = openweathermap)
  • weather requests are server-side only and rate-limited by weather.refreshSeconds
  • missing/invalid weather key falls back to non-crashing placeholder status
  • news headlines parsed from RSS feed
  • bins status from configured JSON endpoint
• Radar integration (RainViewer API based):
  • server polls RainViewer metadata API (radar.apiUrl)
  • startup recovery retries metadata fetch every few seconds (radar.startupRetrySeconds, radar.startupRetryMaxAttempts) before settling into normal radar.refreshSeconds cadence
  • browser only requests local endpoints /api/radar/meta and /api/radar/tile/...
  • browser also requests local OSM basemap endpoint /api/map/tile/...
  • radar is rendered with local map+radar tile compositing at configured lat/lon/zoom
  • smooth transitions controlled by radar.frameHoldMs and radar.transitionMs
  • refresh interval controlled by radar.refreshSeconds
  • map provider template configured in map.tileUrlTemplate
• BOM tiled radar provider:
  • set radar.provider to bom_tiles to use BOM Web Mercator radar tiles (radar.tileUrlTemplate)
  • server synthesizes recent 5-minute frame timestamps and renders them through the existing server GIF path
• Solar focus visuals:
  • canvas current-generation gauge
  • canvas daily ring summary
  • canvas history chart from server-side realtime history (solarHistory in /api/state)
• Git sync:
  • manual sync actions via admin API
  • background auto-sync scheduler from config (git.autoSyncEnabled, git.intervalSeconds)
• Systemd templates for server + Firefox kiosk split

Old OS TLS compatibility

If HTTPS certificate validation fails due to old CA/cipher support, set:

"insecureTLS": true

This allows server-side HTTPS fetches without certificate verification. Use only on trusted networks.

Debugging external calls and GIF rendering

Debugging is off by default. Enable with env vars:

LOG_LEVEL=debug
DEBUG_EXTERNAL=1
DEBUG_GIF=1
DEBUG_EXTERNAL_BODY_MODE=full
DEBUG_BODY_MAX_BYTES=65536

Supported body modes:

• metadata (status/timing only)
• metadata_response (adds response size and content-type)
• full (adds capped request/response bodies; binary is base64)

Debug events are buffered in memory and available after admin login:

• GET /api/admin/debug/events?limit=200
• POST /api/admin/debug/clear

Radar GIF backend

Server-side radar GIF rendering uses ffmpeg for tile compositing and GIF encoding.

If ffmpeg is unavailable, the server still starts normally and falls back to PNG radar mode (/api/radar/meta + /api/radar/tile/...) instead of crashing.

You can force a backend with config:

"radar": {
  "gifBackend": "auto"
}

Supported values: auto (default) and ffmpeg. sharp is intentionally not a production dependency because its native binaries can crash on older CPUs without SSE4.2.

To ensure GIF mode in runtime images, install ffmpeg in the runtime image:

apt-get install ffmpeg

Repository layout

• src/ server and runtime logic
• config/ runtime config files (auth.json is local-only)
• public/ static dashboard/admin pages
• deploy/systemd/ service templates and kiosk launcher
• docs/plans/ design and implementation plans

Development

npm test
cp config/auth.json.example config/auth.json
# set password hash/salt values in config/auth.json
npm start

Optional local secrets in .env.local:

cp .env.example .env.local
# set OPENWEATHER_APPID/OPENWEATHER_APP_ID, OPENWEATHER_LOCATION_ID, RADAR_SOURCE_URL, RADAR_LAT, RADAR_LON

OPENWEATHER_APPID (or OPENWEATHER_APP_ID), OPENWEATHER_LOCATION_ID, RADAR_SOURCE_URL, RADAR_LAT, RADAR_LON, and INSECURE_TLS from .env/.env.local override values from config/dashboard.json.

Set timeZone in config/dashboard.json (for example Australia/Brisbane) or DASHBOARD_TIMEZONE in env to keep daily solar bins/charts aligned on servers with different host timezones.

Open on LAN:

• Dashboard: http://192.168.0.27:8090/
• Admin: http://192.168.0.27:8090/admin

Bootstrap admin auth

./scripts/bootstrap-auth.sh '<strong-password>'

This writes config/auth.json with secure file mode 600.

NanoPi systemd install

sudo ./scripts/install-systemd.sh nanopi /opt/nanopi2-dashboard

This installer rewrites service templates with your service user/install path, enables both services, and restarts them.

Cutover checklist

Use:

docs/cutover/2026-02-14-cutover-checklist.md

VS Code remote workflow

Use VS Code Remote SSH from your laptop to 192.168.0.27 and open this repo directly. Keep dashboard server runtime on NanoPi so behavior matches production.