dashboard

The web UI component of the AuRa framework

Setup

Prerequisites

This version is an early development prototype.

Detailed setup infos will follow, as soon as we reach something between alpha and beta stage.

For dashboard to run locally or to deploy it to some web space, you need Node.js and the Node Package Manager (npm), which comes with Node.js. You have different download options for Node.js depending on your operating system. You need at least Node.js v10.

Configuration

All global configuration settings of the dashboard application can be set in the corresponding .env.* files. You can use different settings for a development and a production environment. So for a production environment you will have to set all values in .env.production. For development use .env.development. For more infos on environment variables, also for test and staging modes, see Vue CLI 3: Environment Variables and Modes

This repository already provides sample environments in the files sample.env.development and sample.env.production, so you can copy them to .env.development and .env.production depending on wheter you want to set up a dev or prod environment.

All needed values are provided with comments in the sample.env.production file, so you can just take a look there and create your copy for the development environment. There are some important notes on what to set and what to not forget. For developers: Also be aware that these settings become environment variables once compiled by Vue.js, so hot reload does not work, when you change them. You have to compile the app again for changes to take effect.

For the OpenID Connect settings it is very important to use exactly the same redirect URIs as defined in you OIDC client settings in the aura/steering module. So VUE_APP_API_STEERING_OIDC_REDIRECT_URI and VUE_APP_API_STEERING_OIDC_REDIRECT_URI_SILENT should ideally be a copy-paste from there.

Running it locally (dev environment)

After you have set up the environment you just need to do the following:

## Project setup
npm install

### Compiles and hot-reloads for development
npm run serve

For customizing the whole vue cli development environment, see Configuration Reference.

Setting it up on a server (production environment)

Before building the final client code, you have to copy the sample.env.production file to .env.production and change the values to your final setup, as described in the Configuration section above.

Similar to the dev environment you first have to install all dependencies by npm install. Then you can build the production code, use npm run build. This compiles and minifies the code for production. Then you just have to put the contents of the dist folder on some web space. From a web server's perspective this is just static code, so nothing special is needed except a plain web server (using HTTPS with Let's Encrypt or any other TLS certificates is highly recommended).

TODO: provide an example setup

Common problems and solutions

Access to steering is denied due to CORS issues

For the dashboard to run in a dev mode you only need the npm install and npm run dev commands. To access show data in the show manager you also have to have the steering module running somewhere. There you need to add the following lines to the pv/local_settings.py, in order to allow CORS requests from your dashboard:

CORS_ALLOW_CREDENTIALS = True
CORS_ORIGIN_WHITELIST = (
	'localhost:8080'
)

This assumes of course that you have the dashboard running on its standard localhost port 8080. If you want to change this to e.g. port 9090, add a line PORT: 9090, to the .env.development file of the dashboard package.

Authentication is not working due to redirect issues

Dashboard can only be used with working authentication against the OIDC provider, which is AuRa steering. Therefore you have to set up an OpenID Connect client there first. Additionally you will also need a separate client for tank.

The standard setup for the dashboard client should use these values:

• Client Type: Public
• Response Type: id_token token (Implicit Flow)
• JWT Algorithm: RS256
• Require Consent?: No
• Reuse Consent?: Yes

You also have to set the Redirect URIs, which have to match exactly the ones you configure in your .env.development or .env.production files here in the dashboard source. This also means that if you use localhost in steering, you must not put 127.0.0.1 or any aquivalent in your dashboard config, but use exactly the same string (and vice versa).

So if for example the Redirect URIs in the steering OIDC client are set to:

http://localhost:8080/static/oidc_callback.html
http://localhost:8080/static/oidc_callback_silentRenew.html

Then your .env.development (assuming this a dev environment) should contain:

VUE_APP_API_STEERING_OIDC_REDIRECT_URI = http://localhost:8080/oidc_callback.html
VUE_APP_API_STEERING_OIDC_REDIRECT_URI_SILENT = http://localhost:8080/oidc_callback_silentRenew.html

Infos on build environment

This project is built with Vue.js 2. Take a look at their Guide or the API docs to find out more about the core framework. As template we are using the webpack template. For a detailed explanation on how things work with this, check out the webpack guide and docs for vue-loader. For the whole einvornment setup we started out with Vue CLI 2 but now work with Vue CLI 3.

Webpack also comes with code linting, using ESLint, which makes our code consistent, functional and less error-prone. For infos on how the routes work, take a look at the vue-router.

And if you want to dig into a lot of useful awesome stuff that was already coded by others and which can be easily integrated into this project, go to the vue-aweseome repo.