signalk-grafana

signalk-grafana

Managed Grafana with auto-provisioned QuestDB and Signal K datasources for Signal K.

Runs Grafana in a container (via signalk-container), automatically connects it to signalk-questdb via a shared container network, and provisions both datasources.

Features

• Zero-config Grafana -- container managed automatically, no manual setup
• Auto-provisioned datasources -- QuestDB (PostgreSQL) and Signal K datasources configured automatically
• Shared container network -- Grafana and QuestDB communicate on a private Podman/Docker network
• Table auto-discovery -- QuestDB supports information_schema, Grafana query builder works
• Anonymous access -- view dashboards without login (configurable)
• Live reachability -- config panel shows whether Grafana can actually reach your Signal K server
• One-click update -- check for new Grafana versions and update from the config panel
• Password management -- set admin password from Signal K config panel
• Config panel -- Grafana status with direct link, settings, all in Admin UI
• Backup & restore integration -- exposes /api/full-export/{db,dashboards,provisioning} endpoints for signalk-backup to pull a consistent SQLite checkpoint plus dashboard JSONs and provisioning YAMLs. On plugin start, if a kopia restore left a staged grafana.db on disk but the live one is missing, it's automatically copied into place before Grafana starts -- dashboards and datasources come back without any manual step.

How It Works

1. Plugin creates a Podman/Docker network (sk-network)
2. Starts Grafana container on the network
3. Auto-provisions QuestDB datasource (connects via container DNS sk-signalk-questdb:8812)
4. Auto-provisions Signal K datasource (connects via host.containers.internal)
5. Sets admin password on every startup to match config

QuestDB must also be on sk-network -- set Container network to sk-network in the QuestDB plugin config.

Example Queries

Create dashboards in Grafana using the QuestDB datasource with raw SQL. QuestDB uses SAMPLE BY for time bucketing:

Speed Over Ground (knots):

SELECT ts AS "time", avg(value) * 1.94384 AS "SOG"
FROM signalk
WHERE path = 'navigation.speedOverGround'
  AND context = 'self'
  AND ts >= $__timeFrom() AND ts <= $__timeTo()
SAMPLE BY 10s

Wind Speed and Angle:

SELECT ts AS "time",
  avg(value) * 1.94384 AS "AWS"
FROM signalk
WHERE path = 'environment.wind.speedApparent'
  AND context = 'self'
  AND ts >= $__timeFrom() AND ts <= $__timeTo()
SAMPLE BY 10s

Battery Voltage:

SELECT ts AS "time", avg(value) AS "Voltage"
FROM signalk
WHERE path LIKE 'electrical.batteries.%.voltage'
  AND context = 'self'
  AND ts >= $__timeFrom() AND ts <= $__timeTo()
SAMPLE BY 10s

Engine RPM (rev/s to RPM):

SELECT ts AS "time", avg(value) * 60 AS "RPM"
FROM signalk
WHERE path LIKE 'propulsion.%.revolutions'
  AND context = 'self'
  AND ts >= $__timeFrom() AND ts <= $__timeTo()
SAMPLE BY 10s

Temperature (Kelvin to Celsius):

SELECT ts AS "time", avg(value) - 273.15 AS "Temp"
FROM signalk
WHERE path = 'environment.water.temperature'
  AND context = 'self'
  AND ts >= $__timeFrom() AND ts <= $__timeTo()
SAMPLE BY 10s

Unit Conversions

Signal K stores values in SI units. Common conversions for Grafana:

Conversion	Formula
m/s to knots	value * 1.94384
radians to degrees	value * 57.2958
Kelvin to Celsius	value - 273.15
Pascals to hPa	value / 100
rev/s to RPM	value * 60
Pascals to PSI	value * 0.000145038

Grafana Macros

Use these Grafana PostgreSQL macros in your queries:

Macro	Expands to
$__timeFrom()	Start of selected time range
$__timeTo()	End of selected time range

QuestDB's SAMPLE BY handles time bucketing (e.g., SAMPLE BY 10s, SAMPLE BY 1m, SAMPLE BY 1h).

Configuration

Setting	Default	Description
Grafana port	3001	Host port for Grafana UI
Image version	latest	Grafana Docker image tag
Admin password	admin	Grafana admin password (applied on every start)
Anonymous access	true	Allow viewing without login
Signal K URL override	auto	Auto-detected; set to override (use http:// or https://)
QuestDB container	signalk-questdb	Container name (without sk- prefix)
PostgreSQL port	8812	QuestDB PG wire port
Network name	sk-network	Shared container network name
Bind to 0.0.0.0	false	Expose Grafana outside localhost
Sub-path	empty	Set to /grafana/ when running behind a reverse proxy
Auto-request token	true	On secured Signal K servers, request a device-access token

Secured Signal K servers

When Signal K security is enabled, the plugin drives the standard SK device-access-request flow on startup so the Grafana Signal K datasource can read paths and history from the secured server.

1. Plugin POSTs /signalk/v1/access/requests with clientId: signalk-grafana, permissions: readwrite.
2. Plugin status shows Awaiting Signal K token approval — see Security → Access Requests.
3. Approve in Signal K Admin → Security → Access Requests.
4. The plugin caches the JWT to ${dataDir}/signalk-token (mode 0600), injects it into the Grafana datasource provisioning, and recreates the Grafana container so the new credentials take effect.

Disable with requestSignalkToken: false if you prefer to paste a token into the Grafana datasource UI manually.

What works and what doesn't on secured SK

Use case	Works on secured SK?
Explore → Signal K → pick a path
Historical range queries (from/to are explicit times, or now-1h to now-1m)
/api/health and datasource Test button
Live-updating panels (range now-X to now that streams values in real time)

The live-update gap is in the upstream tkurki-signalk-datasource plugin: it opens its WebSocket from the browser where Grafana's secret store is not accessible by design, so the upgrade request goes out without an Authorization header and Signal K rejects it. HTTP queries are unaffected because Grafana's datasource proxy injects the bearer token server-side for those. Tracked at tkurki/signalk-grafana-datasource#12 — until that lands, use the QuestDB datasource for live-updating panels (the intended architecture: SK → questdb → Grafana, with the SK datasource reserved for ad-hoc Explore and historical queries).

Requirements

• Node.js >= 22.16 (needs node:sqlite backup() for the SQLite checkpoint endpoint)
• signalk-container plugin
• signalk-questdb plugin (with network set to sk-network)
• Signal K server

License

MIT