Self-serve Tutorials App

Plugin where self-serve users' tutorials and walkthrough docs live.

Getting started

To have this project running locally, you will need to finish the following:

1. Install all prerequisites.
2. Have grafana-com running locally.
3. Have all your local environment variables set up.
4. Run the commands to start your server and docker.

1. Prerequisites

• Node v.16.13.0 (We recommend using nvm to manage your node version)
• Docker
• Docker Compose latest

2. Setting up Grafana-com

Navigate to grafana-com to have the repository up and running locally.

3. Local set up

1. Install dependencies

   npm install
   

2. Create your local stack token with access policies read/write, which will allow you to create more local tokens.

   scripts/create-local-stack-token
   

   You can confirm that the token exists by visiting the access policies tab here, and check that your token as accesspolicies:read, accesspolicies:write, and accesspolicies:delete

4. Start your plugin

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

   npm run server
   

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

   npm run dev
   

   Login with user admin and password admin locally.

Useful commands

• Run the linter

  npm run lint
  or
  npm run lint:fix
  

• Run prettier

• Run spellcheck

  npm run spellcheck
  

Testing

• Run the tests (using Jest)

  # Runs the tests and watches for changes, requires git init first
  npm run test
  Exits after running all the tests
  npm run test:ci
  

• Run the E2E tests (using Cypress)

  # Spins up a Grafana instance first that we tests against
  npm run server
  Starts the tests
  npm run e2e
  

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.

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 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 app plugin example
• plugin.json documentation
• How to sign a plugin?