Running Grafana

You run Grafana yourself. We publish an image with the Undercurrent data source and a starter dashboard already set up, so a single command gets you working dashboards.

Your events stay in Undercurrent’s storage. The container holds only your dashboards and Grafana’s own settings, and queries your events over HTTPS using your query token.

Requirements

Docker, and about 500 MB of disk. Any machine that runs Docker will do — your laptop, a server, or a container platform.

Starting it

docker run -d --name undercurrent \
  -p 3000:3000 \
  -v undercurrent-grafana:/var/lib/grafana \
  -e UNDERCURRENT_TOKEN=<your query token> \
  robmoore121/undercurrent-grafana:latest

Open localhost:3000 and sign in as admin / undercurrent.

Use a named volume, not a host directory. Grafana runs as user 472 inside the container. A bind-mounted host directory (-v /some/path:/var/lib/grafana) arrives owned by root, and Grafana then cannot create its database. The named-volume form above inherits the right ownership automatically. This is the most common first-run problem.

Configuration

Variable	Required	Default	Purpose
`UNDERCURRENT_TOKEN`	yes	—	Your query token, from your credentials file.
`GF_SECURITY_ADMIN_PASSWORD`	no	`undercurrent`	Admin password.
`R2SQL_API_BASE_URL`	no	the Undercurrent query endpoint	Only change this if we ask you to.
`GF_SERVER_ROOT_URL`	no	`http://localhost:3000/`	Set this if you put a reverse proxy in front.

Every other Grafana configuration option works too, through the usual GF_<SECTION>_<KEY> environment variables.

Change the admin password before exposing port 3000 beyond your own machine. The default is published in the image, so it is public knowledge.

Adding your team

Invite teammates from Administration → Users. They join the same organization and see the same dashboards, as Editors by default.

Upgrading

docker pull robmoore121/undercurrent-grafana:latest
docker rm -f undercurrent
docker run -d --name undercurrent ...    # the same command you started with

Your dashboards survive, because they live in the volume rather than the container.

Backing up

Your dashboards are the only thing here worth backing up — your events are already safe in Undercurrent’s storage.

The whole volume:

docker run --rm -v undercurrent-grafana:/data -v "$PWD:/backup" \
  alpine tar czf /backup/undercurrent-grafana-backup.tar.gz -C /data .

Or export individual dashboards as JSON and commit them to your app repo, which also gives you dashboards-as-code:

curl -su admin:undercurrent http://localhost:3000/api/search?type=dash-db
curl -su admin:undercurrent http://localhost:3000/api/dashboards/uid/<uid>

Troubleshooting

If panels show no data, check the data source first:

curl -su admin:undercurrent \
  http://localhost:3000/api/datasources/uid/undercurrent-r2sql/health

Message	What it means
`R2 SQL connection OK`	The data source works. If panels are still empty, your app may not be sending events yet.
`missing R2 SQL token`	`UNDERCURRENT_TOKEN` was not passed to the container.
`unknown or revoked token`	The token is wrong or has been revoked. Check it against your credentials file.

If Grafana won’t start at all, run docker logs undercurrent. The usual cause is a bind-mounted host directory instead of a named volume.