Astarte Dashboard

Astarte Dashboard is a web UI that allows visualizing the status of your realm and to perform administrative tasks such as installing interfaces and triggers, managing devices, pipelines and flows.

Table of Contents

• Try it!
• Run it locally
  • Prerequisites
  • Configuration
  • Run it
• Contributing
  • Dependencies
  • Starting up a local server
  • Testing
• License

Try it!

Astarte Dashboard is deployed by default on all Astarte instances.

When deploying locally using docker-compose, visit http://localhost:4040.

On a kubernetes cluster, the URL is specified in the Astarte Voyager Ingress configuration.

Or try out Astarte as a service on Astarte Cloud.

Run it locally

Prerequisites

Before starting you must have:

• Docker version 19.0 or greater.
• An Astarte instance up and running, either locally or on a remote cluster. You can have a look at Astarte in 5 minutes if you haven't already.

Configuration

Astarte Dashboard relies on a configuration file for parameters like the Astarte API URL. As soon as you open Astarte Dashboard, it will search for a file config.json containing the following keys:

• astarte_api_url (required): the base URL of your Astarte API endpoints. This will be used to deduct the endpoints of all Astarte components:

  • AppEngine: api_url + /appengine
  • Realm Management: api_url + /realmmanagement
  • Pairing: api_url + /pairing
  • Flow: api_url + /flow

  The special string localhost sets the enpoints the one ones used in the Astarte in 5 minutes guide

  • AppEngine: http://localhost:4002
  • Realm Management: http://localhost:4000
  • Pairing: http://localhost:4003
  • Flow: http://localhost:4009

  In custom deployments those URLs may change, so you can overwrite any of those with the following optional keys:

  • realm_management_api_url
  • appengine_api_url
  • pairing_api_url
  • flow_api_url

• default_realm (optional): the default realm to login into.

• enable_flow_preview (optional): this requires your Astarte cluster to have Flow configured and running. When enabled (set it to true) the Dashboard will display Flow API status and the related pages such as flows, pipelines and blocks.

• auth (required): the list of auth options available for login.

  Supported authentication methods are direct token or OAuth2 Implicit Grant

  • oauth: following the OAuth standard, Astarte Dashboard will redirect you to your OAuth provider for login. On successful login you'll be redirected back to Astarte Dashboard.

  • token: A token is needed to authenticate against the Astarte API. You can generate one from the realm private key using astartectl.

  If multiple auth options are enabled, the user may use either one.

• default_auth (required): the default auth option to display when attempting login.

An example config would look like this:

{
  "astarte_api_url": "https://api.example.com",
  "enable_flow_preview": true,
  "default_realm": "myrealm",
  "default_auth": "token",
  "auth": [
    {
      "type": "token"
    },
    {
      "type": "oauth",
      "oauth_api_url": "https://auth.example.com"
    }
  ]
}

Run it

You can easily run the Astarte Dashboard using the official Docker images from the public Dockerhub registry.

For example, to run it locally on port 4040, you can use the following command:

docker run \
  -p 4040:80 \
  -v /absolute/path/to/config.json:/usr/share/nginx/html/user-config/config.json \
  astarte/astarte-dashboard:snapshot

Contributing

Dependencies

Astarte Dashboard is written in TypeScript using the React framework and npm to manage dependencies.

• node (10 or greater)
• npm (6 or greater)

Starting up a local server

1. Clone this repo locally

   git clone [email protected]:astarte-platform/astarte-dashboard.git && cd astarte-dashboard
   

2. Install the project dependencies

   npm install
   

3. Place your configuration file in src/user-config/config.json
4. Start the dev server

   npm run start
   

5. Open the browser at the displayed URL, usually http://localhost:8080

Testing

Tests are carried out using Cypress, which in turn uses a headless browser to simulate user interactions. So before testing, a server from which the browser can access Astarte Dashboard is needed. The command start-ci serves the purpose.

npm run start-ci

Once the server is up, you can run tests in the CLI by running the command test

npm run test

But if you want to test specific pages or components, you can open the Cypress GUI with

npm run cypress:open

Other routine tests are formatting and typescript checks

 npm run check-format
 npm run check-types

License

Distributed under the Apache2.0 License. See LICENSE for more information.