Installing Grafana with 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.