Installing using Docker

Grafana is very easy to install and run using the official docker container.

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

Configuration

All options defined in conf/grafana.ini can be overridden using environment variables by using the syntax GF_<SectionName>_<KeyName>. For example:

$ docker run \
  -d \
  -p 3000:3000 \
  --name=grafana \
  -e "GF_SERVER_ROOT_URL=http://grafana.server.name" \
  -e "GF_SECURITY_ADMIN_PASSWORD=secret" \
  grafana/grafana

The back-end web server has a number of configuration options. Go to the Configuration page for details on all those options.

Running a Specific Version of Grafana

# specify right tag, e.g. 5.1.0 - see Docker Hub for available tags
$ docker run \
  -d \
  -p 3000:3000 \
  --name grafana \
  grafana/grafana:5.1.0

Installing Plugins for Grafana

Pass the plugins you want installed to docker with the GF_INSTALL_PLUGINS environment variable as a comma separated list. This will pass each plugin name to grafana-cli plugins install ${plugin} and install them when Grafana starts.

docker run \
  -d \
  -p 3000:3000 \
  --name=grafana \
  -e "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
  grafana/grafana

Building a custom Grafana image with pre-installed plugins

In the grafana-docker there is a folder called custom/ which includes a Dockerfile that can be used to build a custom Grafana image. It accepts GRAFANA_VERSION and GF_INSTALL_PLUGINS as build arguments.

Example of how to build and run:

cd custom
docker build -t grafana:latest-with-plugins \
  --build-arg "GRAFANA_VERSION=latest" \
  --build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" .

docker run \
  -d \
  -p 3000:3000 \
  --name=grafana \
  grafana:latest-with-plugins

Configuring AWS Credentials for CloudWatch Support

$ docker run \
  -d \
  -p 3000:3000 \
  --name=grafana \
  -e "GF_AWS_PROFILES=default" \
  -e "GF_AWS_default_ACCESS_KEY_ID=YOUR_ACCESS_KEY" \
  -e "GF_AWS_default_SECRET_ACCESS_KEY=YOUR_SECRET_KEY" \
  -e "GF_AWS_default_REGION=us-east-1" \
  grafana/grafana

You may also specify multiple profiles to GF_AWS_PROFILES (e.g. GF_AWS_PROFILES=default another).

Supported variables:

  • GF_AWS_${profile}_ACCESS_KEY_ID: AWS access key ID (required).
  • GF_AWS_${profile}_SECRET_ACCESS_KEY: AWS secret access key (required).
  • GF_AWS_${profile}_REGION: AWS region (optional).
# create a persistent volume for your data in /var/lib/grafana (database and plugins)
docker volume create grafana-storage

# start grafana
docker run \
  -d \
  -p 3000:3000 \
  --name=grafana \
  -v grafana-storage:/var/lib/grafana \
  grafana/grafana

Grafana container using bind mounts

You may want to run Grafana in Docker but use folders on your host for the database or configuration. When doing so it becomes important to start the container with a user that is able to access and write to the folder you map into the container.

mkdir data # creates a folder for your data
ID=$(id -u) # saves your user id in the ID variable

# starts grafana with your user id and using the data folder
docker run -d --user $ID --volume "$PWD/data:/var/lib/grafana" -p 3000:3000 grafana/grafana:5.1.0

Migration from a previous version of the docker container to 5.1 or later

In 5.1 we switched the id of the grafana user. Unfortunately this means that files created prior to 5.1 won’t have the correct permissions for later versions. We made this change so that it would be easier for you to control what user Grafana is executed as (see examples below).

VersionUserUser ID
< 5.1grafana104
>= 5.1grafana472

There are two possible solutions to this problem. Either you start the new container as the root user and change ownership from 104 to 472 or you start the upgraded container as user 104.

Running docker as a different user

docker run --user 104 --volume "<your volume mapping here>" grafana/grafana:5.1.0

docker-compose.yml with custom user

version: "2"

services:
  grafana:
    image: grafana/grafana:5.1.0
    ports:
      - 3000:3000
    user: "104"

Modifying permissions

The commands below will run bash inside the Grafana container with your volume mapped in. This makes it possible to modify the file ownership to match the new container. Always be careful when modifying permissions.

$ docker run -ti --user root --volume "<your volume mapping here>" --entrypoint bash grafana/grafana:5.1.0

# in the container you just started:
chown -R root:root /etc/grafana && \
  chmod -R a+r /etc/grafana && \
  chown -R grafana:grafana /var/lib/grafana && \
  chown -R grafana:grafana /usr/share/grafana