Skip to content

Commit

Permalink
flow panel buildout
Browse files Browse the repository at this point in the history
  • Loading branch information
@andymchugh
andymchugh committed Jan 23, 2024
1 parent 9056a4a commit 6047a3e
Show file tree
Hide file tree
Showing 22 changed files with 22,111 additions and 229 deletions.
5 changes: 5 additions & 0 deletions .config/types/custom.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ declare module '*.svg' {
export default content;
}

declare module '*.yaml' {
const content: string;
export default content;
}

// Font declarations
declare module '*.woff';
declare module '*.woff2';
Expand Down
118 changes: 8 additions & 110 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,114 +1,12 @@
# Grafana panel plugin template
# Grafana Flow Panel Plugin
The plugin was created from this [grafana template](https://grafana.com/developers/plugin-tools/tutorials/build-a-panel-plugin). It provides side-by-side metric visualization on SVG diagrams. You provide the SVG diagram along with configuration on how you want the diagram to behave. The panel then combines these with your time-series data to bring your diagram to life.

This template is a starting point for building a panel plugin for Grafana.
![example1](src/img/example1.png)

## What are Grafana panel plugins?
![example2](src/img/example2.png)

Panel plugins allow you to add new types of visualizations to your dashboard, such as maps, clocks, pie charts, lists, and more.
## Getting started with creating panels
Go to the [documentation](https://github.com/andymchugh/andrewbmchugh-flow-panel-docs/blob/main/README.md) repository for full details on how to use the panel.

Use panel plugins when you want to do things like visualize data returned by data source queries, navigate between dashboards, or control external systems (such as smart home devices).

## Getting started

### Frontend

1. Install dependencies

```bash
npm install
```

2. Build plugin in development mode and run in watch mode

```bash
npm run dev
```

3. Build plugin in production mode

```bash
npm run build
```

4. Run the tests (using Jest)

```bash
# Runs the tests and watches for changes, requires git init first
npm run test

# Exits after running all the tests
npm run test:ci
```

5. Spin up a Grafana instance and run the plugin inside it (using Docker)

```bash
npm run server
```

6. Run the E2E tests (using Cypress)

```bash
# Spins up a Grafana instance first that we tests against
npm run server

# Starts the tests
npm run e2e
```

7. Run the linter

```bash
npm run lint

# or

npm run lint:fix
```

# Distributing your plugin

When distributing a Grafana plugin either within the community or privately the plugin must be signed so the Grafana application can verify its authenticity. This can be done with the `@grafana/sign-plugin` package.

_Note: It's not necessary to sign a plugin during development. The docker development environment that is scaffolded with `@grafana/create-plugin` caters for running the plugin without a signature._

## Initial steps

Before signing a plugin please read the Grafana [plugin publishing and signing criteria](https://grafana.com/legal/plugins/#plugin-publishing-and-signing-criteria) documentation carefully.

`@grafana/create-plugin` has added the necessary commands and workflows to make signing and distributing a plugin via the grafana plugins catalog as straightforward as possible.

Before signing a plugin for the first time please consult the Grafana [plugin signature levels](https://grafana.com/legal/plugins/#what-are-the-different-classifications-of-plugins) documentation to understand the differences between the types of signature level.

1. Create a [Grafana Cloud account](https://grafana.com/signup).
2. Make sure that the first part of the plugin ID matches the slug of your Grafana Cloud account.
- _You can find the plugin ID in the `plugin.json` file inside your plugin directory. For example, if your account slug is `acmecorp`, you need to prefix the plugin ID with `acmecorp-`._
3. Create a Grafana Cloud API key with the `PluginPublisher` role.
4. Keep a record of this API key as it will be required for signing a plugin

## Signing a plugin

### Using Github actions release workflow

If the plugin is using the github actions supplied with `@grafana/create-plugin` signing a plugin is included out of the box. The [release workflow](./.github/workflows/release.yml) can prepare everything to make submitting your plugin to Grafana as easy as possible. Before being able to sign the plugin however a secret needs adding to the Github repository.

1. Please navigate to "settings > secrets > actions" within your repo to create secrets.
2. Click "New repository secret"
3. Name the secret "GRAFANA_API_KEY"
4. Paste your Grafana Cloud API key in the Secret field
5. Click "Add secret"

#### Push a version tag

To trigger the workflow we need to push a version tag to github. This can be achieved with the following steps:

1. Run `npm version <major|minor|patch>`
2. Run `git push origin main --follow-tags`

## Learn more

Below you can find source code for existing app plugins and other related documentation.

- [Basic panel plugin example](https://github.com/grafana/grafana-plugin-examples/tree/master/examples/panel-basic#readme)
- [`plugin.json` documentation](https://grafana.com/developers/plugin-tools/reference-plugin-json)
- [How to sign a plugin?](https://grafana.com/developers/plugin-tools/publish-a-plugin/sign-a-plugin)
## Getting started with addng new features
Go to the [Getting Started](./grafana-getting-started.md) guide to get going with adding changes on your fork.
108 changes: 108 additions & 0 deletions grafana-getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# Getting started with Development

## Frontend

1. Install dependencies

```bash
npm install
```

2. Build plugin in development mode and run in watch mode

```bash
npm run dev

docker compose up

http://localhost:3000/?orgId=1
```

3. Build plugin in production mode

```bash
npm run build
```

4. Run the tests (using Jest)

```bash
# Runs the tests and watches for changes, requires git init first
npm run test

# Exits after running all the tests
npm run test:ci
```

5. Spin up a Grafana instance and run the plugin inside it (using Docker)

```bash
npm run server
```

6. Run the E2E tests (using Cypress)

```bash
# Spins up a Grafana instance first that we tests against
npm run server

# Starts the tests
npm run e2e
```

7. Run the linter

```bash
npm run lint

# or

npm run lint:fix
```

## Distributing your plugin

When distributing a Grafana plugin either within the community or privately the plugin must be signed so the Grafana application can verify its authenticity. This can be done with the `@grafana/sign-plugin` package.

_Note: It's not necessary to sign a plugin during development. The docker development environment that is scaffolded with `@grafana/create-plugin` caters for running the plugin without a signature._

### Initial steps

Before signing a plugin please read the Grafana [plugin publishing and signing criteria](https://grafana.com/legal/plugins/#plugin-publishing-and-signing-criteria) documentation carefully.

`@grafana/create-plugin` has added the necessary commands and workflows to make signing and distributing a plugin via the grafana plugins catalog as straightforward as possible.

Before signing a plugin for the first time please consult the Grafana [plugin signature levels](https://grafana.com/legal/plugins/#what-are-the-different-classifications-of-plugins) documentation to understand the differences between the types of signature level.

1. Create a [Grafana Cloud account](https://grafana.com/signup).
2. Make sure that the first part of the plugin ID matches the slug of your Grafana Cloud account.
- _You can find the plugin ID in the `plugin.json` file inside your plugin directory. For example, if your account slug is `acmecorp`, you need to prefix the plugin ID with `acmecorp-`._
3. Create a Grafana Cloud API key with the `PluginPublisher` role.
4. Keep a record of this API key as it will be required for signing a plugin

### Signing a plugin

#### Using Github actions release workflow

If the plugin is using the github actions supplied with `@grafana/create-plugin` signing a plugin is included out of the box. The [release workflow](./.github/workflows/release.yml) can prepare everything to make submitting your plugin to Grafana as easy as possible. Before being able to sign the plugin however a secret needs adding to the Github repository.

1. Please navigate to "settings > secrets > actions" within your repo to create secrets.
2. Click "New repository secret"
3. Name the secret "GRAFANA_API_KEY"
4. Paste your Grafana Cloud API key in the Secret field
5. Click "Add secret"

##### Push a version tag

To trigger the workflow we need to push a version tag to github. This can be achieved with the following steps:

1. Run `npm version <major|minor|patch>`
2. Run `git push origin main --follow-tags`

### Learn more

Below you can find source code for existing app plugins and other related documentation.

- [Basic panel plugin example](https://github.com/grafana/grafana-plugin-examples/tree/master/examples/panel-basic#readme)
- [`plugin.json` documentation](https://grafana.com/developers/plugin-tools/reference-plugin-json)
- [How to sign a plugin?](https://grafana.com/developers/plugin-tools/publish-a-plugin/sign-a-plugin)
Loading

0 comments on commit 6047a3e

Please sign in to comment.