developer-guide.md 5.53 KB
Newer Older
1
# Developer guide
2

3
This guide helps you get started developing Grafana.
4
5
6
7
8
9
10
11
12
13

## Dependencies

Make sure you have the following dependencies installed before moving on to set up your developer environment:

- [Git](https://git-scm.com/)
- [Go](https://golang.org/dl/)
- [Node.js (Long Term Support)](https://nodejs.org)
- [Yarn](https://yarnpkg.com)

14
15
### macOS

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
We recommend using [Homebrew](https://brew.sh/) for installing any missing dependencies:

```
brew install git
brew install go
brew install node

npm install -g yarn
```

## Download Grafana

We recommend using Go to download the source code for the Grafana project:

1. Add `export GOPATH=$HOME/go/` to the bottom of your `$HOME/.bash_profile`.
1. Open a terminal and run `go get github.com/grafana/` in your terminal. This command downloads, and installs Grafana to your `$GOPATH`.
1. Open `$GOPATH/src/github.com/grafana/grafana` in your favorite code editor.

## Build Grafana

Grafana consists of two components; the _frontend_, and the _backend_.

### Frontend

Before we can build the frontend assets, we need to install the dependencies:

```
yarn install --pure-lockfile
```

46
After the command has finished, we can start building our source code:
47
48
49
50
51
52
53
54
55
56
57
58
59

```
yarn start
```

Once `yarn start` has built the assets it will continue to do so whenever any of the files change. This means you don't have to manually build the assets whenever you've made a change to the code.

Next, we'll build the web server that will serve the frontend assets we just built.

### Backend

Build and run the backend, by running `make run` in the root directory of the repository. This command will compile the Go source code, and start a web server.

60
By default, you can access the web server at `http://localhost:3000/`.
61
62
63
64

Log in using the default credentials:

| username | password |
65
66
| -------- | -------- |
| `admin`  | `admin`  |
67

68
When you log in for the first time, Grafana will ask you to change your password.
69
70
71

## Test Grafana

72
73
74
75
The test suite consists of three types of tests: _Frontend tests_, _backend tests_, and _end-to-end tests_.

### Run frontend tests

76
We use [jest](https://jestjs.io/) for our frontend tests. Run them using yarn:
77
78
79
80
81

```
yarn jest
```

82
83
### Run backend tests

84
85
86
87
88
89
If you're developing for the backend, run the tests with the standard Go tool:

```
go test -v ./pkg/...
```

90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
### Run end-to-end tests

The end-to-end tests in Grafana uses [puppeteer](https://github.com/GoogleChrome/puppeteer) to run automated scripts in a headless Chrome browser. To run the tests:

```
yarn e2e-tests
```

By default, the end-to-end tests assumes Grafana is available on `localhost:3000`. To use a specific URL, set the `BASE_URL` environment variable:

```
BASE_URL=http://localhost:3333 yarn e2e-tests
```

To follow the tests in the browser while they're running, add the `BROWSER` and `SLOWMO` environment variables:

```
BROWSER=1 SLOWMO=1 yarn e2e-tests
```

## Configure Grafana for development

The default configuration, `grafana.ini`, is located in the `conf` directory. 

To override the default configuration, create a `custom.ini` file in the `conf` directory. You only need to add the options you wish to override.

Enable the development mode, by adding the following line in your `custom.ini`:

```
app_mode = development
```


### Add data sources
124

125
By now, you should be able to build and test a change you've made to the Grafana source code. In most cases, you need to add at least one data source to verify the change.
126

127
To set up data sources for your development environment, go to the [devenv](devenv) directory in the Grafana repository:
128
129
130
131
132

```
cd devenv
```

133
Run the `setup.sh` script to setup a set of data sources and dashboards in your local Grafana. The script creates a set of data sources called **gdev-\<type\>**, and a set of dashboards located in a folder called **gdev dashboards**.
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

Some of the data sources require databases to run in the background.

Installing and configuring databases can be a tricky business. Grafana uses [Docker](https://docker.com) to make the task of setting up databases a little easier. Make sure you [install Docker](https://docs.docker.com/docker-for-mac/install/) before proceeding to the next step.

In the root directory of your Grafana repository, run the following command:

```
make devenv sources=influxdb,loki
```

The script generates a Docker Compose file with the databases you specify as `sources`, and runs them in the background.

See the repository for all the [available data sources](https://github.com/grafana/grafana/tree/master/devenv/docker/blocks). Note that some data sources have specific Docker images for macOS, e.g. `prometheus_mac`.

149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
## Build a Docker image

To build a Docker image, run:

```
make build-docker-full
```

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

**Note:** If you've already set up a local development environment, and you're running a `linux/amd64` machine, you can speed up building the Docker image:

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

**Note:** If you are using Docker for macOS, be sure to set the memory limit to be larger than 2 GiB. Otherwise `grunt build` may fail. The memory limit settings are available under **Docker Desktop** -> **Preferences** -> **Advanced**.

166
167
## Learn more

168
169
170
- Read our [style guides](/contribute/style-guides).
- Learn how to [Create a pull request](/contribute/pull-request.md).
- Read [How to contribute to Grafana as a junior dev](https://medium.com/@ivanahuckova/how-to-contribute-to-grafana-as-junior-dev-c01fe3064502) by [Ivana Huckova](https://medium.com/@ivanahuckova).