README.md 4.52 KB
Newer Older
1
[Grafana](https://grafana.com) [![Circle CI](https://circleci.com/gh/grafana/grafana.svg?style=svg)](https://circleci.com/gh/grafana/grafana) [![Go Report Card](https://goreportcard.com/badge/github.com/grafana/grafana)](https://goreportcard.com/report/github.com/grafana/grafana) [![codecov](https://codecov.io/gh/grafana/grafana/branch/master/graph/badge.svg)](https://codecov.io/gh/grafana/grafana)
Torkel Ödegaard committed
2
================
Torkel Ödegaard committed
3
[Website](https://grafana.com) |
4
[Twitter](https://twitter.com/grafana) |
Torkel Ödegaard committed
5
[Community & Forum](https://community.grafana.com)
Rashid Khan committed
6

tuexss committed
7
Grafana is an open source, feature rich metrics dashboard and graph editor for
Torkel Ödegaard committed
8
Graphite, Elasticsearch, OpenTSDB, Prometheus and InfluxDB.
Torkel Ödegaard committed
9

Torkel Ödegaard committed
10
![](http://docs.grafana.org/assets/img/features/dashboard_ex1.png)
Torkel Ödegaard committed
11

12
## Installation
13
Head to [docs.grafana.org](http://docs.grafana.org/installation/) and [download](https://grafana.com/get)
14
the latest release.
Torkel Ödegaard committed
15

Torkel Ödegaard committed
16
If you have any problems please read the [troubleshooting guide](http://docs.grafana.org/installation/troubleshooting/).
17

18
## Documentation & Support
Torkel Ödegaard committed
19
Be sure to read the [getting started guide](http://docs.grafana.org/guides/gettingstarted/) and the other feature guides.
Torkel Ödegaard committed
20

21
## Run from master
noakup committed
22
If you want to build a package yourself, or contribute - Here is a guide for how to do that. You can always find
Torkel Ödegaard committed
23
the latest master builds [here](https://grafana.com/grafana/download)
Torkel Ödegaard committed
24 25 26

### Dependencies

Carl Bergquist committed
27
- Go 1.10
28
- NodeJS LTS
Torkel Ödegaard committed
29 30

### Building the backend
31
```bash
32
go get github.com/grafana/grafana
33
cd $GOPATH/src/github.com/grafana/grafana
34
go run build.go setup
Torkel Ödegaard committed
35
go run build.go build
Torkel Ödegaard committed
36 37 38 39
```

### Building frontend assets

40
For this you need nodejs (v.6+).
Torkel Ödegaard committed
41

42
To build the assets, rebuild on file change, and serve them by Grafana's webserver (http://localhost:3000):
43
```bash
44
npm install -g yarn
45
yarn install --pure-lockfile
Marcus Efraimsson committed
46
yarn watch
Torkel Ödegaard committed
47 48
```

49 50 51 52 53 54 55 56
Build the assets, rebuild on file change with Hot Module Replacement (HMR), and serve them by webpack-dev-server (http://localhost:3333):
```bash
yarn start
# OR set a theme
env GRAFANA_THEME=light yarn start
```
Note: HMR for Angular is not supported. If you edit files in the Angular part of the app, the whole page will reload.

57
Run tests
Torkel Ödegaard committed
58
```bash
Marcus Efraimsson committed
59
yarn jest
Torkel Ödegaard committed
60 61
```

Torkel Ödegaard committed
62
### Recompile backend on source change
63

64
To rebuild on source change.
65
```bash
Torkel Ödegaard committed
66 67 68 69
go get github.com/Unknwon/bra
bra run
```

70
Open grafana in your browser (default: `http://localhost:3000`) and login with admin user (default: `user/pass = admin/admin`).
Torkel Ödegaard committed
71

72 73 74 75 76 77 78 79 80
### Building a docker image (on linux/amd64)

This builds a docker image from your local sources:

1. Build the frontend `go run build.go build-frontend`
2. Build the docker image `make build-docker-dev`

The resulting image will be tagged as `grafana/grafana:dev`

Torkel Ödegaard committed
81 82 83 84 85 86
### 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
87
1. custom.ini
Torkel Ödegaard committed
88

89 90
In your custom.ini uncomment (remove the leading `;`) sign. And set `app_mode = development`.

91 92
### Running tests

93 94 95
#### Frontend
Execute all frontend tests
```bash
Marcus Efraimsson committed
96
yarn test
97
```
98

99
Writing & watching frontend tests
100

Marcus Efraimsson committed
101 102
- Start watcher: `yarn jest`
- Jest will run all test files that end with the name ".test.ts"
103

104 105 106
#### Backend
```bash
# Run Golang tests using sqlite3 as database (default)
107
go test ./pkg/...
108

109
# Run Golang tests using mysql as database - convenient to use /docker/blocks/mysql_tests
110
GRAFANA_TEST_DB=mysql go test ./pkg/...
111 112

# Run Golang tests using postgres as database - convenient to use /docker/blocks/postgres_tests
113
GRAFANA_TEST_DB=postgres go test ./pkg/...
114 115
```

116 117 118 119 120 121 122 123 124 125 126 127
## Building custom docker image

You can build a custom image using Docker, which doesn't require installing any dependencies besides docker itself.
```bash
git clone https://github.com/grafana/grafana
cd grafana
docker build -t grafana:dev .
docker run -d --name=grafana -p 3000:3000 grafana:dev
```

Open grafana in your browser (default: `http://localhost:3000`) and login with admin user (default: `user/pass = admin/admin`).

Morton Fox committed
128
## Contribute
Torkel Ödegaard committed
129

noakup committed
130
If you have any idea for an improvement or found a bug, do not hesitate to open an issue.
131 132
And if you have time clone this repo and submit a pull request and help me make Grafana
the kickass metrics & devops dashboard we all dream about!
Torkel Ödegaard committed
133

Torkel Ödegaard committed
134 135
## Plugin development

136 137
Checkout the [Plugin Development Guide](http://docs.grafana.org/plugins/developing/development/) and checkout the [PLUGIN_DEV.md](https://github.com/grafana/grafana/blob/master/PLUGIN_DEV.md) file for changes in Grafana that relate to
plugin development.
Torkel Ödegaard committed
138

139
## License
Torkel Ödegaard committed
140

141
Grafana is distributed under Apache 2.0 License.
Torkel Ödegaard committed
142