README.md 4.48 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's avatar
Torkel Ödegaard committed
2
================
Torkel Ödegaard's avatar
Torkel Ödegaard committed
3
[Website](https://grafana.com) |
tuexss's avatar
tuexss committed
4
[Twitter](https://twitter.com/grafana) |
Torkel Ödegaard's avatar
Torkel Ödegaard committed
5
[Community & Forum](https://community.grafana.com)
Rashid Khan's avatar
Rashid Khan committed
6

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

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

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

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

Torkel Ödegaard's avatar
Torkel Ödegaard committed
18
## Documentation & Support
Torkel Ödegaard's avatar
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's avatar
Torkel Ödegaard committed
20

Torkel Ödegaard's avatar
Torkel Ödegaard committed
21
## Run from master
noakup's avatar
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's avatar
Torkel Ödegaard committed
23
the latest master builds [here](https://grafana.com/grafana/download)
Torkel Ödegaard's avatar
Torkel Ödegaard committed
24
25
26

### Dependencies

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

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

### Building frontend assets

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

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

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.

Torkel Ödegaard's avatar
Torkel Ödegaard committed
57
Run tests 
Torkel Ödegaard's avatar
Torkel Ödegaard committed
58
```bash
Torkel Ödegaard's avatar
Torkel Ödegaard committed
59
npm run jest
Torkel Ödegaard's avatar
Torkel Ödegaard committed
60
61
```

Torkel Ödegaard's avatar
Torkel Ödegaard committed
62
Run karma tests
Torkel Ödegaard's avatar
Torkel Ödegaard committed
63
```bash
Torkel Ödegaard's avatar
Torkel Ödegaard committed
64
npm run karma
65
66
```

Torkel Ödegaard's avatar
Torkel Ödegaard committed
67
### Recompile backend on source change
68

bergquist's avatar
bergquist committed
69
To rebuild on source change.
bergquist's avatar
bergquist committed
70
```bash
Torkel Ödegaard's avatar
Torkel Ödegaard committed
71
72
73
74
go get github.com/Unknwon/bra
bra run
```

75
Open grafana in your browser (default: `http://localhost:3000`) and login with admin user (default: `user/pass = admin/admin`).
Torkel Ödegaard's avatar
Torkel Ödegaard committed
76

77
78
79
80
81
82
83
84
85
### 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's avatar
Torkel Ödegaard committed
86
87
88
89
90
91
### 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
92
1. custom.ini
Torkel Ödegaard's avatar
Torkel Ödegaard committed
93

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

96
97
### Running tests

98
99
100
#### Frontend
Execute all frontend tests
```bash
101
npm run test
102
```
103
104
105
106
107
108
109
110
111
112

Writing & watching frontend tests (we have two test runners)

- jest for all new tests that do not require browser context (React+more)
   - Start watcher: `npm run jest`
   - Jest will run all test files that end with the name ".jest.ts"
- karma + mocha is used for testing angularjs components. We do want to migrate these test to jest over time (if possible).
  - Start watcher: `npm run karma`
  - Karma+Mocha runs all files that end with the name "_specs.ts".

113
114
115
#### Backend
```bash
# Run Golang tests using sqlite3 as database (default)
116
go test ./pkg/... 
117

118
119
# Run Golang tests using mysql as database - convenient to use /docker/blocks/mysql_tests
GRAFANA_TEST_DB=mysql go test ./pkg/... 
120
121

# Run Golang tests using postgres as database - convenient to use /docker/blocks/postgres_tests
122
GRAFANA_TEST_DB=postgres go test ./pkg/... 
123
124
```

Morton Fox's avatar
Morton Fox committed
125
## Contribute
Torkel Ödegaard's avatar
Torkel Ödegaard committed
126

noakup's avatar
noakup committed
127
If you have any idea for an improvement or found a bug, do not hesitate to open an issue.
128
129
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's avatar
Torkel Ödegaard committed
130

Torkel Ödegaard's avatar
Torkel Ödegaard committed
131
132
## Plugin development

133
134
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's avatar
Torkel Ödegaard committed
135

Torkel Ödegaard's avatar
Torkel Ödegaard committed
136
## License
Torkel Ödegaard's avatar
Torkel Ödegaard committed
137

138
Grafana is distributed under Apache 2.0 License.
Torkel Ödegaard's avatar
Torkel Ödegaard committed
139