Skip to content

N
nexpie-grafana-theme
Commit 85b371a0 by oddlittlebird Committed by Marcus Olsson
Options

Docs: Getting started edits (#19915) 

* Getting started edits

Adjusted weights, moved some from mac.md to configuration.md, have some questions

* Update docs/sources/installation/configuration.md

Co-Authored-By: Marcus Olsson <olsson.e.marcus@gmail.com>

* Update docs/sources/installation/configuration.md

Co-Authored-By: Marcus Olsson <olsson.e.marcus@gmail.com>

* Update docs/sources/installation/configuration.md

Co-Authored-By: Marcus Olsson <olsson.e.marcus@gmail.com>

* Edited configuration.md

* Update docs/sources/installation/configuration.md

Co-Authored-By: Marcus Olsson <olsson.e.marcus@gmail.com>

* Update docs/sources/installation/configuration.md

Co-Authored-By: Marcus Olsson <olsson.e.marcus@gmail.com>

* Update docs/sources/installation/mac.md

Co-Authored-By: Marcus Olsson <olsson.e.marcus@gmail.com>

* Update docs/sources/installation/mac.md

Co-Authored-By: Marcus Olsson <olsson.e.marcus@gmail.com>

* Update docs/sources/installation/mac.md

Co-Authored-By: Marcus Olsson <olsson.e.marcus@gmail.com>

* Update requirements.md

* Update requirements.md

* Update building_from_source.md
parent 17724e9f
Showing with 55 additions and 233 deletions
docs/sources/installation/configuration.md
......@@ -17,7 +17,7 @@ specified in a `.ini` configuration file or specified using environment variable
> **Note.** Grafana needs to be restarted for any configuration changes to take effect.
## Comments In .ini Files
## Comments in .ini Files
Semicolons (the `;` char) are the standard way to comment out lines in a `.ini` file.
......@@ -35,6 +35,8 @@ A common problem is forgetting to uncomment a line in the `custom.ini` (or `graf
> used. This path is specified in the Grafana
> init.d script using `--config` file parameter.
**macOS:** By default, the configuration file is located at `/usr/local/etc/grafana/grafana.ini`.
## Using environment variables
All options in the configuration file (listed below) can be overridden
......@@ -79,9 +81,9 @@ system calls to get the machine name.
### data
Path to where Grafana stores the sqlite3 database (if used), file based
sessions (if used), and other data. This path is usually specified via
command line in the init.d script or the systemd service file.
Path to where Grafana stores the sqlite3 database (if used), file based sessions (if used), and other data. This path is usually specified via command line in the init.d script or the systemd service file.
**macOS:** The default SQLite database is located at `/usr/local/var/lib/grafana`
### temp_data_lifetime
......@@ -90,14 +92,15 @@ How long temporary images in `data` directory should be kept. Defaults to: `24h`
### logs
Path to where Grafana will store logs. This path is usually specified via
command line in the init.d script or the systemd service file. It can
be overridden in the configuration file or in the default environment variable
file.
Path to where Grafana will store logs. This path is usually specified via command line in the init.d script or the systemd service file. It can be overridden in the configuration file or in the default environment variable file.
**macOS:** By default, the log file should be located at `/usr/local/var/log/grafana/grafana.log`.
### plugins
Directory where grafana will automatically scan and look for plugins
Directory where Grafana will automatically scan and look for plugins. Manually or automatically install any plugins here.
**macOS:** By default, the Mac plugin location is: `/usr/local/var/lib/grafana/plugins`.
### provisioning
......
docs/sources/installation/debian.md
......@@ -8,7 +8,7 @@ aliases = ["/installation/installation/debian"]
name = "Installing on Ubuntu / Debian"
identifier = "debian"
parent = "installation"
weight = 1
weight = 200
+++
# Installing on Debian / Ubuntu
......@@ -27,34 +27,35 @@ sudo apt-get install -y adduser libfontconfig1
sudo dpkg -i grafana_<version>_amd64.deb
```
You will find package urls on the [download page](https://grafana.com/grafana/download?platform=linux).
You will find package URLs on the [download page](https://grafana.com/grafana/download?platform=linux).
## APT Repository
The command `add-apt-repository` isn't a default app on Debian 9 and requires
The command `add-apt-repository` isn't a default app on Debian 9 and requires you to run:
```bash
apt-get install -y software-properties-common
```
Install the repository for stable releases
Install the repository for stable releases:
```bash
sudo add-apt-repository "deb https://packages.grafana.com/oss/deb stable main"
```
There is a separate repository if you want beta releases.
There is a separate repository if you want beta releases:
```bash
sudo add-apt-repository "deb https://packages.grafana.com/oss/deb beta main"
```
Use the above line even if you are on Ubuntu or another Debian version. Then add our gpg key. This allows you to install signed packages.
Use the above line even if you are on Ubuntu or another Debian version. Then add our GPG key. This allows you to install signed packages.
```bash
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
```
Update your Apt repositories and install Grafana
Update your Apt repositories and install Grafana:
```bash
sudo apt-get update
......
docs/sources/installation/docker.md
......@@ -7,12 +7,12 @@ type = "docs"
name = "Installing using Docker"
identifier = "docker"
parent = "installation"
weight = 4
weight = 600
+++
# Installing using Docker
Grafana is very easy to install and run using the official docker container.
Grafana is very easy to install and run using the official Docker container.
```bash
$ docker run -d -p 3000:3000 grafana/grafana
......@@ -40,7 +40,7 @@ those options.
> For any changes to `conf/grafana.ini` (or corresponding environment variables) to take effect you need to restart Grafana by restarting the Docker container.
### Default Paths
### Default paths
The following settings are hard-coded when launching the Grafana Docker container and can only be overridden using environment variables, not in `conf/grafana.ini`.
......@@ -53,7 +53,7 @@ GF_PATHS_LOGS | /var/log/grafana
GF_PATHS_PLUGINS | /var/lib/grafana/plugins
GF_PATHS_PROVISIONING | /etc/grafana/provisioning
## Running a Specific Version of Grafana
## Running a specific version of Grafana
```bash
# specify right tag, e.g. 5.1.0 - see Docker Hub for available tags
......@@ -72,7 +72,7 @@ When running Grafana master in production we **strongly** recommend that you use
For a list of available tags, check out [grafana/grafana](https://hub.docker.com/r/grafana/grafana/tags/) and [grafana/grafana-dev](https://hub.docker.com/r/grafana/grafana-dev/tags/).
## Installing Plugins for Grafana
## Installing Grafana plugins
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.
......@@ -107,7 +107,7 @@ docker run \
> If you need to specify the version of a plugin, you can add it to the `GF_INSTALL_PLUGINS` build argument. Otherwise, the latest will be assumed. For example: `--build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5"`
## Installing Plugins from other sources
## Installing plugins from other sources
> Only available in Grafana v5.3.1+
......@@ -122,7 +122,7 @@ docker run \
grafana/grafana
```
## Configuring AWS Credentials for CloudWatch Support
## Configuring AWS credentials for CloudWatch Support
```bash
$ docker run \
......@@ -180,15 +180,14 @@ It's possible to supply Grafana with configuration through files. This works wel
You can do this with any of the configuration options in conf/grafana.ini by setting `GF_<SectionName>_<KeyName>__FILE` to the path of the file holding the secret.
Let's say you want to set the admin password this way.
Let's say you want to set the admin password this way:
- Admin password secret: `/run/secrets/admin_password`
- Environment variable: `GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password`
## Migration from a previous version of the docker container to 5.1 or later
The docker container for Grafana has seen a major rewrite for 5.1.
The Docker container for Grafana has seen a major rewrite for 5.1.
**Important changes**
......
docs/sources/installation/mac.md
......@@ -5,12 +5,15 @@ keywords = ["grafana", "configuration", "documentation", "mac", "homebrew", "osx
type = "docs"
[menu.docs]
parent = "installation"
weight = 4
weight = 500
+++
# Installing on macOS
This page provides instructions to help you install Grafana on macOS. You can either install using homebrew or a binary tar file.
## Install using homebrew
Installation can be done using [homebrew](http://brew.sh/)
......@@ -46,7 +49,7 @@ To upgrade grafana if you've installed from HEAD:
brew reinstall --HEAD grafana/grafana/grafana
```
### Starting Grafana
### Start Grafana
To start Grafana using homebrew services first make sure homebrew/services is installed.
......@@ -62,24 +65,7 @@ brew services start grafana
Default login and password `admin`/ `admin`
### Configuration
The Configuration file should be located at `/usr/local/etc/grafana/grafana.ini`.
### Logs
The log file should be located at `/usr/local/var/log/grafana/grafana.log`.
### Plugins
If you want to manually install a plugin place it here: `/usr/local/var/lib/grafana/plugins`.
### Database
The default sqlite database is located at `/usr/local/var/lib/grafana`
## Installing from binary tar file
## Install from binary tar file
Download [the latest `.tar.gz` file](https://grafana.com/get) and
extract it. This will extract into a folder named after the version you
......@@ -90,11 +76,6 @@ To configure Grafana add a configuration file named `custom.ini` to the
`conf` folder and override any of the settings defined in
`conf/defaults.ini`.
Start Grafana by executing `./bin/grafana-server web`. The `grafana-server`
binary needs the working directory to be the root install directory (where the
binary and the `public` folder is located).
## Logging in for the first time
### Start Grafana
To run Grafana open your browser and go to http://localhost:3000/. 3000 is the default HTTP port that Grafana listens to if you haven't [configured a different port](/installation/configuration/#http-port).
Then follow the instructions [here](/guides/getting_started/).
Start Grafana by executing `./bin/grafana-server`. The `grafana-server` binary needs the working directory to be the root install directory (where the binary and the `public` folder is located).
docs/sources/installation/requirements.md
......@@ -7,23 +7,23 @@ type = "docs"
name = "Requirements"
identifier = "requirements"
parent = "installation"
weight = -1
weight = 100
+++
# Requirements
This page includes useful information on the supported Operating Systems as well as the hardware requirements that are needed to install and use Grafana.
## Operating Systems
## Supported operating systems
### Supported
The following operating systems are supported for Grafana installation:
- [Debian / Ubuntu](/installation/debian)
- [RPM-based Linux (CentOS, Fedora, OpenSuse, RedHat)](/installation/rpm)
- [macOS](/installation/mac)
- [Windows](/installation/windows)
### Unsupported
## Unsupported operating systems
Installation of Grafana on other operating systems is possible, but not supported. Please see the [building from source](/project/building_from_source/#building-grafana-from-source) guide for more information.
......@@ -47,29 +47,16 @@ Grafana supports the following databases:
- MySQL
- PostgreSQL
Per default Grafana ships with and uses SQLite which is an embedded database stored on disk in Grafana's installation location.
Per default Grafana ships with and uses SQLite, which is an embedded database stored on disk in Grafana's installation location.
## Supported web browsers
Grafana is supported in the following browsers:
Grafana is supported in the current version of the following browsers. Older versions of these browsers might not be supported, so you should always upgrade to the latest version when using Grafana.
- Chrome/Chromium
- Firefox
- Safari
- Microsoft Edge
- Internet Explorer 11 is only fully supported in Grafana versions prior v6.0.
> Note 1: Older versions of above browsers may not be supported
> Note 2: Internet Explorer 11 is only fully supported in Grafana versions prior v6.0.
> Note 3: Running Grafana without JavaScript enabled in the browser is not supported
### Known issues
#### Problem with logging in using Safari 12
There is a known [iOS Safari 12 issue](https://bugs.webkit.org/show_bug.cgi?id=188165) that prevents the Grafana session cookie from being written after a successful login.
A quick workaround for this problem would be to configure [cookie_samesite](/installation/configuration/#cookie-samesite) to `none`. However, there is another known [Safari 12 issue](https://bugs.webkit.org/show_bug.cgi?id=198181) that threats `SameSite=none` as `strict` which also
prevents the Grafana session cookie from being written after a successful login.
To resolve using `none` as `SameSite` cookie attribute in combination with Safari 12, please upgrade to at least Grafana v6.3.3 which includes a fix.
> Note: Always enable JavaScript in your browser. Running Grafana without JavaScript enabled in the browser is not supported.
docs/sources/installation/rpm.md
......@@ -8,7 +8,7 @@ type = "docs"
name = "Installing on Centos / Redhat"
identifier = "rpm"
parent = "installation"
weight = 2
weight = 300
+++
# Installing on RPM-based Linux (CentOS, Fedora, OpenSuse, RedHat)
......@@ -22,13 +22,13 @@ Go to the [download page](https://grafana.com/grafana/download?platform=linux) f
links.
You can install Grafana using Yum directly.
You can install Grafana using Yum directly:
```bash
$ sudo yum install <rpm package url>
```
You will find package urls on the [download page](https://grafana.com/grafana/download?platform=linux).
You will find package URLs on the [download page](https://grafana.com/grafana/download?platform=linux).
Or install manually using `rpm`. First execute
......@@ -87,8 +87,7 @@ $ sudo yum install grafana
### RPM GPG Key
The RPMs are signed, you can verify the signature with this [public GPG
key](https://packages.grafana.com/gpg.key).
The RPMs are signed, you can verify the signature with this [public GPG key](https://packages.grafana.com/gpg.key).
## Package details
......
docs/sources/installation/upgrading.md
......@@ -7,13 +7,13 @@ type = "docs"
name = "Upgrading"
identifier = "upgrading"
parent = "installation"
weight = 10
weight = 800
+++
# Upgrading Grafana
We recommend everyone to upgrade Grafana often to stay up to date with the latest fixes and enhancements.
In order make this a reality Grafana upgrades are backward compatible and the upgrade process is simple and quick.
In order make this a reality, Grafana upgrades are backward compatible and the upgrade process is simple and quick.
Upgrading is generally always safe (between many minor and one major version) and dashboards and graphs will look the same. There can be minor breaking changes in some edge cases which are usually outlined in the [Release Notes](https://community.grafana.com/c/releases) and [Changelog](https://github.com/grafana/grafana/blob/master/CHANGELOG.md)
......@@ -134,7 +134,6 @@ If you're using systemd and have a large amount of annotations consider temporar
If you have text panels with script tags they will no longer work due to a new setting that per default disallow unsanitized HTML.
Read more [here](/installation/configuration/#disable-sanitize-html) about this new setting.
### Authentication and security
If your using Grafana's builtin, LDAP (without Auth Proxy) or OAuth authentication all users will be required to login upon the next visit after the upgrade.
......@@ -201,6 +200,3 @@ One of the database migrations included in this release will merge multiple rows
Plugins that need updating:
* [Splunk](https://grafana.com/grafana/plugins/grafana-splunk-datasource)
docs/sources/installation/windows.md
......@@ -5,7 +5,7 @@ keywords = ["grafana", "configuration", "documentation", "windows"]
type = "docs"
[menu.docs]
parent = "installation"
weight = 3
weight = 400
+++
# Installing on Windows
......
docs/sources/project/building_from_source.md
......@@ -3,154 +3,9 @@ title = "Building from source"
type = "docs"
[menu.docs]
parent = "installation"
weight = 5
weight = 700
+++
# Building Grafana from source
This guide will help you create packages from source and get grafana up and running in
dev environment. Grafana ships with its own required backend server; also completely open-source. It's written in [Go](http://golang.org) and has a full [HTTP API](/v2.1/reference/http_api/).
## Dependencies
- [Go (Latest Stable)](https://golang.org/dl/)
- [Git](https://git-scm.com/downloads)
- [NodeJS LTS](https://nodejs.org/download/)
- node-gyp is the Node.js native addon build tool and it requires extra dependencies: python 2.7, make and GCC. These are already installed for most Linux distros and macOS. See the Building On Windows section or the [node-gyp installation instructions](https://github.com/nodejs/node-gyp#installation) for more details.
## Get Code
Create a directory for the project and set your path accordingly (or use the [default Go workspace directory](https://golang.org/doc/code.html#GOPATH)). Then download and install Grafana into your $GOPATH directory:
```bash
export GOPATH=`pwd`
go get github.com/grafana/grafana
```
On Windows use setx instead of export and then restart your command prompt:
```bash
setx GOPATH %cd%
```
You may see an error such as: `package github.com/grafana/grafana: no buildable Go source files`. This is just a warning, and you can proceed with the directions.
## Building the backend
```bash
cd $GOPATH/src/github.com/grafana/grafana
go run build.go setup
go run build.go build # (or 'go build ./pkg/cmd/grafana-server')
```
#### Building on Windows
The Grafana backend includes Sqlite3 which requires GCC to compile. So in order to compile Grafana on Windows you need to install GCC. We recommend [TDM-GCC](http://tdm-gcc.tdragon.net/download).
[node-gyp](https://github.com/nodejs/node-gyp#installation) is the Node.js native addon build tool and it requires extra dependencies to be installed on Windows. In a command prompt which is run as administrator, run:
```bash
npm --add-python-to-path='true' --debug install --global windows-build-tools
```
## Build the Frontend Assets
For this you need nodejs (v.6+):
```bash
npm install -g yarn
yarn install --pure-lockfile
yarn start
```
## Running Grafana Locally
You can run a local instance of Grafana by running:
```bash
./bin/grafana-server
```
Or, if you built the binary with `go run build.go build`, run `./bin/<os>-<architecture>/grafana-server`
If you built it with `go build .`, run `./grafana`
Open grafana in your browser (default [http://localhost:3000](http://localhost:3000)) and login with admin user (default user/pass = admin/admin).
# Developing Grafana
To add features, customize your config, etc, you'll need to rebuild the backend when you change the source code. We use a tool named `bra` that
does this.
If you using *nix machine, you can just use the `make run` command, otherwise you need install `bra` binary first:
```bash
go get github.com/unknwon/bra
bra run
```
You'll also need to run `yarn start` to watch for changes to the front-end (typescript, html, sass)
### Running tests
- You can run backend Golang tests using `go test ./pkg/...`.
- Execute all frontend tests with `yarn test`
Writing and watching frontend tests
- Start watcher: `yarn jest`
- Jest will run all test files that end with the name ".test.ts"
### Data source and dashboard provisioning
[Here](https://github.com/grafana/grafana/tree/master/devenv) you can find helpful scripts and docker-compose setup
that will populate your dev environment for quicker testing end experimenting.
## Creating optimized release packages
This step builds Linux packages and requires that fpm is installed. Install fpm via `gem install fpm`:
```bash
go run build.go build package
```
## Dev config
Create a custom.ini in the conf directory to override default configuration options.
You only need to add the options you want to override. Config files are applied in the order of:
1. grafana.ini
2. custom.ini
### Set app_mode to development
In your custom.ini uncomment (remove the leading `;`) sign. And set `app_mode = development`.
Learn more about Grafana config options in the [Configuration section](/installation/configuration/)
## Create a pull requests
Please contribute to the Grafana project and submit a pull request! Build new features, write or update documentation, fix bugs and generally make Grafana even more awesome.
# Troubleshooting
**Problem**: PhantomJS or node-sass errors when running grunt
**Solution**: delete the node_modules directory. Install [node-gyp](https://github.com/nodejs/node-gyp#installation) properly for your platform. Then run `yarn install --pure-lockfile` again.
<br><br>
**Problem**: When running `make run` for the first time you get an error that it is not a recognized command.
**Solution**: Add the bin directory in your Go workspace directory to the path. Per default this is `$HOME/go/bin` on Linux and `%USERPROFILE%\go\bin` on Windows or `$GOPATH/bin` (`%GOPATH%\bin` on Windows) if you have set your own workspace directory.
<br><br>
**Problem**: When executing a `go get` command on Windows and you get an error about the git repository not existing.
**Solution**: `go get` requires Git. If you run `go get` without Git then it will create an empty directory in your Go workspace for the library you are trying to get. Even after installing Git, you will get a similar error. To fix this, delete the empty directory (for example: if you tried to run `go get github.com/unknwon/bra` then delete `%USERPROFILE%\go\src\github.com\unknwon\bra`) and run the `go get` command again.
<br><br>
**Problem**: On Windows, getting errors about a tool not being installed even though you just installed that tool.
**Solution**: It is usually because it got added to the path and you have to restart your command prompt to use it.
## Logging in for the first time
To run Grafana open your browser and go to the default port http://localhost:3000 or the port you have configured.
Then follow the instructions [here](/guides/getting_started/).
Refer to the [Grafana developer guide](contribute\developer-guide.md) for information about building Grafana from the source code.
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment