In this chapter, you will learn what is Grafana and why it is an excellent option for building IoT solutions. Throughout this chapter, you will learn to install Grafana in different scenarios.

Also, you will be able to perform a basic configuration and make it run at boot.

Finally, we will explore the Grafana Cloud service, which you can use instead of installing and maintaining a Grafana instance.

In this chapter, we’re going to cover the following main topics:

• Installing Grafana on a Raspberry Pi
• Installing Grafana on Ubuntu Server
• Installing Grafana with Docker
• Initial configuration of Grafana
• Maybe you prefer the cloud option

Let’s explore some of these functionalities.

Depending on the type of implementation that you want to use, you will need some of the following requirements:

• A Raspberry Pi: version 2, 3, or 4 will work. However, depending on the size of your solution, you will have to size your hardware according to it.
• If you prefer to use an Ubuntu Server or a Docker implementation, then you will need a virtual machine, either local or in the cloud. The resources of the virtual machine will have to adapt to your system needs.

Managing data

Grafana allows to capture and manage data from many different sources, such as relational databases, time-series databases, NoSQL databases, Excel or CSV files, logs, and many others.

In this way, Grafana can be connected to different data sources, isolating the visualization and analytics app from the databases. All databases are independent and can be managed by the corresponding applications.

So, even if the database is managed by another department, read-only access can be granted to Grafana to perform analytics on that data.

With the release of Grafana 8.x, it is possible to feed live events into Grafana using MQTT, HTTP, or other streaming data sources. This is a great new feature for IoT systems.

Performing visualizations

Grafana allows you to build a broad range of dashboards, from the typical time-series plot to advanced visualizations.

The dashboards are made up of panels, which provide different types of visualizations.

Some of the possible visualization panels are as follows:

• Time-series plots
• Statistical graphs
• Categorical or boolean panels
• Text and logs
• Topological views
• Geographical or georeferenced data

Every dashboard can be easily modified through drag and drop and resize operations.

Dashboards can be shared with specific users or teams, allowing the data to be used in a cooperative way. Also, dashboards can be published on a website to make information available to the public.

Transformations, alerts, and annotations

With Grafana, you can perform transformations directly on the visualization panels. For instance, you can summarize, combine, rename, and make calculations just with a few clicks.

With Grafana, you can create, modify, and silence all the alert conditions in a centralized way. This functionality simplifies the management of alerts.

Finally, with annotations, you can make comments on data directly on the visualization panels. You can include descriptions and tags for every event of interest.

Now that you have learned about the capabilities of Grafana and the reasons that lead to its use in IoT systems, in the following sections, you will learn how to install Grafana on Raspberry Pi, Ubuntu Server, and Docker.

The Single Board Computer (SBC) Raspberry Pi has been widely adopted for many uses, including IoT. So, it is quite natural to try to use Grafana on it.

In this section, we will see how to install and configure Grafana on a Raspberry Pi. To achieve good performance, we will use a Raspberry Pi version 2 or later.

Installation instructions

All the following instructions assume that you are using Raspberry Pi OS as the operating system.

Let’s start:

1. First, it is always recommended to start with an update.

So, we run the following:

$ sudo apt-get update
$ sudo apt-get upgrade

2. After that, we need to download the binary files for the installation:

   $ wget https://dl.grafana.com/oss/release/grafana-rpi_8.0.6_armhf.deb
   $ sudo dpkg -i grafana-rpi_8.0.6_armhf.deb

   Note about Versions

   Change the package version to the most recent stable version available. You can find all the available options at https://grafana.com/grafana/download?edition=oss.

3. The next step is to make Grafana start at boot. To do this, we can use the systemd service file, included in Grafana packages.

So, we enable it by running the following:

 $ sudo systemctl enable grafana-server

And that’s it. Grafana will start at every boot.

4. Now, to start Grafana manually, we can use the following:

   $ sudo systemctl start grafana-server

Now that you know how to install Grafana on a Raspberry Pi, let’s dive into how you can access Grafana for the first time.

Accessing Grafana for the first time

Now that you have Grafana running in your Raspberry Pi, you can access it through any web browser, pointing it to http://your-raspberry-ip-address:3000.

You can use your Raspberry Pi IP address, as well as its DNS name. Or, if you are accessing Grafana from the Raspberry Pi itself, you can use localhost or 127.0.0.1 in the URL.

After you access the web interface, you will have to enter the username and password to enter the platform.

The default credentials are user = admin and password = admin.

Figure 1.1 – Grafana login page

In this section, you have learned to install Grafana on a Raspberry Pi. In the next section, you will see how to do it on Ubuntu Server.

