mirror of
https://github.com/grafana/grafana.git
synced 2024-11-30 20:54:22 -06:00
c9e566b156
* Update README.md Capitalized the G and S in "Getting Started," and moved "guide" to match the section title in the docs. * Fixed sentence structure. Changed "download" to "grafana.com/get" and changed "get" to "download". * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111)
224 lines
6.8 KiB
Markdown
224 lines
6.8 KiB
Markdown
# [Grafana](https://grafana.com) [](https://circleci.com/gh/grafana/grafana) [](https://goreportcard.com/report/github.com/grafana/grafana)
|
|
|
|
[Website](https://grafana.com) |
|
|
[Twitter](https://twitter.com/grafana) |
|
|
[Community & Forum](https://community.grafana.com)
|
|
|
|
Grafana is an open source, feature rich metrics dashboard and graph editor for
|
|
Graphite, Elasticsearch, OpenTSDB, Prometheus and InfluxDB.
|
|
|
|
<!---
|
|
|
|
-->
|
|
|
|
## Installation
|
|
|
|
Head to [docs.grafana.org](http://docs.grafana.org/installation/) for documentation or [grafana.com/get](https://grafana.com/get) to download the latest release.
|
|
|
|
## Documentation & Support
|
|
|
|
Be sure to read the [Getting Started](http://docs.grafana.org/guides/gettingstarted/) guide and the other feature guides.
|
|
|
|
## Run from master
|
|
|
|
If you want to build a package yourself, or contribute - here is a guide for how to do that. You can always find
|
|
the latest master builds [here](https://grafana.com/grafana/download).
|
|
|
|
### Dependencies
|
|
|
|
- Go (Latest Stable)
|
|
- Node.js LTS
|
|
- yarn [`npm install -g yarn`]
|
|
|
|
### Get the project
|
|
|
|
**The project located in the go-path will be your working directory.**
|
|
|
|
```bash
|
|
go get github.com/grafana/grafana
|
|
cd $GOPATH/src/github.com/grafana/grafana
|
|
```
|
|
|
|
### Run and rebuild on source change
|
|
|
|
#### Backend
|
|
|
|
To run the backend and rebuild on source change:
|
|
|
|
```bash
|
|
make run
|
|
```
|
|
|
|
#### Frontend
|
|
Install front-end dependencies first:
|
|
|
|
```bash
|
|
yarn install --pure-lockfile
|
|
```
|
|
|
|
Rebuild on file change, and serve them by Grafana's webserver (http://localhost:3000):
|
|
|
|
```bash
|
|
yarn start
|
|
```
|
|
|
|
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:hot
|
|
# OR set a theme
|
|
env GRAFANA_THEME=light yarn start:hot
|
|
```
|
|
|
|
_Note: HMR for Angular is not supported. If you edit files in the Angular part of the app, the whole page will reload._
|
|
|
|
Run tests and rebuild on source change:
|
|
|
|
```bash
|
|
yarn jest
|
|
```
|
|
|
|
**Open grafana in your browser (default: e.g. `http://localhost:3000`) and login with admin user (default: `user/pass = admin/admin`).**
|
|
|
|
### Building
|
|
|
|
#### The backend
|
|
|
|
```bash
|
|
go run build.go setup
|
|
go run build.go build
|
|
```
|
|
|
|
#### Frontend assets
|
|
|
|
_For this you need Node.js (LTS version)._
|
|
|
|
```bash
|
|
yarn install --pure-lockfile
|
|
```
|
|
|
|
### Building a Docker image
|
|
|
|
There are two different ways to build a Grafana docker image. If your machine is setup for Grafana development and you run linux/amd64 you can build just the image. Otherwise, there is the option to build Grafana completely within Docker.
|
|
|
|
Run the image you have built using: `docker run --rm -p 3000:3000 grafana/grafana:dev`
|
|
|
|
#### Building on linux/amd64 (fast)
|
|
|
|
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`.
|
|
|
|
#### Building anywhere (slower)
|
|
|
|
Choose this option to build on platforms other than linux/amd64 and/or not have to setup the Grafana development environment.
|
|
|
|
1. `make build-docker-full` or `docker build -t grafana/grafana:dev`.
|
|
|
|
The resulting image will be tagged as `grafana/grafana:dev`.
|
|
|
|
Notice: If you are using Docker for MacOS, be sure to set the memory limit to be larger than 2 GiB (at docker -> Preferences -> Advanced), otherwise `grunt build` may fail.
|
|
|
|
## Development
|
|
|
|
### 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
|
|
1. custom.ini
|
|
|
|
In your custom.ini uncomment (remove the leading `;`) sign. And set `app_mode = development`.
|
|
|
|
### Running tests
|
|
|
|
#### Frontend
|
|
|
|
Execute all frontend tests:
|
|
|
|
```bash
|
|
yarn test
|
|
```
|
|
|
|
Write and watch frontend tests:
|
|
|
|
- Start watcher: `yarn jest`.
|
|
- Jest runs all test files that end with the name ".test.ts".
|
|
|
|
#### Backend
|
|
|
|
```bash
|
|
# Run Golang tests using sqlite3 as database (default)
|
|
go test ./pkg/...
|
|
```
|
|
|
|
##### Running the MySQL or Postgres backend tests:
|
|
|
|
Run these by setting `GRAFANA_TEST_DB` in your environment.
|
|
|
|
- `GRAFANA_TEST_DB=mysql` to test MySQL
|
|
- `GRAFANA_TEST_DB=postgres` to test Postgres
|
|
|
|
Follow the instructions in `./devenv` to spin up test containers running the appropriate databases with `docker-compose`
|
|
- Use `docker/blocks/mysql_tests` or `docker/blocks/postgres_tests` as appropriate.
|
|
|
|
```bash
|
|
# MySQL
|
|
# Tests can only be ran in one Go package at a time due to clashing db queries. To run MySQL tests for the "pkg/services/sqlstore" package, run:
|
|
GRAFANA_TEST_DB=mysql go test ./pkg/services/sqlstore/...
|
|
|
|
# Or run all the packages using the circle CI scripts. This method will be slower as the scripts will run all the tests, including the integration tests.
|
|
./scripts/circle-test-mysql.sh
|
|
```
|
|
|
|
```bash
|
|
# Postgres
|
|
# Tests can only be ran in one Go package at a time due to clashing db queries. To run Postgres tests for the "pkg/services/sqlstore" package, run:
|
|
GRAFANA_TEST_DB=postgres go test ./pkg/services/sqlstore/...
|
|
|
|
# Or run all the packages using the circle CI scripts. This method will be slower as the scripts will run all the tests, including the integration tests.
|
|
./scripts/circle-test-postgres.sh
|
|
```
|
|
|
|
#### End-to-end
|
|
|
|
Execute all end-to-end tests:
|
|
|
|
```bash
|
|
yarn e2e-tests
|
|
```
|
|
|
|
Execute all end-to-end tests using using a specific url:
|
|
|
|
```bash
|
|
ENV BASE_URL=http://localhost:3333 yarn e2e-tests
|
|
```
|
|
|
|
Debugging all end-to-end tests (BROWSER=1 starts the browser and SLOWMO=1 delays each puppeteer operation by 100ms):
|
|
|
|
```bash
|
|
ENV BROWSER=1 SLOWMO=1 yarn e2e-tests
|
|
```
|
|
|
|
### 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 and experimenting.
|
|
|
|
## Contribute
|
|
|
|
If you have any ideas for improvement or have found a bug, do not hesitate to open an issue.
|
|
And if you have time, clone this repo and submit a pull request to help me make Grafana the kickass metrics and devops dashboard we all dream about!
|
|
|
|
Read the [contributing](https://github.com/grafana/grafana/blob/master/CONTRIBUTING.md) guide then check the [`beginner friendly`](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22beginner+friendly%22) label to find issues that are easy and that we would like help with.
|
|
|
|
## Plugin development
|
|
|
|
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.
|
|
|
|
## License
|
|
|
|
Grafana is distributed under [Apache 2.0 License](https://github.com/grafana/grafana/blob/master/LICENSE).
|