From 2c28f8cdca5cc89d3291a11fb08355970d582612 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torkel=20=C3=96degaard?= Date: Tue, 10 Mar 2015 17:25:11 +0100 Subject: [PATCH] Began work on grafana 2.0 install instructions --- docs/sources/installation/index.md | 232 +++++++---------------------- 1 file changed, 57 insertions(+), 175 deletions(-) diff --git a/docs/sources/installation/index.md b/docs/sources/installation/index.md index 3b49cfa2761..7de73c45998 100644 --- a/docs/sources/installation/index.md +++ b/docs/sources/installation/index.md @@ -5,184 +5,66 @@ page_keywords: grafana, installation, documentation --- # Installation +Grafana is easily installed via a Debian/Ubuntu package (.deb), via Redhat/Centos package (.rpm) or manually via +a tar that contains all required files and binaries. If there is not a package or binary for you specific platform you might be able +to build one your self, read [build from source](../project/building_from_source) instructions for more information. -[Download](http://grafana.org/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. +## From Ubuntu & Debian package +Start by [downloading](http://grafana.org/download/builds) the latest `.deb` package. -### 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. +To install the package: -### Provisioning -If you prefer to install grafana via Puppet, Ansible, Docker or Chef. [This page](/docs/provisioning) has compiled a +``` +sudo dpkg -i grafana_latest_amd64.deb +``` + +## From Redhat & Centos package +Start by [downloading](http://grafana.org/download/builds) the latest `.rpm` package. + +``` +sudo rpm -Uvh grafana-latest-1.x86_64.rpm +``` + +On Redhat/RHEL 5.10 you need to add the grafana user before executing the above. +Execute this to add a grafana user: + +``` +sudo useradd -r grafana + +``` + +### Package details +The `.deb` and the `rpm` package install will do the following + +- Install binaries and frontend files under `/opt/grafana/versions/` +- Symlink dir `/opt/grafana/current` to `/opt/grafana/versions/` +- Symlink `/etc/init.d/grafana` to `/opt/grafana/current/scripts/init.sh` +- Add config file to `/etc/grafana/grafana.ini` , this is where you specify your config settings +- Default configuration is in `/opt/grafana/current/conf/defaults.ini`, do not modify that file +- The default configuration specifies log file at `/var/log/grafana/grafana.log` +- The default configuration specifies sqlite3 db at `/opt/grafana/data/grafana.db` + +### Start the backend & web server + +- Start grafana by `sudo service grafana start` +- This will start the grafana process as the `grafana` user (created during package install) +- Default http port is `3000`, and default user is admin/admin + +## Manual install from tar file +Start by [downloading](http://grafana.org/download/builds) the latest `.tar.gz` file and extract it. +This will extract into a folder named after the version you downloaded. This folder contains all files required to run grafana. +There are no init scripts or install scripts in this package. + +To configure grafana add a config file named `custom.ini` to the `conf` folder and override any of the settings defined in +`conf/defaults.ini`. Start grafana by excecuting `./grafana web`. The grafana binary needs the working directory +to be the root install dir (where the binary is and the public folder is located). + +## Dependencies +There are no dependencies with the default configuration. You can switch from a sqlite3 database to mysql or postgres but +that is optional. For small to medium setups sqlite3 should suffice. + +## Install using provisioning +If you prefer to install grafana via Puppet, Ansible, Docker or Chef. [This page](provisioning) 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 -```javascript -datasources: { - 'eu-metrics': { - type: 'influxdb', - url: 'http://my_influxdb_server:8086/db/', - 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 - -```javascript -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 - -```javascript -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](/docs/features/opentsdb) 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 - -```javascript -// 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: - -```javascript -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: - -```html -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 - - - AuthName "graphs restricted" - AuthType Basic - AuthUserFile /etc/apache2/htpasswd - - require valid-user - - -``` - -For nginx: - -```javascript -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"; -} -```