Ubuntu is one of the most popular operating systems for servers, so we will learn how to install Grafana on it.

Installing Grafana on Ubuntu is a very straightforward procedure because there are Ubuntu packages.

Installation instructions

Let’s look at what we need to do here:

1. As before, we first run updates:

   $ sudo apt-get update 
   $ sudo apt-get upgrade

2. Next, if you do not have wget installed on your server, you can install it as follows:

   $ sudo apt-get install apt-transport-https
   $ sudo apt-get install software-properties-common wget

3. Then you can use wget to download the GPG key and add it to the APT keys. In this way, you authorize Grafana packages to be installed on the system:

   $ wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add –

4. After that, you can add the Grafana repository (stable release) to the APT source list:

   $ echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list

5. Finally, run the following commands:

   $ sudo apt-get update
   $ sudo apt-get install grafana

Now that you have installed Grafana on Ubuntu Server, let’s see how to run it.

Running Grafana on Ubuntu Server

There are two ways of running Grafana as a service. Let’s have a look at them.

Running Grafana using systemd

Grafana services can be managed by systemd.

To start Grafana, simply execute the following:

$ sudo systemctl start grafana-server

To see the Grafana service status, run this command:

$ sudo systemctl status grafana-server

To stop the service, use this command:

$ sudo systemctl stop grafana-server

And to enable start at boot, use this command:

$ sudo systemctl enable grafana-server.service

Now that you know how to do it with systemd, let’s see how to do it with initd.

Running Grafana with initd

You can run Grafana as follows:

$ sudo service grafana-server start

To stop Grafana, use this command:

$ sudo service grafana-server stop

To get the service status, run this command:

$ sudo service grafana-server status

To configure it to start at boot, use the following command:

$ sudo update-rc.d grafana-server defaults

You have now installed and executed Grafana on Ubuntu Server. You also configured it to start on boot. Now let’s see how to access Grafana from a browser.

Accessing Grafana

Before trying to access Grafana, make sure that the service is running. You can check it using the preceding commands. If it is stopped, you must start it as shown earlier.

As soon as you have Grafana installed and running, you can access it by pointing the browser to http://your-server-ip-or-name:3000.

The default credentials are admin/admin.

Now that you have learned how to install and run Grafana on Ubuntu Server as well as how to manage start-up at boot using two different methods, let’s move on to the next section, where you will learn how to deploy Grafana using Docker.

Docker is a great option to deploy Grafana quickly and easily.

With Docker, you can manage multiple applications on the same server, avoiding conflicts between them. Each application can depend on different versions of libraries and software packages, but their files are completely isolated from each other.

Docker also allows us to start, stop, remove, and update applications in a few seconds. In a more advanced implementation, you can create a cluster with multiple hosts and containers. This cluster can be managed by Swarm or Kubernetes. However, this is beyond the scope of this book.

In this section, you will learn how to deploy Grafana using Docker.

You will be able to use two different methods: the Docker CLI and Docker Compose.

Deploying Grafana with Docker CLI

There are many ways to deploy Grafana with Docker.

One of these options is the operating system selection of the container. You can choose between Alpine and Ubuntu.

The most recent version of Grafana uses Alpine by default, which is a very light operating system based on musl libc and BusyBox. This is the option recommended by GrafanaLabs.

Important note

Please, do not run Docker on Windows. Docker is designed to run in a Linux host. If you run Docker on Windows, it will create a virtual machine running Linux (you need Windows Professional and Hyper V installed). It is more natural and easier to run Docker directly in a Linux host. So, I recommend you do this.

Now, let’s see how to deploy Grafana with Docker.

Running Grafana with Docker

To run Grafana from Docker with the default options, simply execute the following:

$ sudo docker run -d -p 3000:3000 grafana/grafana

The command options are as follows:

• -d: Detached mode, which means to execute the container in the background.
• -p 3000:3000: Container port and published port are set to 3000. You can change it at your convenience.

The grafana/grafana image comes with the Alpine operating system and the latest stable version of Grafana.

The deployment of Grafana can be modified through options and environment variables. Let’s see some examples:

$ sudo docker run -d \
  -p 3000:3000 \
  --name=grafana \
  -e "GF_INSTALL_PLUGINS= grafana-piechart-panel, agenty-flowcharting-panel " \
  grafana/grafana

The name option is used to give a specific name to the container and e to open the environment section.

In this particular example, the grafana-piechart-panel and agenty-flowcharting-panel plugins are installed when the container is created.

Using persisting storage

Every time a container is created, new files are generated by being copied from the image file, which contains all the necessary code, libraries, and dependencies to run the application.

