Skip to content

Commit

Permalink
Docs: Simplify README (grafana#19702)
Browse files Browse the repository at this point in the history
* Simplify README

* Fix review comments

* Rename Developer guide
  • Loading branch information
marcusolsson authored Oct 8, 2019
1 parent 9bff81e commit 096e0e7
Show file tree
Hide file tree
Showing 5 changed files with 94 additions and 207 deletions.
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Unsure where to begin contributing to Grafana? Start by browsing issues labeled
- [Beginner-friendly](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22beginner+friendly%22) issues are generally straightforward to complete.
- [Help wanted](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) issues are problems we would like the community to help us with regardless of complexity.

If you're looking to make a code change, see how to set up your environment for [local development](contribute/development.md).
If you're looking to make a code change, see how to set up your environment for [local development](contribute/developer-guide.md).

When you're ready to contribute, it's time to [Create a pull request](/contribute/pull-request.md).

Expand All @@ -69,6 +69,6 @@ Before we can accept your pull request, you need to [sign our CLA](https://grafa

## Where do I go from here?

- Set up your [development environment](contribute/development.md).
- Set up your [development environment](contribute/developer-guide.md).
- Learn how to [contribute documentation](contribute/documentation.md).
- Get started [developing plugins](https://grafana.com/docs/plugins/developing/development/) for Grafana.
233 changes: 28 additions & 205 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,222 +1,45 @@
# [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)
![Grafana](docs/logo-horizontal.png)

[Website](https://grafana.com) |
[Twitter](https://twitter.com/grafana) |
[Community & Forum](https://community.grafana.com)
The open-source platform for monitoring and observability.

Grafana is an open source, feature rich metrics dashboard and graph editor for
Graphite, Elasticsearch, OpenTSDB, Prometheus and InfluxDB.
[![License](https://img.shields.io/github/license/grafana/grafana)](LICENSE)
[![Circle CI](https://img.shields.io/circleci/build/gh/grafana/grafana)](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)

<!---
![](http://docs.grafana.org/assets/img/features/dashboard_ex1.png)
-->
Grafana allows you to query, visualize, alert on and understand your metrics no matter where they are stored. Create, explore, and share dashboards with your team and foster a data driven culture:

## Installation
- **Visualize:** Fast and flexible client side graphs with a multitude of options. Panel plugins for many different way to visualize metrics and logs.
- **Dynamic Dashboards:** Create dynamic & reusable dashboards with template variables that appear as dropdowns at the top of the dashboard.
- **Explore Metrics:** Explore your data through ad-hoc queries and dynamic drilldown. Split view and compare different time ranges, queries and data sources side by side.
- **Explore Logs:** Experience the magic of switching from metrics to logs with preserved label filters. Quickly search through all your logs or streaming them live.
- **Alerting:** Visually define alert rules for your most important metrics. Grafana will continuously evaluate and send notifications to systems like Slack, PagerDuty, VictorOps, OpsGenie.
- **Mixed Data Sources:** Mix different data sources in the same graph! You can specify a data source on a per-query basis. This works for even custom datasources.

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.
## Get started

## Documentation & Support
- [Get Grafana](https://grafana.com/get)
- [Installation guides](http://docs.grafana.org/installation/)

Be sure to read the [Getting Started](http://docs.grafana.org/guides/gettingstarted/) guide and the other feature guides.
Unsure if Grafana is for you? Watch Grafana in action on [play.grafana.org](https://play.grafana.org/)!

## Run from master
## Documentation

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).
The Grafana documentation is available at [grafana.com/docs](https://grafana.com/docs/).

### Dependencies
## Contributing

- Go (Latest Stable)
- Node.js LTS
- yarn [`npm install -g yarn`]
If you're interested in contributing to the Grafana project:

### Get the project
- Start by reading the [Contributing guide](/CONTRIBUTING.md).
- Learn how to set up your local environment, in our [Developer guide](/contribute/developer-guide.md).
- Explore our [beginner-friendly issues](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22beginner+friendly%22).

**The project located in the go-path will be your working directory.**
## Get involved

```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.
- Follow [@grafana on Twitter](https://twitter.com/grafana/)
- Read and subscribe to the [Grafana blog](https://grafana.com/blog/)
- If you have a specific question, check out our [discussion forums](https://community.grafana.com/).
- For general discussions, join us on the [official Slack](http://slack.raintank.io/) team.

## License

Expand Down
File renamed without changes.
Binary file added docs/logo-horizontal.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
64 changes: 64 additions & 0 deletions docs/logo-swirl.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 096e0e7

Please sign in to comment.