Skip to main content

Set up development environment

The create-plugin tool includes a development environment featuring Docker. It allows you to start an instance of the Grafana application for plugin developers against which you can code.

info

It's not necessary to sign a plugin during development. The Docker development environment that is scaffolded with @grafana/create-plugin will load the plugin without a signature. This is because it is configured by default to run in development mode.

Why use the Docker environment​

We have chosen to use Docker because it simplifies the process of creating, deploying, and running applications. It allows you to create consistent and isolated environments for your plugin. This makes it easy to manage dependencies and ensure that the plugin runs the same way across different machines.

With the create-plugin tool, the Docker container is configured with the necessary variables to allow easy access to Grafana and to load plugins without the need for them to be signed. The plugin tool also adds a live reload feature that allows you to make your frontend code changes to trigger refreshes in the browser, and changing the backend code will make the plugin binary to automatically reload.

The docker environment also allows you to attach a debugger to the plugin backend code, making the development process easier.

Get started with Docker​

To start your plugin development project, run the following commands in the order listed:

  1. npm install: Installs frontend dependencies.
  2. npm run dev: Builds and watches the plugin frontend code.
  3. mage -v build:linux: Builds the plugin backend code. Rerun this command every time that you edit your backend files.
  4. npm run server: Starts a Grafana development server running on http://localhost:3000. The plugin will be reloaded on every code change and a debugger can be attached on port 2345.

Configure the Grafana version​

To test a plugin across different versions of Grafana, set an environment variable. Use GRAFANA_VERSION to set the Grafana version:

GRAFANA_VERSION=10.0.0 npm run server

Configure the Grafana image​

The default Docker image in the plugin tool is grafana-enterprise. If you want to override this image, alter the docker-compose.yaml by changing the grafana_image build argument like so:

docker-compose.yaml
version: '3.7'

services:
  grafana:
    container_name: 'myorg-basic-app'
    build:
      context: ./.config
      args:
        grafana_version: ${GRAFANA_VERSION:-9.1.2}
        grafana_image: ${GRAFANA_IMAGE:-grafana}

This example assigns the environment variable GRAFANA_IMAGE to the build arg grafana_image with a default value of grafana. This gives you the option to set the value when running docker-compose commands.

Debugging Backend plugin​

If you're developing a plugin with a backend part, the docker compose file will also expose the port 2345 for debugging, from a headless delve instance running inside the docker environment. You can attach a debugger client to this port to debug your backend code. For example, in VSCode, you can add a launch.json configuration like this:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to plugin backend in docker",
      "type": "go",
      "request": "attach",
      "mode": "remote",
      "port": 2345,
      "host": "127.0.0.1",
      "showLog": true,
      "trace": "log",
      "logOutput": "rpc",
      "substitutePath": [
        {
          "from": "${workspaceFolder}",
          "to": "/root/<your-plugin-id>"
        }
      ]
    }
  ]
}

You can control the go version and the architecure used to build your plugin in the docker compose by setting GO_VERSION and GO_ARCH environment variables:

docker-compose.yaml
version: '3.7'

services:
  grafana:
    container_name: 'myorg-basic-app'
    build:
      context: ./.config
      args:
        GO_VERSION: ${GO_VERSION:-1.22}
        GO_ARCH: ${GO_ARCH:-amd64}

You will also notice that the docker-compose.yaml file also has the following settings:

docker-compose.yaml
    security_opt:
      - "apparmor:unconfined"
      - "seccomp:unconfined"
    cap_add:
      - SYS_PTRACE

they are necessary to allow delve to attach to the running process and debug it and should not be used in production environments.

If you wish to test your plugin in a environment closer to production you can disable the development mode by modifying the docker-compose.yaml:

docker-compose.yaml
version: '3.7'

services:
  grafana:
    container_name: 'myorg-basic-app'
    build:
      context: ./.config
      args:
        development: ${DEVELOPMENT:-true}

Doing that, the docker environment will only run grafana and load the content of your projects dist directory. Thefore before doing that you should build your plugin with mage -v build:backend and npm run server to generate the plugin files. In the example you can also use the DEVELOPMENT environment variable to control the development mode.