In the same way, each time a container is deleted, all these files are removed and lost. So, if you want to have persistent data, such as configuration or data files, you will have to attach some storage located in the host (outside of the container).

There are two ways of doing this:

• Using bind mounts
• Using Docker volumes

Let’s explore these options.

Bind mounts

With bind mounts, you can mount a host directory in the container. This is typically used with configuration files, although it can be used either with databases or other data.

In this way, you keep a configuration file in the host (outside the container) that persists even if the container is deleted. Then, to create a new container with the previous configuration, you only have to bind the corresponding directory or file.

Let’s see how to do it with the command line:

 $ sudo docker run -d --name grafana -v "$PWD/config/grafana.ini:/etc/grafana/grafana.ini" -p 3000:3000 grafana/grafana

In this example, the config directory is mounted in the container and the grafana.ini file is accessible from the container. If you want to modify the configuration of Grafana, you can simply edit the grafana.ini file in the host and run the container again.

Important Note

$PWD/config/grafana.ini is where you have the ini file. It can be anywhere as long the directory has the appropriate read permissions.

Moreover, editing a file in the host is easier than editing it in the container.

Volumes

If you need to keep data stored even if you delete a container, you will have to use volumes. This will allow you to have persistent data into a host directory that can be read and write from the container.

Bind mounts are dependent on the directory structure and operating system of the host. In contrast, volumes are fully managed by Docker.

Volumes have some advantages with respect to bind mounts:

• They are easier to move or back up.
• You can manage them with the Docker CLI.
• They can be shared safely among containers.
• They can be created in remote hosts and accessed from any container.

Let’s see how to use Docker volumes:

$sudo docker run -d --name grafana -v grafanavol:/var/lib/grafana -p 3000:3000 grafana/grafana

In this command, we are creating a volume named grafanavol and mapping it to the directory /var/lib/grafana. This directory corresponds to Grafana data files.

You will learn about Grafana configuration and files in the next section.

By combining bind mounts and volumes, you can have the best of both worlds, as shown in the next command:

$ sudo docker run -d -v "$PWD/config/grafana.ini:/etc/grafana/grafana.ini" -v grafanavol:/var/lib/grafana -p 3000:3000 grafana/grafana

In this case, we can configure Grafana by modifying the grafana.ini file in the host while storing persistent data in the grafanavol volume.

Using environmental variables

You can customize the building process of the container with environmental variables.

You can find the complete list of environmental variables here: https://grafana.com/docs/grafana/latest/administration/configuration/#configure-with-environment-variables.

The environmental variables allow you to specify all the parameters included in the configuration file. In fact, you can use the environment variable instead of editing the configuration file.

Any environment variable specified when launching the container will override the corresponding configuration in the configuration file.

Let´s see how you can use environment variables.

Suppose you want to set admin user and password. You can specify the following environment variables:

• GF_SECURITY_ADMIN_USER=youradminuser
• GF_SECURITY_ADMIN_PASSWORD=youradminpassword

Let’s see how to include them in a docker command.

$ sudo docker run -d \
-p 3000:3000 \
--name=grafana \
-e "GF_SECURITY_ADMIN_USER=youradminuser" \
-e "GF_SECURITY_ADMIN_PASSWORD=youradminpassword" \
grafana/grafana

You have seen how to use environment variables with the Docker CLI. Now you will learn how to use Docker Compose.

Using Docker Compose

Docker Compose is a very useful tool for managing and running Docker containers. It uses a YAML file to configure all the services of the applications. With Docker Compose, you can launch all the applications and services that you need in a single command.

Important Note

Docker Compose is not installed by default, so you may need to do it. To install it, follow the instructions at https://docs.docker.com/compose/install/.

Besides practicality, using a YAML file allows you to have a clear picture of your deployment. When using the Docker CLI, things can get messy if you need to pass a lot of parameters and environment variables. In these cases, Docker Compose offers a structured and clean solution.

Also, if you need to deploy more than one application or container, you can use Docker Compose to do it in a single command. With the Docker CLI, you would have to run it for every application/container.

Let’s see an example of YAML file. Take into consideration that you have to name the file docker-compose.yml:

version: '2'

services:

    grafana:

        image: grafana/grafana:latest

        container_name: grafana

        ports:

          - 3000:3000

        environment:

          - GF_SECURITY_ADMIN_USER=youradminuser

          - GF_SECURITY_ADMIN_PASSWORD=youradminpassword

        volumes:

          - grafanavol:/var/lib/grafana

volumes:

    grafanavol:

Building and running the container is as easy as executing this:

$sudo docker-compose up

You must run the command from the same directory where the docker-compose.yaml file is.

Further considerations

