Awesome

<img src="/ez-client/src/main/resources/img/tech/ezLogo_512.png" width="100" alt="ez-Dashing"> ez-Dashing

ez-Dashing is a customizable free dashboard tool for agile development teams. The project is still in development but already usable for production. I am aware that many things could be improved, feel free to contribute !

/!\ Huge work still in progress, master is currently broken, only documentation (npm run doc) is available. I am currently doing a huge refactoring and try to create a pure json generic widget :)

Guidelines

Responsive
Configurable
Ready to use

Tech Stack

Demo

Online

The online demo shows a running dashboard (release 1.2.0) configured to consume online public API (without authentication). Some API are maybe out of date as the consequence the widgets are loading infinitely. For example, it seems it is not possible to call demo.qotilabs.com without authentitfication anymore, or maybe we should update the dashboard config.

The online demo is temporarily disabled.

From Docker Hub

The docker demo show a running dashboard (development build) configured to consume a mocked API. This demo is now the same as the online demo.

docker run --rm -it -p 8081:8081 --name ez-demo ylacaute/ez-dashing:demo

The first screenshots below is exactly what you should see.

Go on http://localhost:8081

Production

You can directly start to use ez-Dashing by pulling the production docker image. You just have to define your json configuration.

From Docker Hub

docker run --rm -itp 8080:8080 --name ez-dashing -v /ABSOLUTE/PATH/TO/CONFIG/DIR:/ez-config  ylacaute/ez-dashing:1.2.0

Go on http://localhost:8080

Please note that your config directory:

MUST be in absolute path for Docker
MUST contains 'dashboard.json' (check sample config directory in the project)
CAN also contains 'application.yml' in order to override Spring Boot config

From sources

DEPRECATED

If you need ez-Dashing in production but without Docker, you will have to package it manually. But keep in mind you should have no reason to start server like that, please use Docker for production.

# BUILD FOR PRODUCTION
./ez.sh build-prod

# START FOR PRODUCTION
./ez.sh start-prod <location_directory>

# More options here
./ez.sh -h

Documentation

The documentation web site can be started with the command below (WIP).

npm run doc

Available versions

Here are the available docker images:

ylacaute/ez-Dashing:latest (December 2019)
ylacaute/ez-Dashing:1.2.0 (December 2019)
ylacaute/ez-Dashing:demo (December 2019)

Release process

New release

This application do not use maven release plugin. The main reason is because no jar are published, but this plugin is not CI friendly anyway. Since Maven 3 we can use ${revision} in version which bring simplicity. See this good article.

Sample to release ez-Dashing version 1.3.0:

# Create the branch
git checkout -b 1.3

# Build the app
./ez.sh build-prod 1.3.0

# Build the docker image
./ez.sh create-docker-image 1.3.0

# Push the docker image
./ez.sh push-docker-image 1.3.0

# Git tag
git tag -a v1.3.0 -m "Release 1.3.0"

Front configuration

Define a dashboard.json configuration file, composed of the sections below:

env: global variables which can be used anywhere in the configuration
server: server config, you should have no reason to use that in production
theme: choose your favorite theme ("default", "black", etc)
dataSources: refreshable dataSources making REST call and mapping the result to properties
widgets: your widgets, usually attached to one or many dataSources. See widgets backlog to see available widgets.
avatars: declare some avatars for your team
thresholds: define the thresholds values which will impact the CSS rules
grid: mainly responsive configuration parameters of the grid

Server configuration

You can define a server configuration file application.yml to override Spring Boot configuration. However, this file is not mandatory.

Workflow

DataSources are regularly refreshed. When refreshed, REST responses are mapped to properties depending your configuration
Properties are then injected into the application state
Widgets are dumb components with properties defined in the configuration and the mapped properties of the dataSources they listen to
Widgets are re-rendered each time properties change

Why dataSources ?

User have a total control of REST requests and how data are mapped to the application
No more REST client dependencies: you build your own
One dataSource can serve many components (no request duplication)

Widgets backlog

Global backlog

Build the application

Requirements

Node 12
Java 8
Maven 3

Development

Most of the time, you will work with front-end only, your best option is then to start a mocked API and start the dev server.

Start the frontend

npm run serve

Hot reload: works for any kind of front sources change (js, sass, html...)
HMR: sadly, HMR is still not working. Feel free to create a PR and make it working !!

Start the mocked API (mock the backend)

npm run api

On mocks change (ez-client/api/mocks): you need to restart the mocked API
Verify all the chain without mocks: turn off the mocked API and start the back-end

If you just work on the backend, use maven as usual. Please notice that ez-Dashing is now based on Spring-Boot 2.2 which bring many breaking changes, please read the [Spring Boot 2.2 Release Notes](https://github.com/spring-projects /spring-boot/wiki/Spring-Boot-2.2-Release-Notes) for more information.

Build the back-end

mvn package

Start the back-end

# Inside the ez-server directory
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# If you want to change the location of the dashboard config
mvn spring-boot:run -Dspring-boot.run.profiles=dev -Dspring-boot.run.jvmArguments="-Dspring.config.additional-location
=<YOUR_CONFIG_LOCATION>"

If you don't use the dev profile, the spring.config.additional-location become mandatory. Please care about the path which must end with a / otherwise Spring will kick you out.

Start the back-end from IDEA Intellij

With dev profile: run the class EzDashingApplication with the vm arg -Dspring.profiles.active=dev
With custom location: run the class EzDashingApplication with the vm arg -Dspring.config.additional-location =<YOUR_DIR>

Production

The production build will generate a Spring Boot application by embedding the frontend inside the final fat jar. The frontend build must be triggered by the maven profile "prod". Without this profile, the Spring Application will not contain the frontend.

# Package the application with the frontend
mvn package -P prod

# Start the application
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dspring.config.additional-location=<YOUR_CONFIG_LOCATION>"

Code style

For frontend development, this project use the AirBnb code style with few changes:

no spaces on braces for import and object destructuring
allow empty objects {} in a single line
try catch: no new line on catch

You can use the .editorconfig or the CodingStyle.xml in this project.

FAQ

Error: Application does not start

Caused by: java.io.FileNotFoundException: @project.parent.basedir@/config/local/dashboard.json

Solution: You must first run maven to compile and do it again each time you modify the application.yml config because maven is in charge to generate some keys, @project.parent.basedir@ in this case.

mvn compile

Error: When building the application, we can see that front logs are marked in ERROR by Maven (even if all tests are passing)

Solution This is not a real but a known Jest bug, Jest writes on stderr instead of stdout, as the result Maven mark them on error.

Error: Error: <rect> attribute height: A negative value is not valid.

Solution: Just resize chart widget, when the widget is too small, it can generated negative values.

Browser compatibility:

Chromium : good (only last version tested)
Firefox : good (only last version tested)
Safari : not tested
Internet Explorer not tested

License

ez-Dashing is licensed under the Apache 2 license.

Screenshots

Screenshot