Updating docs

* Overhauled README * Provide copy-pasteable examples for deployment * Fix tooltip for query editor
meln5674 · Jan 28, 2023 · 25f142d · 25f142d
1 parent 018801c
commit 25f142d
Show file tree

Hide file tree

Showing 2 changed files with 91 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -4,64 +4,126 @@ This Open Source Grafana plugin allows for querying a MongoDB database or cluste
 
 # This plugin is still in early development, and experimental. Everything is subject to change. Use at your own risk. Help Wanted.
 
-## Building
 
-Tools Needed:
-* Node.js 14+
-* Golang 1.17+
-* Yarn
-* Mage
+## Installation
 
-If you have Docker installed you can use `./build-env.sh` to build and run a shell in a container with all necessary tools (or `build-env.Dockerfile` to build it yourself manually).
 
-```bash
-yarn install
-yarn build
-yarn backend
-```
+This plugin is not currently signed. To install it, you have two options: Sign it yourself, or whitelist it as an unsigned plugin.
 
-## Installation
-
-See `integration-tests` directory for configuration examples.
+### Signed
 
-### Production
+This is recommended for production environments.
 
-Run
+To sign the plugin, build the plugin from source as described below, then execute
 
 ```bash
+export GRAFANA_API_KEY=<See https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#generate-an-api-key>
 yarn plugin
+yarn sign -- --rootUrls=<your grafana URL>
 ```
 
-Then copy the produced `meln5674-mongodb-community.zip` file to your artifact repository (e.g. Nexus) or web server (.e.g Nginx) of choice.
+Then copy the produced `meln5674-mongodb-community.zip` file to your artifact repository (e.g. Nexus) or web server (.e.g Nginx) of choice, and note the URL to download the zip.
+
+### Unsigned
 
-#### Bare Metal
+To install the plugin as unsigned, choose a version from the [Releases Page](https://github.com/meln5674/grafana-mongodb-community-plugin/releases), and either download the ZIP file, or copy its URL.
 
-Run
+### Bare Metal
+
+On your grafana server, run
 
 ```bash
-grafana-cli --pluginUrl <your repository url>/meln5674-mongodb-community.zip meln5674-mongodb-community
+grafana-cli --pluginUrl ${ZIP_URL} meln5674-mongodb-community
 ```
 
-on your grafana host.
+then, if using the plugin unsigned, add the following to your `grafana.ini` file:
+
+```ini
+[plugins]
+allow_loading_unsigned_plugins=meln5674-mongodb-community
+```
 
 #### Docker
 
 Set the environment variable
 
+```bash
+GF_INSTALL_PLUGINS=${ZIP_URL}
 ```
-GF_INSTALL_PLUGINS=meln5674-mongodb-community=<your repository url>/meln5674-mongodb-community.zip
+
+as well as the following, if using the plugin unsigned
+```bash
+GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=meln5674-mongodb-community
 ```
 
-#### Kubernetes
+e.g.
 
-Consult your grafana distribution documentation (e.g. https://github.com/bitnami/charts/tree/master/bitnami/grafana) for how to specify plugins to install
+```bash
+PLUGIN_VERSION=<See https://github.com/meln5674/grafana-mongodb-community-plugin/releases>
+docker run \
+    -d \
+    -p 3000:3000 \
+    -e GF_INSTALL_PLUGINS=meln5674-mongodb-community=https://github.com/meln5674/grafana-mongodb-community-plugin/releases/download/${PLUGIN_VERSION}/meln5674-mongodb-community.zip \
+    -e GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=meln5674-mongodb-community \
+    bitnami/grafana:latest
+```
 
+#### Kubernetes
+
+Consult your grafana distribution documentation (e.g. https://github.com/bitnami/charts/tree/master/bitnami/grafana) for how to specify plugins to install.
+
+For a simple deployment, set the following
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: grafana
+spec:
+  selector:
+    matchLabels:
+      app: grafana
+  template:
+    metadata:
+      labels:
+        app: grafana
+    spec:
+      restartPolicy: Always
+      containers:
+      - name: grafana
+        image: bitnami/grafana:latest
+        env:
+        - name: PLUGIN_VERSION
+          value: <See https://github.com/meln5674/grafana-mongodb-community-plugin/releases>
+        - name: GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS
+          value: meln5674-mongodb-community
+        - name: GF_INSTALL_PLUGINS
+          value: meln5674-mongodb-community=https://github.com/meln5674/grafana-mongodb-community-plugin/releases/download/$(PLUGIN_VERSION)/meln5674-mongodb-community.zip
+```
 
 ### Development
 
-Copy built repository to `<grafana plugins dir>/meln5674-mongodb-community`
+#### Building
+
+Tools Needed:
+* Node.js 14+
+* Golang 1.17+
+* Yarn
+* Mage
+
+If you have Docker, installed you can use `./build-env.sh` to build and run a shell in a container with all necessary tools (or `build-env.Dockerfile` to build it yourself manually). You can also execute `./build-env.sh <command>` to execute a single command, batch-style, in this container.
+
+To build, run
+
+```bash
+yarn install
+yarn build
+yarn backend
+```
+
+then to install into a development environment, copy built repository to `<grafana plugins dir>/meln5674-mongodb-community`
 
-## Integration Tests
+#### Integration Tests
 
 Tools Needed:
 * Docker
@@ -73,7 +135,7 @@ Tools Needed:
 yarn integration-test
 ```
 
-## Live Development Environment
+#### Live Development Environment
 
 ```bash
 export KUBECONFIG=integration-test/kubeconfig

diff --git a/src/QueryEditor.tsx b/src/QueryEditor.tsx
@@ -278,7 +278,7 @@ export class QueryEditor extends PureComponent<Props> {
               <InlineField
                     labelWidth={this.labelWidth}
                     label="Legend Format"
-                    tooltip="Series name override. Replacements are:\n{{.Value}}: Value field name.\n{{.Labels.field_name}}: Value of the label with name 'field_name'\n{{.Labels}}: key=value,... for all labels\nSee https://pkg.go.dev/text/template for full syntax.\nFunctions from https://masterminds.github.io/sprig/ are provided"
+                    tooltip={"Series name override. Replacements are:\n{{.Value}}: Value field name.\n{{.Labels.field_name}}: Value of the label with name 'field_name'\n{{.Labels}}: key=value,... for all labels\nSee https://pkg.go.dev/text/template for full syntax.\nFunctions from https://masterminds.github.io/sprig/ are provided"}
               >
                 <Input
                   value={query.legendFormat || ""}