Installing Grafana

At its core, Grafana runs as a web server, and as such, it is not a typical double-click application. You will need to be comfortable with the command line and have administrator privileges on the computer you plan to install Grafana on. To download the latest versions of Grafana, check out https://grafana.com/grafana/download.

The Grafana application server runs on *nix operating systems (Linux, OS X, and Windows), and it can be installed locally on a laptop or workstation or on a remote server. It is even available as a hosted application if you’d rather not deal with setting up or managing a server application on your own.

In this section, we’ll walk through the most typical installation options:

• Docker
• OS X
• Linux
• Windows
• Hosted Grafana in the cloud

Once you’ve completed the installation of your choice, proceed to the Connecting to the Grafana server section for instructions on how to access Grafana from a web browser.

Grafana in a Docker container

The easiest and least complex installation method is to run Grafana from within a Docker container. Docker is available for all major platforms and can be downloaded by visiting https://www.docker.com/.

After installing Docker, open a terminal window and type in the following command:

% docker run -d --name=grafana -p 3000:3000 grafana/grafana

The percent (%) symbol is simply there to indicate we are typing in commands to an interactive shell such as zsh or Windows PowerShell. If you are cutting and pasting from the book, you’ll want to leave out that symbol.

Docker will automatically download and run the latest version of Grafana for your computer’s architecture. Bear in mind that since this basic container has no persistent storage, nothing will be retained if you delete the container. I suggest you run the container with a temporary volume so that Grafana’s internal database will continue to exist, even if you destroy the container:

% docker volume create grafana-storage
% docker run -d --name=grafana -p 3000:3000  \
    -v grafana-storage:/var/lib/grafana \
    grafana/grafana

Note

The book and its tutorial examples were written for the macOS operating system, a POSIX-compliant OS that shares many similarities to Linux, including the shell. However, with a few syntax modifications here and there, Windows users should be able to use these same commands in PowerShell.

For example, in the preceding command, you’ll want to use the backtick (`) in PowerShell for line continuation, rather than the backslash (\).

I will proceed with Docker and its companion product Docker Compose for the purposes of this book as it will allow an almost turnkey installation experience, as all the necessary dependencies will be automatically downloaded with the container. It will also install in its own sandbox, so you don’t need to worry about installing a stack of software that will be difficult to delete later. Finally, in future chapters, we will be setting up data sources using similar Docker containers, so managing the data pipeline as a combination of containers will be very consistent and straightforward.

Make and Makefile

In the book’s GitHub repository, you’ll find a Makefile in each chapter directory. You can use it to streamline some of the common Docker commands. If you’re not familiar with the make command or it isn’t installed on your computer, you can still cut and paste many of the commands embedded in the Makefile.

While space doesn’t permit a comprehensive introduction to the concepts that underlie make, here is a quick example of how to use it in concert with this book. The following is from the Makefile in the Chapter02 directory of the book’s GitHub repository:

up:
    docker-compose up -d --pull missing

On the first line, the word up before the colon (:) is referred to as the target. Anything following that colon is a dependency; there are no dependencies associated with the target. The second line is the command; there must be at least one command. For decades, the venerable make command and associated Makefile have been the backbone for building software, often with hundreds of complex dependencies. Nonetheless, for our use of make, we’ll use it mostly as a notepad of shortcut commands. To use it, you simply run a make command from the shell:

% make <target>

make will first run any targets named in the list of dependencies, followed by the command(s) associated with the target. Run the following:

% make up

You are using make to run this equivalent command:

% docker-compose up -d --pull missing

There is no requirement to use make for this book; all the commands you need are in the text.

Grafana for macOS

There are two options for installing and running Grafana for macOS:

• Homebrew
• Command line binary install

Using Homebrew is the simplest option as it wraps all the installation chores in a single command. To get Homebrew, visit https://brew.sh/. If you want more control over where to install Grafana, the command line option is a better choice.

Homebrew

Homebrew does not ship as part of macOS, but you can easily install it:

% /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

To install Grafana via Homebrew, run the following commands:

% brew update
% brew install grafana

If you want to keep Grafana running even after a reboot, use the Homebrew services subcommand to launch the installed Grafana application as a service. You will first need to confirm services installation:

% brew tap homebrew/services
% brew services start grafana

Command line binary install

To install via the command line, open a Terminal shell window and download the macOS distribution tarball, then untar it into the directory of your choice (replace ${GRAFANA_VERSION} with the current version):

% wget https://dl.grafana.com/oss/release/grafana-${GRAFANA_VERSION}.darwin-amd64.tar.gz
% tar -zxvf grafana-$GRAFANA_VERSION.darwin-amd64.tar.gz

Once you’ve untarred the file, cd into the directory and launch the binary by executing this command:

% ./bin/grafana-server web

Grafana for Linux

While Linux comes in a number of flavors, each falls into one of two installation systems: yum for Red Hat-based releases or apt for Debian or Ubuntu releases. Typically, you download the binary and then run the installer on the package file. To get the latest Grafana binaries for Linux, visit https://grafana.com/grafana/download?platform=linux.

Yum installation (Red Hat, Fedora, CentOS)

The installer for Red Hat distributions (CentOS, Fedora, and Red Hat) is yum. To download and install it (replace ${GRAFANA_VERSION} with the current version), use the following:

% wget https://dl.grafana.com/oss/release/grafana-%{GRAFANA_VERSION}.x86_64.rpm
% sudo yum install grafana-${GRAFANA_VERSION}.x86_64.rpm

To start up Grafana, use systemctl:

% systemctl daemon-reload
% systemctl start grafana-server
% systemctl status grafana-server

To keep Grafana running even after a reboot, use the following:

% sudo systemctl enable grafana-server.service

Apt installation (Debian, Ubuntu)

The installer for the Debian distributions (Debian and Ubuntu) is dpkg. To download and install it (replace ${GRAFANA_VERSION} with the current version), use the following:

% sudo apt-get install -y adduser libfontconfig1
% wget https://dl.grafana.com/oss/release/grafana_${GRAFANA_VERSION}_amd64.deb
% sudo dpkg -i grafana_${GRAFANA_VERSION}_amd64.deb

To start up Grafana, use the following:

% systemctl daemon-reload
% systemctl start grafana-server
% systemctl status grafana-server

To keep Grafana running even after a reboot, use the following:

% sudo systemctl enable grafana-server.service

Grafana for Windows

Installation for Windows is straightforward:

1. Go to https://grafana.com/grafana/download?platform=windows.
2. Download the latest MSI installer file from the download link.
3. Launch the .msi file to install.

Grafana Cloud

If you would rather not install Grafana on your computer, or you don’t have access to a computer that can run Grafana, there is another option—Grafana will host a free instance for you. Free Grafana Cloud hosting provides very generous limits on the number of users, metrics, logs, and traces. To sign up for the hosted version, go to https://grafana.com/get/ and select Cloud.

Now that you have installed and started up Grafana, let’s have a look at the interface. Grafana is a web application, so we’ll connect to it with an ordinary web browser such as Chrome, Safari, or Edge.