This guide helps you get started developing Grafana.
Before you begin, you might want to read How to contribute to Grafana as a junior dev by Ivana Huckova.
Make sure you have the following dependencies installed before setting up your developer environment:
- Git
- Go (see go.mod for minimum required version)
- Node.js (Long Term Support)
- Yarn
We recommend using Homebrew for installing any missing dependencies:
brew install git
brew install go
brew install node@12
npm install -g yarn
We recommend using Go to download the source code for the Grafana project:
- Add
export GOPATH=$HOME/go/
to the bottom of your$HOME/.bash_profile
. - Open a terminal and run
go get github.com/grafana/grafana
in your terminal. This command downloads, and installs Grafana to your$GOPATH
. - Open
$GOPATH/src/github.com/grafana/grafana
in your favorite code editor.
Grafana consists of two components; the frontend, and the backend.
Before we can build the frontend assets, we need to install the dependencies:
yarn install --pure-lockfile
After the command has finished, we can start building our source code:
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 every time you change the code.
Next, we'll build the web server that will serve the frontend assets we just built.
Build and run the backend by running make run
in the root directory of the repository. This command compiles the Go source code and starts a web server.
Are you having problems with too many open files?
By default, you can access the web server at http://localhost:3000/
.
Log in using the default credentials:
username | password |
---|---|
admin |
admin |
When you log in for the first time, Grafana asks you to change your password.
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.
The test suite consists of three types of tests: Frontend tests, backend tests, and end-to-end tests.
We use jest for our frontend tests. Run them using Yarn:
yarn jest
If you're developing for the backend, run the tests with the standard Go tool:
go test -v ./pkg/...
The end to end tests in Grafana use Cypress to run automated scripts in a headless Chromium browser. Read more about our e2e framework.
To run the tests:
yarn e2e-tests
By default, the end-to-end tests assume 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, use the yarn e2e-tests:debug
instead.
yarn e2e-tests:debug
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
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.
To set up data sources for your development environment, go to the devenv directory in the Grafana repository:
cd devenv
Run the setup.sh
script to set up a set of data sources and dashboards in your local Grafana instance. The script creates a set of data sources called gdev-<type>, and a set of dashboards located in a folder called gdev dashboards.
Some of the data sources require databases to run in the background.
Installing and configuring databases can be a tricky business. Grafana uses Docker to make the task of setting up databases a little easier. Make sure you install Docker 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. Note that some data sources have specific Docker images for macOS, e.g. prometheus_mac
.
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:
- Build the frontend:
go run build.go build-frontend
. - 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.
Are you having issues with setting up your environment? Here are some tips that might help.
Depending on your environment, you may have to increase the maximum number of open files allowed. For the rest of this section, we will assume you are on a Unix like OS (e.g. Linux/MacOS), where you can control the maximum number of open files through the ulimit shell command.
To see how many open files are allowed, run:
ulimit -a
To change the number of open files allowed, run:
ulimit -S -n 2048
The number of files needed may be different on your environment. To determine the number of open files needed by make run
, run:
find ./conf ./pkg ./public/views | wc -l
Another alternative is to limit the files being watched. The directories that are watched for changes are listed in the .bra.toml
file in the root directory.
To retain your ulimit
configuration, i.e. so it will be remembered for future sessions, you need to commit it to your command line shell initialization file. Which file this will be depends on the shell you are using, here are some examples:
- zsh -> ~/.zshrc
- bash -> ~/.bashrc
Commit your ulimit configuration to your shell initialization file as follows ($LIMIT being your chosen limit and $INIT_FILE being the initialization file for your shell):
echo ulimit -S -n $LIMIT >> $INIT_FILE
Your command shell should read the initialization file in question every time it gets started, and apply your ulimit
command.
For some people, typically using the bash shell, ulimit fails with an error similar to the following:
ulimit: open files: cannot modify limit: Operation not permitted
If that happens to you, chances are you've already set a lower limit and your shell won't let you set a higher one. Try looking in your shell initalization files (~/.bashrc typically), if there's already a ulimit command that you can tweak.
- Read our style guides.
- Learn how to Create a pull request.
- Read How to contribute to Grafana as a junior dev by Ivana Huckova.
- Read about the architecture.