How to Set Up Grafana

This guide will walk you through setting up Grafana to run locally on your PC. Included are examples for using the MachineMetrics GraphQL API to gather data and visualize it with panels in Grafana.

Before Getting Started

This guide assumes you have some experience with Docker. The guide attempts to include as many examples in a copy-paste form as possible, but Docker is a development tool that may require additional reading and training to operate confidently.

For Windows users, you must use the Windows Subsystem for Linux and configure your Docker environment accordingly.

Acquire an API Key

The MachineMetrics GraphQL API is read-only. To interact with the API, you must have credentials. Go to https://app.machinemetrics.com/settings/api-keys and create a new API Key with the reporting scope. Name it appropriately and when you copy the key, put it somewhere safe. For security reasons, we do not save the API Keys in a retrievable form in our database. You will only be shown it one time. If you lose the key, you will need to create a new one.

Remember, API Keys are like passwords and should be protected at all times.

Create a Workspace

We will be creating a few files to get started. A good first step is to create a folder where we can do our work. Name it something memorable, like mm-grafana.

In this folder, we will be creating the following:

Dockerfile
Setup Scripts
Configuration Files
Example Dashboard Template

Preparing the Files

This section walks through what each file does and instructs you to create each file manually. For a quicker setup, skip ahead to the Download section.

Docker is a virtualization system that allows for you to create sandboxed services that operate in a very predicable way. That predictability comes from the setup process. At the most basic level, a Dockerfile is a set of rules that are followed to create an image that, when run, creates a service (a Docker container) that does a targeted task. The Docker container we intend to run will host an instance of Grafana that you can access in your browser at http://localhost:3000.

Each section below shows the contents of all the files that need to be created. Note the name of the file at the top of each code block. Copy each code block and paste the content into a file by that name in the folder you created. The names below assume the folder you created is called mm-grafana.

mm-grafana/Dockerfile
FROM grafana/grafana

ENV GF_INSTALL_PLUGINS="fifemon-graphql-datasource 1.3.0,natel-discrete-panel 0.1.1,ae3e-plotly-panel 0.5.0"
ENV GF_SERVER_DOMAIN=\${SERVER_DOMAIN}

COPY ./datasources.yaml /etc/grafana/provisioning/datasources/mm-graphql.yaml
COPY ./machine_view_dashboard.json /machine_view_dashboard.json

USER root
RUN apk --no-cache add curl
RUN apk --no-cache add jq

COPY ./mm-setup.sh /mm-setup.sh
COPY ./mm-grafana.sh /mm-grafana.sh

ENTRYPOINT ["/mm-grafana.sh"]

This Dockerfile is an extension of the official grafana/grafana Docker image. The extension we're creating is going to set it up to work with MachineMetrics.

#!/bin/bash

sh /mm-setup.sh & /run.sh

The ENTRYPOINT of the Dockerfile calls this small shell script to kick things off. The base grafana/grafana image calls run.sh by default. Our new entrypoint, allows for our extension to do some work before that in mm-setup.sh which we'll get to next.

You must update the permissions on this file to be executable. In a terminal, run the following command:

chmod u+x mm-grafana.sh

#!/bin/bash

while [[ "$(curl -s -o /dev/null -w ''%{http_code}'' localhost:3000/api/health)" != "200" ]]; do sleep 5; done

json=$(cat /machine_view_dashboard.json | jq .)
echo $json

url="http://localhost:3000"

curl -u admin:admin -X POST -H "Content-Type: application/json" -d "{\"dashboard\": ${json}}" "${url}/api/dashboards/import"

This script waits until the Grafana server is up and running, reads in a JSON file containing all of our examples (we'll get to that soon), and imports that into Grafana.

apiVersion: 1

datasources:
  - name: graphql
    type: fifemon-graphql-datasource
    isDefault: false
    readOnly: false
    editable: true
    url: https://api.machinemetrics.com/graphql
    access: proxy
    jsonData:
      httpHeaderName1: Authorization
    secureJsonData:
      httpHeaderValue1: Bearer $API_KEY

This YAML file prepares the GraphQL datasource to send requests to our GraphQL endpoint and include the API_KEY that you will provide when initializing the Grafana container.

{
  "annotations": {
    "list": [
      {
        "builtIn": 1,
        "datasource": "-- Grafana --",
        "enable": true,
        "hide": true,
        "iconColor": "rgba(0, 211, 255, 1)",
        "name": "Annotations & Alerts",
        "type": "dashboard"
      }
    ]
  },
  "editable": true,

  ...

Above is a snippet of the first few lines of a Grafana template that contains a series of dashboards you can use to get started. Download the entire contents of that template here. You'll want to make sure the file name is machine_view_dashboard.json and is saved right alongside the rest of the files you've been creating in your working folder.

Download

Download this zip of the above files, unpack it and move on to the next step.

Building Your Docker Image

Once you have all the files prepared, we can run a few commands to get things packaged up. Using a terminal, navigate to your working directory and run the following:

docker build -t mm-grafana .

This will build your image and add it to your local docker runtime -- ready to be run!

Launching Grafana

Next, we need to launch a docker container based on the image we built using the run command. In the following command, replace YOUR_API_KEY with the one you created earlier.

docker run --env API_KEY=YOUR_API_KEY -dp 3000:3000 --name grafana mm-grafana

Trying it Out

After a few moments, your Grafana instance will be running happily in the background. In your browser, navigate to http://localhost:3000. You will be prompted to log in.

Default Username: admin
Default Password: admin

You will be required to change your password on the first login.

Once you're in, you will be able to navigate to the dashboards by going to http://localhost:3000/dashboards and choosing the Examples from the Browse list.

It's important to note that this application should only be made accessible from your local PC for testing purposes. Additional work is required to harden a Grafana deployment that is not detailed in this guide.

Troubleshooting and Tips

If your run command fails and you recognize that you missed a step (maybe the permissions on the mm-grafana.sh file need to be updated), you may need to rebuild your image. To do so, use the following procedure.

docker stop grafana
docker rm grafana
docker build -t mm-grafana .
docker run --env API_KEY=YOUR_API_KEY -dp 3000:3000 --name grafana mm-grafana

If you want to stop and start the Grafana container, you can do so with the following commands.

docker stop grafana

docker start grafana

Before Getting Started​

Acquire an API Key​

Create a Workspace​

Preparing the Files​

Download​

Building Your Docker Image​

Launching Grafana​

Trying it Out​

Troubleshooting and Tips​