grafana/docs/sources/install.md

page_title	page_description	page_keywords
Grafana Installation	Install guide for Grafana.	grafana, installation, documentation

Installation

Grafana is a frontend for Graphite, InfluxDB and OpenTSDB with powerfull visualization features for time series data. You will need either a Graphite, InfluxDB or OpenTSDB server for Grafana to be of any use.

Download

Download the latest release. The release package contain a subfolder, for example grafana-1.7.0. The contents of this folder should be hosted by a web server, for example nginx, apache, IIS. The standard release packages does not contain a web server to host Grafana.

Dependencies

There are no dependencies, Grafana is a client side application that runs in your browser. It only needs a time series store where it can fetch metrics. If you use InfluxDB Grafana can use it to store dashboards. If you use Graphite or OpenTSDB you can use Elasticsearch to store dashboards or just use json files stored on disk.

Provisioning

If you prefer to install grafana via Puppet, Ansible, Docker or Chef. This page has compiled a list of repositories for different provisioning systems

Configuration

In your chosen Grafana install location, locate the file config.sample.js and copy or rename it to config.js. This files contains global settings for your Grafana installation.

Datasources

The datasources property defines your metric, annotation and dashboard storage backends.

• You can specify multiple datasources.
• default: true marks it as the default metric source (if you have multiple)
• grafanaDB: true marks it for use as dashboard storage (applicable for InfluxDB & Elasticsearch)

InfluxDB example setup

datasources: {
  'eu-metrics': {
    type: 'influxdb',
    url: 'http://my_influxdb_server:8086/db/<db_name>',
    username: 'test',
    password: 'test',
  },
  'grafana': {
    type: 'influxdb',
    url: 'http://my_influxdb_server:8086/db/grafana',
    username: 'test',
    password: 'test',
    grafanaDB: true
  },
},

In the above example you see two InfluxDB datasources, one for metrics and a seperate used for dashboard storage. You can use the same InfluxDB database for both. But it is probably a good idea to keep them seperate. The InfluxDB databases need to exist, grafana does not create them.

Graphite & Elasticsearch setup example

datasources: {
  graphite: {
    type: 'graphite',
    url: "http://my.graphite.server.com:8080",
  },
  elasticsearch: {
    type: 'elasticsearch',
    url: "http://my.elastic.server.com:9200",
    index: 'grafana-dash',
    grafanaDB: true,
  }
},

If you use Graphite you need Elasticsearch if you want to store & search dashboards. You can also use json and scripted dashboards if you really do not want to setup Elasticsearch.

OpenTSDB & Elasticsearch setup example

datasources: {
  opentsdb: {
    type: 'opentsdb',
    url: "http://my.opentsdb.server.com:4242",
  },
  elasticsearch: {
    type: 'elasticsearch',
    url: "http://my.elastic.server.com:9200",
    index: 'grafana-dash',
    grafanaDB: true,
  }
},

Please view this page for details on how to configure OpenTSDB to work with Grafana.

Elasticsearch & CORS

As of Elasticsearch v1.4 CORS is disabled by default. This needs to be enabled in the Elasticsearch config file, otherwise grafana will not be able to access Elasticsearch.

http.cors.enabled: true
http.cors.allow-origin: *

Instead of the wildcard you can put your full grafana webserver address (including http:// and port)

Basic authentication

If your Graphite or Elasticsearch server require basic authentication you can specify the username and password in the url. For example "http://admin:secret@my.graphite.com"

Global configuration options

// specify the limit for dashboard search results
search: {
  max_results: 20
},

// default start dashboard
default_route: '/dashboard/file/default.json',

// set to false to disable unsaved changes warning
unsaved_changes_warning: true,

// set the default timespan for the playlist feature
// Example: "1m", "1h"
playlist_timespan: "1m",

// If you want to specify password before saving, please specify it bellow
// The purpose of this password is not security, but to stop some users from accidentally changing dashboards
admin: {
  password: ''
},

// Add your own custom pannels
plugins: {
  panels: []
}

Graphite server config

If you haven't used an alternative dashboard for graphite before you need to enable CORS (Cross Origin Resource Sharing). This is only required if Grafana is hosted on a different web domain from your graphite-web.

For Apache 2.x:

Header set Access-Control-Allow-Origin "*"
Header set Access-Control-Allow-Methods "GET, OPTIONS"
Header set Access-Control-Allow-Headers "origin, authorization, accept"

Note that using "*" leaves your graphite instance quite open so you might want to consider using "http://my.grafana.com" in place of "*"

If your Graphite web is proteced by basic authentication, you have to enable the HTTP verb OPTIONS. Take note that when using basic auth Access-Control-Allow-Origin must not be set to a wildcard, also the header Access-Control-Allow-Credentials must be specified. This looks like the following for Apache:

Header set Access-Control-Allow-Origin    "http://mygrafana.com:5656"
Header set Access-Control-Allow-Methods   "GET, OPTIONS"
Header set Access-Control-Allow-Headers   "origin, authorization, accept"
Header set Access-Control-Allow-Credentials true

<Location />
    AuthName "graphs restricted"
    AuthType Basic
    AuthUserFile /etc/apache2/htpasswd
    <LimitExcept OPTIONS>
      require valid-user
    </LimitExcept>
</Location>

For nginx:

auth_basic            "Restricted";
auth_basic_user_file  /path/to/my/htpasswd/file;

if ($http_origin ~* (https?://[^/]*\.somedomain\.com(:[0-9]+)?)) {  #Test if request is from allowed domain, you can use multiple if
    set $cors "true";                                               #statements to allow multiple domains, simply setting $cors to true in each one.
}

if ($cors = 'true') {
    add_header  Access-Control-Allow-Origin $http_origin;           #this mirrors back whatever domain the request came from as authorized, as
    add_header  "Access-Control-Allow-Credentials" "true";          #as long as it matches one of your if statements
    add_header  "Access-Control-Allow-Methods" "GET, OPTIONS";
    add_header  "Access-Control-Allow-Headers" "Authorization, origin, accept";
}