CONTRIBUTING.md

Developer Guide

How to build the Sitewise data source plugin locally

Dependencies

Make sure you have the following dependencies installed first:

• Git
• Go (see go.mod for minimum required version)
• Mage
• Node.js (Long Term Support)
• Yarn

Frontend

1. Install dependencies

yarn install

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

yarn dev

3. Build plugin in production mode

yarn build

4. Run tests

yarn test

Backend

1. Build backend for all platforms

mage buildAll

2. Run tests

mage test

Local Grafana development setup

Instructions to install grafana server locally can be found, here:

• Grafana Server

To install the plugin locally, copy the built plugin to the Grafana plugin directory (usually: /var/lib/grafana/plugins)

• https://grafana.com/docs/grafana/latest/plugins/installation/

Docker development setup

1. Create AWS credentials file:

cat << EOF >> ~/.aws/credentials
[DEFAULT]

[default]
aws_access_key_id=<your aws access key id>
aws_secret_access_key=<your aws secret access key>
EOF

See https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html for more details on configuring the credentials file.

2. Start Grafana docker

cd /Workspace/iot-sitewise-datasource
yarn server:dev

Starting the docker image with yarn server:dev will automatically rebuild and reload the plugin whenever changes are made.

Access from http://localhost:3000.

If you run yarn server:dev with ANONYMOUS_AUTH_ENABLED=false the first time login will be user:admin password:admin.

Build a release

You need to have commit rights to the GitHub repository to publish a release.

1. Update the version number in the package.json file.
2. Update the CHANGELOG.md by copy and pasting the relevant PRs from Github's Release drafter interface or by running yarn generate-release-notes (you'll need to install the gh cli and jq to run this command).
3. PR the changes.
4. Once merged, follow the Drone release process that you can find here

E2E Tests

This plugin uses playwright and @grafana/plugin-e2e for e2e end tests.

To get the best fidelity, we make live requests to AWS for many of our e2e tests. In order to run them you will need to create an AWS User and secret/access keys and add them in either as env variables (AWS_ACCESS_KEY and AWS_SECRET_KEY) which is how we run our tests in CI or add a yaml file to the provisioning repo like so:

apiVersion: 1

deleteDatasources:
  - name: sitewise
    orgId: 1

datasources:
  - name: sitewise
    type: grafana-iot-sitewise-datasource
    editable: true
    jsonData:
      authType: keys
      defaultRegion: us-east-1
    secureJsonData:
      accessKey: {your access key here}
      secretKey: {your secret key here}

Running e2e tests locally

To run e2e tests locally:

yarn run e2e

This will then print out a report that can be viewed. Or To run e2e tests locally with UI mode for easier debugging:

yarn run e2e:debug

You may also wish to enable "traces" in the playwright.config.ts file which will show screenshots of failures and network requests.