Feedback, break up env docs

urbiz-grafana · urbiz-grafana · commit b42c10f53712 · 2025-09-02T06:59:34.000+02:00
diff --git a/docusaurus/docs/e2e-test-a-plugin/authentication.md b/docusaurus/docs/e2e-test-a-plugin/authentication.md
@@ -97,7 +97,7 @@ export default defineConfig<PluginOptions>({
 
 ## Managing users
 
-When a `user` is defined in a setup project (like in the RBAC example above) `plugin-e2e` will use the Grafana HTTP API to create the user account. This action requires elevated permissions, so by default the server administrator credentials `admin:admin` will be used. If the end-to-end tests are targeting the [development environment](../set-up-development-environment.md) scaffolded with `create-plugin`, this will work fine. However for other test environments the server administrator password may be different. In that case, we search for GRAFANA_ADMIN_USER and GRAFANA_ADMIN_PASSWORD environment variables. Additionally you can provide the correct credentials by setting `grafanaAPICredentials` in the global options.
+When a `user` is defined in a setup project (like in the RBAC example above) `plugin-e2e` will use the Grafana HTTP API to create the user account. This action requires elevated permissions, so by default the server administrator credentials `admin:admin` will be used. If the end-to-end tests are targeting the [development environment](../set-up/set-up-development-environment.md) scaffolded with `create-plugin`, this will work fine. However for other test environments the server administrator password may be different. In that case, we search for GRAFANA_ADMIN_USER and GRAFANA_ADMIN_PASSWORD environment variables. Additionally you can provide the correct credentials by setting `grafanaAPICredentials` in the global options.
 
 ```ts title="playwright.config.ts"
 import { dirname } from 'path';
diff --git a/docusaurus/docs/get-started.md b/docusaurus/docs/get-started.md
@@ -44,9 +44,11 @@ If this is your first time creating a plugin, we recommend that you familiarize
 
 :::
 
-## Classifications of Grafana plugins
+## Signature classifications of Grafana plugins
 
-We recommend that you familiarize yourself with the signature classifications of Grafana plugins, such as the distinction between private and public plugins. Note that if you want to publish a plugin which is associated with a commercial offering to the official Grafana catalog, a paid subscription is typically required. Learn more about [our plugins policy](https://grafana.com/legal/plugins/).
+Familiarize yourself with the signature classifications of Grafana plugins, such as the distinction between private and public plugins. 
+
+Note that if you want to publish a plugin associated with a commercial offering to the official Grafana catalog, a paid subscription is typically required. Learn more about [our plugins policy](https://grafana.com/legal/plugins/).
 
 ## Use plugin tools to develop your plugins faster
 
@@ -155,7 +157,7 @@ For more information about these files, refer to [Anatomy of a plugin](/key-conc
 
 ## Build and run your plugin in Docker
 
-With the `create-plugin` tool, you can use a Docker container to simplify the configuration, loading, and development processes. For more information, refer to [Set up development environment](/set-up-development-environment/).
+With the `create-plugin` tool, you can use a Docker container to simplify the configuration, loading, and development processes. For more information, refer to [Set up development environment](/set-up/set-up-development-environment/).
 
 Refer to the "Next steps" terminal output following the [scaffolding of a new plugin](#scaffold-a-plugin) to install dependencies, build and run your plugin.
 
@@ -186,7 +188,7 @@ Note: We strongly recommend creating a new Git repository by running git init in
 
 ### Build the frontend
 
-To build the plugin in watch mode for development, continually monitoring for changes, run:
+To build the plugin in watch mode for development and continually monitor for changes, run:
 
 <BuildFEDevNPM />
 
diff --git a/docusaurus/docs/how-to-guides/app-plugins/include-dashboards-in-app-plugins.md b/docusaurus/docs/how-to-guides/app-plugins/include-dashboards-in-app-plugins.md
@@ -19,7 +19,7 @@ We'll walk you through the process of bundling dashboards into plugins. The proc
 
 ## Step 1: Create a dashboard
 
-Start by creating the dashboard you want to bundle with your plugin. The [development environment](/set-up-development-environment) provided by create-plugin can aid with creating and testing dashboards.
+Start by creating the dashboard you want to bundle with your plugin. The [development environment](/set-up/set-up-development-environment) provided by create-plugin can aid with creating and testing dashboards.
 
 ### Set up a data source variable
 
diff --git a/docusaurus/docs/how-to-guides/data-source-plugins/include-dashboards.md b/docusaurus/docs/how-to-guides/data-source-plugins/include-dashboards.md
@@ -16,7 +16,7 @@ We'll walk you through the process of bundling dashboards into plugins. The proc
 
 ## Step 1: Create a dashboard
 
-Start by creating the dashboard you want to bundle with your plugin. The [development environment](/set-up-development-environment) provided by create-plugin can aid with creating and testing dashboards.
+Start by creating the dashboard you want to bundle with your plugin. The [development environment](/set-up/set-up-development-environment) provided by create-plugin can aid with creating and testing dashboards.
 
 ### Export the dashboard
 
diff --git a/docusaurus/docs/how-to-guides/plugin-internationalization.md b/docusaurus/docs/how-to-guides/plugin-internationalization.md
@@ -282,6 +282,6 @@ The translation file will look similar to this:
 
 ## Test the translated plugin
 
-To test the plugin follow the steps in [Set up your development environment](../set-up-development-environment#docker-development-environment) to run your plugin locally.
+To test the plugin follow the steps in [Set up your development environment](../set-up/set-up-d) to run your plugin locally.
 
 You can then verify your plugin is displaying the appropriate text as you [change the language](https://grafana.com/docs/grafana/latest/administration/organization-preferences/#change-grafana-language).
diff --git a/docusaurus/docs/key-concepts/best-practices.md b/docusaurus/docs/key-concepts/best-practices.md
@@ -79,7 +79,7 @@ Is something missing from this list? [Let us know](https://github.com/grafana/pl
 ## Publish a plugin
 
 - **Add a GitHub badge** - Follow [these steps](https://grafana.com/blog/2024/06/06/6-tips-to-improve-your-grafana-plugin-before-you-publish/#tip-4-add-dynamic-badges-to-your-readme) to help users find your plugin using GitHub badges.
-- **Add workflow automation** - If your plugin is available on GitHub, consider [adding the GitHub workflows](../set-up-development-environment.md#set-up-github-workflows) for plugin development to your repository.
+- **Add workflow automation** - If your plugin is available on GitHub, consider [adding the GitHub workflows](../set-up/set-up-github) for plugin development to your repository.
 
 ## Manage plugin compatibility
 
diff --git a/docusaurus/docs/key-concepts/manage-npm-dependencies.md b/docusaurus/docs/key-concepts/manage-npm-dependencies.md
@@ -26,7 +26,7 @@ However, when the plugin is installed and executed within a Grafana instance, it
 
 :::info
 
-This dynamic dependency linking also applies to the [docker development environment](/set-up-development-environment) provided by create-plugin. When the plugin is running inside Grafana it will inherit the version of the `@grafana` dependencies from the Grafana application.
+This dynamic dependency linking also applies to the [docker development environment](/set-up/set-up-development-environment) provided by create-plugin. When the plugin is running inside Grafana it will inherit the version of the `@grafana` dependencies from the Grafana application.
 
 :::
 
diff --git a/docusaurus/docs/publish-a-plugin/build-automation.md b/docusaurus/docs/publish-a-plugin/build-automation.md
@@ -15,7 +15,7 @@ keywords:
 
 # Automate packaging and signing with GitHub CI
 
-We recommend setting up your plugin to use the supplied [Github workflows](../set-up-development-environment.md#set-up-github-workflows) from [create-plugin](../get-started.md)
+We recommend setting up your plugin to use the supplied [Github workflows](../set-up/set-up-github) from [create-plugin](../get-started.md)
 to ensure that your plugin will be built and packaged in the correct format.
 
 Additionally, we recommend using the zip file produced from this workflow to test the plugin.
diff --git a/docusaurus/docs/publish-a-plugin/provide-test-environment.md b/docusaurus/docs/publish-a-plugin/provide-test-environment.md
@@ -22,7 +22,7 @@ Developers often ask us how long it takes for a plugin to be reviewed for publis
 
 By far the most time consuming aspect of a plugin's review is the creation of a suitable test environment so we can verify its behavior. This step often involves a number of back-and-forth conversations between the plugin developer and the review team.
 
-To improve the review time, add [_provisioning_](https://grafana.com/docs/grafana/latest/administration/provisioning/#provision-grafana) to your plugin. Provisioning refers to the process of preparing and configuring a test environment within the plugin's [Docker development environment](/set-up-development-environment).
+To improve the review time, add [_provisioning_](https://grafana.com/docs/grafana/latest/administration/provisioning/#provision-grafana) to your plugin. Provisioning refers to the process of preparing and configuring a test environment within the plugin's [Docker development environment](/set-up/set-up-development-environment).
 
 ## Why provisioning test environments?
 
diff --git a/docusaurus/docs/publish-a-plugin/sign-a-plugin.md b/docusaurus/docs/publish-a-plugin/sign-a-plugin.md
@@ -17,7 +17,7 @@ All Grafana Labs-authored plugins, including Enterprise plugins, are signed so t
 
 :::info
 
-You don't need to sign a plugin during development or when submitting a plugin for review for the first time. The [Docker development environment](../set-up-development-environment.md) that is scaffolded with `@grafana/create-plugin` is configured by default to run in [development mode](https://github.com/grafana/grafana/blob/main/contribute/developer-guide.md#configure-grafana-for-development), which allows you to load the plugin without a signature.
+You don't need to sign a plugin during development or when submitting a plugin for review for the first time. The [Docker development environment](../set-up/set-up-development-environment.md) that is scaffolded with `@grafana/create-plugin` is configured by default to run in [development mode](https://github.com/grafana/grafana/blob/main/contribute/developer-guide.md#configure-grafana-for-development), which allows you to load the plugin without a signature.
 
 :::
 
diff --git a/docusaurus/docs/set-up/index.md b/docusaurus/docs/set-up/index.md
@@ -0,0 +1,25 @@
+---
+id: set-up-development-environment
+title: Set up your development environment
+description: Set up your development environment for Grafana plugin development.
+keywords:
+  - grafana
+  - plugins
+  - plugin
+  - create-plugin
+  - Docker
+  - GitHub
+  - setup
+  - CI
+  - continuous integration
+  - automation
+  - configuration
+---
+
+These guides walk you through setting up your development environment for Grafana plugin development. Including:
+
+- Running a development Grafana server with your plugin installed using Docker
+- Setting up GitHub workflows to automate your development and release process
+- Extending configurations for ESLint, Prettier, Jest, TypeScript, and Webpack
+
+<DocLinkList />
diff --git a/docusaurus/docs/set-up/set-up-docker.md b/docusaurus/docs/set-up/set-up-docker.md
@@ -0,0 +1,102 @@
+---
+id: set-up-development-environment
+title: Set up your Docker development environment
+description: Set up your Docker development environment with Docker for Grafana plugin development.
+  - grafana
+  - plugins
+  - plugin
+  - create-plugin
+  - Docker
+  - setup
+  - CI
+  - continuous integration
+  - automation
+  - configuration
+sidebar_position: 20
+---
+
+import DockerNPM from '@shared/docker-grafana-version.md';
+
+The [`create-plugin` tool](/get-started.md#use-plugin-tools-to-develop-your-plugins-faster) includes a development environment featuring [Docker](https://docs.docker.com/get-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](/publish-a-plugin/sign-a-plugin.md) 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](https://github.com/grafana/grafana/blob/main/contribute/developer-guide.md#configure-grafana-for-development).
+
+:::
+
+## 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. <SyncCommand cmd="install" />: Installs frontend dependencies.
+1. <SyncCommand cmd="run dev" />: Builds and watches the plugin frontend code.
+1. `mage -v build:linux`: Builds the plugin backend code. Rerun this command every time that you edit your backend files.
+1. <SyncCommand cmd="run server" />: Starts a Grafana development server running on
+   [http://localhost:3000](http://localhost:3000).
+
+## 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:
+
+<DockerNPM />
+
+## 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:
+
+```yaml title="docker-compose.yaml"
+version: '3.7'
+
+services:
+  grafana:
+    extends:
+      file: .config/docker-compose-base.yaml
+      service: grafana
+    build:
+      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 a plugin's backend
+
+If you're developing a plugin with a backend part, run `npm run server` with `DEVELOPMENT=true`. The docker compose file exposes the port `2345` for debugging, from a headless delve instance that will run 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:
+
+```json
+{
+  "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>"
+        }
+      ]
+    }
+  ]
+}
+```
+
diff --git a/docusaurus/docs/set-up/set-up-github.md b/docusaurus/docs/set-up/set-up-github.md
diff --git a/docusaurus/website/sidebars.ts b/docusaurus/website/sidebars.ts
diff --git a/docusaurus/website/websiteRedirects.json b/docusaurus/website/websiteRedirects.json
diff --git a/packages/plugin-e2e/README.md b/packages/plugin-e2e/README.md
