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 webspace, 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 v14.
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 whether 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.
For further information, check out the detailed documentation on OIDC configuration.
Running it locally (development environment)
After you have set up the environment you first need to install the required packages:
npm install
And start the development server:
./run.sh
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 webspace. 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
Building/running with Docker
You can use Docker either to run the local development server, if you do not want to set up node/npm on your host, or you can use Docker to just build the dist directory, that you then use in your dashboard's web root.
Before you build any image and run containers, make sure you followed the steps above in the Configuration section.
To create the image for the dev container and run it use the following:
docker build -t dashboard-dev --target=dev .
docker run --rm -it -v $(pwd):/aura -p 8080:8080 dashboard-dev
To use the build image to build the dist directory do the following:
docker build -t dashboard --target=prod .
docker run --rm -it -v "$(pwd)"/dist_docker:/aura/dist_docker dashboard \
sh -c 'npm run build && mv dist/* dist_docker'
In this case the final result will be put into the dist_docker
directory, so
you can have different builds through docker and a local dev setup.
If you do not use any local dev setup and want to get the built files directly
into the dist
directory, just change the "$(pwd)"/dist_docker
in the volume
option to "$(pwd)"/dist
. (If you are wondering why inside the container we
copy everything from the dist
to the dist_docker
container: this is a
workaround, because the build process needs the dist
directory unlocked,
which is not the case if we bind it to a volume)
A more comprehensive setup in combination with other AuRa components can be found in the aura repository.
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 equivalent 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
Software Stack
This project is built with Vue.js. Take a look at the Guide or the API docs to find out more about the core framework.
On top of Vue we use vue-router for in-app routing, BootstrapVue for most of the generic UI components, Tailwind CSS for custom component styling, and Vuex for state management (with the latter most likely being subject to change in the future).
We use Vite as build system and dev server with little
custom configuration (see vite.config.js
).
Contributing
A lot of the code is still using the legacy Options API of Vue 2, which is possible through Vue v3’s compat mode (see @vue/compat). Feel free to re-implement components with the Composition API. New code should always use the Composition API.
If you’re in need for components or UX patterns that you’ve seen on other sites or seem generic to you, it’s always a good idea to look have a look at VueUse which comes with a lot of composables that are handy in everyday UI development. Unstyled components are available from headless ui if you need a specific UI component but need a custom design. For more generic ecosystem information you should visit awesome-vue and awesome-vue-3. If you add any new dependencies make sure they don’t rely on any behaviours from Vue 2 as we are in the process of migrating to a Vue 3-only setup.
Run npm run format
to automatically format your code or run npm run lint
to check it for errors. ESLint emits some warnings for existing code.
Please make sure that you don’t add code that produces any new warnings.