When installing Grafana with Docker, you will have to consider a variety of factors, such as security, networking, and storage.

All these factors will affect the installation and configuration needs.

In this section, you have all the information you need to start using Grafana with Docker. However, more complex use of Docker is far beyond the scope of this book.

Now, let’s look at the initial configuration of Grafana.

You can configure Grafana whether editing the grafana.ini file or by specifying environment variables.

In this section, you will learn how to do it both ways.

Configuration files

Grafana comes with a default configuration file that you should not edit: defaults.ini.

To override the settings in this file, you must edit grafana.ini. This file is located – in Linux systems – in the /etc/grafana/grafana.ini directory.

You can find the locations for different operating systems at https://grafana.com/docs/grafana/latest/administration/configuration/#config-file-locations.

All configuration options are shown here: https://grafana.com/docs/grafana/latest/administration/configuration/.

We will explore some basic options to start using Grafana. In later chapters, you will learn about some other specific configuration settings.

The app_mode variable accepts two options: development and production. The default option is production and you must keep it unless you are planning to do some development:

app_mode  production

In the date_formats section, you can set date and time formats used in graphs and date-time boxes. In this section, you will find several options.

full_date is used to show a full date format where it is applicable.

Here’s an example:

full_date YYYY-MM-DD HH:mm:s

interval options are used in the graph to show partial dates or times.

The default options are as follows:

interval_second = HH:mm:ss

interval_minute = HH:mm

interval_hour = MM/DD HH:mm

interval_day = MM/DD

interval_month = YYYY-MM

interval_year = YYYY

use_browser_locale allows us to use date formats derived from the browser location. It is set to false by default.

With default_timezone, you can set your own time zone, or set it to use the browser location. The default option is the browser.

In the security section, you can set the administration user and security-related options. Some of these options, such as admin username and password, can be edited from the web interface.

In the paths section, you can see the paths that Grafana is using in your system.

In a Linux system, these paths are as follows:

data       /var/lib/grafana

logs       /var/log/grafana

plugins          /var/lib/grafana/plugins

provisioning    /etc/grafana/provisioning

Important Note

If you are using Docker to deploy Grafana, these paths cannot be modified in the configuration file. Instead, you will have to use environment variables.

You have now learned to use the configuration file to modify the behavior of Grafana. You also have seen the paths to important Grafana files.

In the next section, you will learn how to configure Grafana using environment variables.

Environment variables

In the previous section, you learned how to use environment variables with Docker. Now, you will see how to do this in the Linux host.

You can override any option in the configuration file using environment variables.

The syntax is as follows:

GF_<SectionName>_<KeyName>

So, if you want to change the admin user, you must type the following in the console:

export GF_SECURITY_ADMIN_USER=newadminuser

The same applies to every other option.

Note

You will have to restart Grafana for any configuration change to take effect.

Until here, you have learned how to install Grafana on-premises using different deployment options.

In the next section, you will learn how to use the Grafana Cloud service to avoid the installation and management process.

If you want to avoid all the work related to the installation and configuration of Grafana, maybe you can try using the Grafana Cloud service.

It takes a matter of minutes to create an account on Grafana Cloud and start using the platform. In the next screenshot, you can see the registration page:

Figure 1.2 – Registration page in Grafana Cloud

After you enter your email and password, you will receive an email to confirm the registration.

You will then access a 14-day trial of Grafana Pro. After those 14 days, you can subscribe or continue using the free version.

You can see the plans at https://grafana.com/products/cloud/pricing/.

Following the registration process, you will be able to access the Grafana Cloud services.

The first step when configuring your stack of Grafana is to select a name. In the free or trial versions, you have to use a domain ending with grafana.net, as shown in Figure 1.3. In the paid options, you can choose your domain.

Figure 1.3 – Naming your Grafana stack

After you name your stack, you will access the integration page.

Figure 1.4 – First screen accessing Grafana

Now you have a running instance of Grafana Cloud and can start using it.

In this chapter, you have learned how to install, configure, and run Grafana in three different scenarios. We first installed it on a Raspberry Pi, then on Ubuntu Server, and finally using Docker. Then you learned how to configure Grafana using the grafana.ini file and environment variables. Finally, you met the Grafana Cloud service, registered a new user, and set a stack name. Now you will be able to implement and run your own Grafana instance.

In the next chapter, you will explore the entire Grafana platform, learning about dashboards, plugins, data sources, users, and other things.

Read this book alongside other Grafana users and the author Rodrigo Juan Hernández.

Ask questions, provide solutions to other readers, chat with the author via Ask Me Anything sessions and much more.

SCAN the QR code or visit the link to join the community.

https://packt.link/iotgrafana