mirror of
https://github.com/grafana/grafana.git
synced 2025-09-17 18:43:49 +08:00
Add Grafana tutorials originally from tutorials repository (#62124)
* Add Grafana tutorials originally from tutorials repository Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Replace tutorials/step shortcode with ordinary headings Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix typos reported by codespell Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix doc-validator linting and run prettier Signed-off-by: Jack Baldry <jack.baldry@grafana.com> Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
This commit is contained in:
40
docs/sources/shared/tutorials/create-plugin.md
Executable file
40
docs/sources/shared/tutorials/create-plugin.md
Executable file
@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Create Plugin
|
||||
---
|
||||
|
||||
Tooling for modern web development can be tricky to wrap your head around. While you certainly can write your own webpack configuration, for this guide, you'll be using grafana create-plugin tool
|
||||
|
||||
Grafana [create-plugin tool](https://www.npmjs.com/package/@grafana/create-plugin) is a CLI application that simplifies Grafana plugin development, so that you can focus on code. The tool scaffolds a starter plugin and all the required configuration for you.
|
||||
|
||||
1. In the plugin directory, create a plugin from template using create-plugin:
|
||||
|
||||
```
|
||||
npx @grafana/create-plugin
|
||||
```
|
||||
|
||||
1. Change directory to your newly created plugin:
|
||||
|
||||
```
|
||||
cd my-plugin
|
||||
```
|
||||
|
||||
1. Install the dependencies:
|
||||
|
||||
```
|
||||
yarn install
|
||||
```
|
||||
|
||||
1. Build the plugin:
|
||||
|
||||
```
|
||||
yarn dev
|
||||
```
|
||||
|
||||
1. Restart the Grafana server for Grafana to discover your plugin.
|
||||
1. Open Grafana and go to **Configuration** -> **Plugins**. Make sure that your plugin is there.
|
||||
|
||||
By default, Grafana logs whenever it discovers a plugin:
|
||||
|
||||
```
|
||||
INFO[01-01|12:00:00] Registering plugin logger=plugins name=my-plugin
|
||||
```
|
29
docs/sources/shared/tutorials/plugin-anatomy.md
Normal file
29
docs/sources/shared/tutorials/plugin-anatomy.md
Normal file
@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Plugin Anatomy
|
||||
---
|
||||
|
||||
Plugins come in different shapes and sizes. Before we dive deeper, let's look at some of the properties that are shared by all of them.
|
||||
|
||||
Every plugin you create will require at least two files: `plugin.json` and `module.ts`.
|
||||
|
||||
### plugin.json
|
||||
|
||||
When Grafana starts, it scans the plugin directory for any subdirectory that contains a `plugin.json` file. The `plugin.json` file contains information about your plugin, and tells Grafana about what capabilities and dependencies your plugin needs.
|
||||
|
||||
While certain plugin types can have specific configuration options, let's look at the mandatory ones:
|
||||
|
||||
- `type` tells Grafana what type of plugin to expect. Grafana supports three types of plugins: `panel`, `datasource`, and `app`.
|
||||
- `name` is what users will see in the list of plugins. If you're creating a data source, this is typically the name of the database it connects to, such as Prometheus, PostgreSQL, or Stackdriver.
|
||||
- `id` uniquely identifies your plugin, and should start with your Grafana username, to avoid clashing with other plugins. [Sign up for a Grafana account](/signup/) to claim your username.
|
||||
|
||||
To see all the available configuration settings for the `plugin.json`, refer to the [plugin.json Schema](/docs/grafana/latest/plugins/developing/plugin.json/).
|
||||
|
||||
### module.ts
|
||||
|
||||
After discovering your plugin, Grafana loads the `module.ts` file, the entrypoint for your plugin. `module.ts` exposes the implementation of your plugin, which depends on the type of plugin you're building.
|
||||
|
||||
Specifically, `module.ts` needs to expose an object that extends [GrafanaPlugin](https://github.com/grafana/grafana/blob/08bf2a54523526a7f59f7c6a8dafaace79ab87db/packages/grafana-data/src/types/plugin.ts#L124), and can be any of the following:
|
||||
|
||||
- [PanelPlugin](https://github.com/grafana/grafana/blob/08bf2a54523526a7f59f7c6a8dafaace79ab87db/packages/grafana-data/src/types/panel.ts#L73)
|
||||
- [DataSourcePlugin](https://github.com/grafana/grafana/blob/08bf2a54523526a7f59f7c6a8dafaace79ab87db/packages/grafana-data/src/types/datasource.ts#L33)
|
||||
- [AppPlugin](https://github.com/grafana/grafana/blob/45b7de1910819ad0faa7a8aeac2481e675870ad9/packages/grafana-data/src/types/app.ts#L27)
|
77
docs/sources/shared/tutorials/publish-your-plugin.md
Normal file
77
docs/sources/shared/tutorials/publish-your-plugin.md
Normal file
@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Package your plugin
|
||||
---
|
||||
|
||||
Once you're happy with your plugin, it's time to package it, and submit to the plugin repository.
|
||||
|
||||
For users to be able to use the plugin without building it themselves, you need to make a production build of the plugin, and commit to a release branch in your repository.
|
||||
|
||||
To submit a plugin to the plugin repository, you need to create a release of your plugin. While we recommend following the branching strategy outlined below, you're free to use one that makes more sense to you.
|
||||
|
||||
#### Create a plugin release
|
||||
|
||||
Let's create version 0.1.0 of our plugin.
|
||||
|
||||
1. Create a branch called `release-0.1.x`.
|
||||
|
||||
```
|
||||
git checkout -b release-0.1.x
|
||||
```
|
||||
|
||||
1. Do a production build.
|
||||
|
||||
```
|
||||
yarn build
|
||||
```
|
||||
|
||||
1. Add the `dist` directory.
|
||||
|
||||
```
|
||||
git add -f dist
|
||||
```
|
||||
|
||||
1. Create the release commit.
|
||||
|
||||
```
|
||||
git commit -m "Release v0.1.0"
|
||||
```
|
||||
|
||||
1. Create a release tag.
|
||||
|
||||
```
|
||||
git tag -a v0.1.0 -m "Create release tag v0.1.0"
|
||||
```
|
||||
|
||||
1. Push to GitHub. `follow-tags` tells Git to push the release tag along with our release branch.
|
||||
```
|
||||
git push --set-upstream origin release-0.1.x --follow-tags
|
||||
```
|
||||
|
||||
#### Submit the plugin
|
||||
|
||||
For a plugin to be published on [Grafana Plugins](/grafana/plugins/), it needs to be added to the [grafana-plugin-repository](https://github.com/grafana/grafana-plugin-repository).
|
||||
|
||||
1. Fork the [grafana-plugin-repository](https://github.com/grafana/grafana-plugin-repository)
|
||||
|
||||
1. Add your plugin to the `repo.json` file in the project root directory:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "<plugin id>",
|
||||
"type": "<plugin type>",
|
||||
"url": "https://github.com/<username>/my-plugin",
|
||||
"versions": [
|
||||
{
|
||||
"version": "<version>",
|
||||
"commit": "<git sha>",
|
||||
"url": "https://github.com/<username>/my-plugin"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
1. [Create a pull request](https://github.com/grafana/grafana-plugin-repository/pull/new/master).
|
||||
|
||||
Once your plugin has been accepted, it'll be published on [Grafana Plugin](/grafana/plugins/), available for anyone to [install](/docs/grafana/latest/plugins/installation/)!
|
||||
|
||||
> We're auditing every plugin that's added to make sure it's ready to be published. This means that it might take some time before your plugin is accepted. We're working on adding more automated tests to improve this process.
|
34
docs/sources/shared/tutorials/set-up-environment.md
Normal file
34
docs/sources/shared/tutorials/set-up-environment.md
Normal file
@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Set up Environment
|
||||
---
|
||||
|
||||
Before you can get started building plugins, you need to set up your environment for plugin development.
|
||||
|
||||
To discover plugins, Grafana scans a _plugin directory_, the location of which depends on your operating system.
|
||||
|
||||
1. Create a directory called `grafana-plugins` in your preferred workspace.
|
||||
|
||||
1. Find the `plugins` property in the Grafana configuration file and set the `plugins` property to the path of your `grafana-plugins` directory. Refer to the [Grafana configuration documentation](/docs/grafana/latest/installation/configuration/#plugins) for more information.
|
||||
|
||||
```ini
|
||||
[paths]
|
||||
plugins = "/path/to/grafana-plugins"
|
||||
```
|
||||
|
||||
1. Restart Grafana if it's already running, to load the new configuration.
|
||||
|
||||
### Alternative method: Docker
|
||||
|
||||
If you don't want to install Grafana on your local machine, you can use [Docker](https://www.docker.com).
|
||||
|
||||
To set up Grafana for plugin development using Docker, run the following command:
|
||||
|
||||
```
|
||||
docker run -d -p 3000:3000 -v "$(pwd)"/grafana-plugins:/var/lib/grafana/plugins --name=grafana grafana/grafana:7.0.0
|
||||
```
|
||||
|
||||
Since Grafana only loads plugins on start-up, you need to restart the container whenever you add or remove a plugin.
|
||||
|
||||
```
|
||||
docker restart grafana
|
||||
```
|
Reference in New Issue
Block a user